---

This section details on the original issue you should resolve

<issue_title>CacheExtensions.TryGetValue documentation and behavior are ambiguous for type mismatches (key present with incompatible type returns false)</issue_title>
<issue_description>### Description

When using Microsoft.Extensions.Caching.Memory.IMemoryCache with the generic extension method:

IMemoryCachecache= ...;cache.Set("k",(object)"string-value");// Under the hood: IMemoryCache.TryGetValue("k", out object? obj) == true// But the generic extension below returns false because obj is not int.boolfound=cache.TryGetValue<int>("k",outvari);// found == false

This reveals two problems:

1. Behavioral ambiguity for instrumentation / decorators
   A decorator that instrumentsIMemoryCache.TryGetValue(object, out object?) will observe a hit (returnstrue because the key exists), while the calling code usingCacheExtensions.TryGetValue<T> observes a miss (false due to type mismatch). This makes consistent hit/miss accounting impossible when consumers use the generic extension.

2. Documentation mismatch
   The current docs forCacheExtensions.TryGetValue<T> say: “true if the key was found; false otherwise.” In the scenario above, the key is found but the method returnsfalse. The real behavior is closer to:

“Returnstrue if the key was found and the stored value is of typeTItem (otherwise returnsfalse and sets return value todefault).”

Reproduction Steps

usingMicrosoft.Extensions.Caching.Memory;varcache=newMemoryCache(newMemoryCacheOptions());// Store as object/stringcache.Set("key",(object)"abc");// 1) Non-generic call sees "found"varfoundObj=cache.TryGetValue("key",outobject?obj);// true// 2) Generic extension reports "not found" for incompatible typevarfoundInt=cache.TryGetValue<int>("key",outvari);// false// Instrumented decorators counting "hits" in IMemoryCache.TryGetValue(object, out object?)// will count the first as a hit, while callers using the generic extension see a miss.Console.WriteLine((foundObj,foundInt));// (True, False)

Expected behavior

Docs and API guidance should clarify that the generic overload only returns true when the value existsand is compatible withTItem.

Expected behavior

• CacheExtensions.TryGetValue<T> documentation should explicitly state:

"Returns true if the key was found and the stored value can be cast toTItem. Returns false otherwise (including type mismatches)."

• Guidance should explain implications for decorators/instrumented caches.
• (Optional stretch) Consider an additional API if presence-vs-type disambiguation is needed, but a doc fix alone would resolve most confusion.

Actual behavior

• Non-genericIMemoryCache.TryGetValue(object, out object?) returnstrue if the key is present.
• GenericCacheExtensions.TryGetValue<T> returnsfalse if the type does not match, even when the key exists.
• Documentation implies only the first behavior ("true if the key was found”'), without mention of the type check.

Regression?

No. This appears to be the behavior since the generic extension was introduced. The issue is a documentation mismatch and missing guidance rather than a runtime regression

Known Workarounds

• Use the non-generic overload when consistent hit/miss metrics are required in decorators.
• Or, after a generic call returns false, double-check with the non-generic overload if you need to distinguish "key present with wrong type" from "key absent" scenario.

Configuration

No response

Other information

No response</issue_description>

<agent_instructions>Please fix the documentation based on the feedback provided in the issue.</agent_instructions>

Comments on the Issue (you are@copilot in this section)

@jozkee@rjmurillo thank you for reporting this. Your workaround is correct, and the documentation should be clearer about the type check in the "found" logic.