How does `HybridCache` "Remove cache entries by tag" work?

[khteh]

Description

What does this statement in https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid?view=aspnetcore-10.0#remove-cache-entries-by-tag mean?

"when receiving data with such tags, the data is treated as a cache-miss from both the local and remote cache."

Page URL

https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/caching/hybrid.md

Document ID

fdd3c6f2-c3f4-6fc7-0928-0b18ba9297cf

Platform Id

77e7a2f3-9ddb-06e2-9b46-7ddeb411f8c4

Article author

@tdykstra

Metadata

• ID: fdd3c6f2-c3f4-6fc7-0928-0b18ba9297cf
• PlatformId: 77e7a2f3-9ddb-06e2-9b46-7ddeb411f8c4
• Service: aspnet-core
• Sub-service: performance

Related Issues

---

Associated WorkItem - 554581

[wadepickett]

@khteh, thanks for this issue.

The author will be along to address this.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-02-07
Issue: 36757
Model: GitHub Copilot

---

Issue Analysis: Clarify how HybridCache tag-based invalidation works ("logical" operation)

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The issue reports that the documentation's explanation of tag-based cache invalidation in the "Remove cache entries by tag" section is confusing. Specifically, the sentence:

"when receiving data with such tags, the data is treated as a cache-miss from both the local and remote cache."

is unclear to readers. The issue author is asking what this means in practice, and the current wording does not sufficiently explain the underlying mechanism.

After examining the actual source code implementation, the mechanism works as follows:

1. When RemoveByTagAsync is called, HybridCache records the current timestamp against that tag (both locally and in the L2/distributed backend).
2. It does not iterate through and delete the actual cached values from IMemoryCache or IDistributedCache.
3. When a subsequent GetOrCreateAsync retrieves a cached value, HybridCache checks the value's creation timestamp against the tag's invalidation timestamp. If the value was created before the tag was invalidated, the value is considered expired (i.e., treated as a cache miss), even though the value still physically exists in the cache stores.
4. The factory method is then called to get fresh data, effectively treating the stale entry as if it didn't exist.

The current documentation explains this as a "logical operation" but doesn't describe the timestamp-based mechanism, which would help readers understand why the data isn't physically removed and what "treated as a cache-miss" actually means.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/performance/caching/hybrid.md	112-127	"Remove cache entries by tag" and "Removing all cache entries"

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential Documentation Updates

File: aspnetcore/performance/caching/hybrid.md
Location: Lines 120-123 (the paragraph explaining tag-based invalidation as a "logical" operation)
Type: Replacement / Expansion of existing paragraph

Current content (lines 120-123):

Remove all entries for a specified tag by calling <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache.RemoveByTagAsync%2A> with the tag value. An overload lets you specify a collection of tag values.

Neither `IMemoryCache` nor `IDistributedCache` has direct support for the concept of tags, so tag-based invalidation is a *logical* operation only. It doesn't actively remove values from either local or distributed cache. Instead, it ensures that when receiving data with such tags, the data is treated as a cache-miss from both the local and remote cache. The values expire from `IMemoryCache` and `IDistributedCache` in the usual way based on the configured lifetime.

Suggested direction:

Remove all entries for a specified tag by calling <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache.RemoveByTagAsync%2A> with the tag value. An overload lets you specify a collection of tag values.

Neither `IMemoryCache` nor `IDistributedCache` has direct support for the concept of tags, so tag-based invalidation is a *logical* operation, not a physical deletion. When `RemoveByTagAsync` is called, `HybridCache` records the current time as the invalidation timestamp for that tag. The cached values themselves are **not** actively removed from either the local (in-memory) or distributed cache stores.

Instead, when a subsequent call to `GetOrCreateAsync` retrieves a cached value, `HybridCache` compares the value's creation time against the tag's invalidation timestamp. If the value was created *before* the tag was invalidated, `HybridCache` treats the value as a cache miss—even though the data still physically exists in the underlying cache stores. The factory method is then called to fetch fresh data. The old values remain in `IMemoryCache` and `IDistributedCache` until they expire naturally based on their configured lifetime.

This rewrite:

• Explains what actually happens when RemoveByTagAsync is called (a timestamp is recorded).
• Explains how subsequent reads detect invalidation (timestamp comparison).
• Clarifies why data isn't physically deleted.
• Clarifies what "treated as a cache-miss" means in practice (the factory is called again).

🎯 Suggested Action Plan

For documentation team review

1. Review file: aspnetcore/performance/caching/hybrid.md

   • Navigate to: Lines 120-123
   • Section: "Remove cache entries by tag"
   • Consider: Rewriting the paragraph to explain the timestamp-based logical invalidation mechanism more clearly

2. Review source code for accuracy: DefaultHybridCache.TagInvalidation.cs

   • Navigate to: Lines 24-34 — RemoveByTagAsync records the timestamp
   • Navigate to: Lines 36-66 — IsValid checks timestamp to determine if cache item is stale
   • Confirm that the suggested documentation text accurately reflects the implementation

⚠️ Review Considerations

• Verify the suggested wording doesn't expose too much internal implementation detail that could change across versions — aim for the conceptual "timestamp-based logical invalidation" level of detail.
• The existing NOTE block at lines 195-196 in the "Cache storage" section already mentions that tag/key invalidation on one server doesn't affect in-memory cache on other servers — ensure consistency with any changes.
• This applies to ASP.NET Core 9.0+ (the monikerRange for this article).

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid?view=aspnetcore-10.0
• Content source: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/caching/hybrid.md
• HybridCache tag invalidation source code: https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.TagInvalidation.cs
• Related product issue (tag invalidation design): HybridCache - tags and invalidation extensions#7098

[wadepickett]

@tdykstra for triage. Note that the latest triage analysis was run and placed in the discussion.

[khteh]

3. When a subsequent GetOrCreateAsync retrieves a cached value, HybridCache checks the value's creation timestamp against the tag's invalidation timestamp. If the value was created before the tag was invalidated, the value is considered expired (i.e., treated as a cache miss), even though the value still physically exists in the cache stores.

4. The factory method is then called to get fresh data, effectively treating the stale entry as if it didn't exist.

How practical is this implementation that the GetOrCreateAsync fetches fresh values from the underlying store everytime between RemoveByTagAsync and the actual expiration of the cache entries? Doesn't it defeat both the purpose of having any cache at all and the original intention of the user to RemoveByTagAsync the cache entries and the expection that a fresh values will be cached (the factory called just once after the RemoveByTagAsync) the next time it is accessed?

[wadepickett]

@khteh, great question! The concern you're raising is understandable based on the wording, but the implementation actually does not call the factory every time after RemoveByTagAsync. The fresh data fetched after invalidation is re-cached and served from cache on subsequent requests. Here's the key flow:

1. RemoveByTagAsync("someTag") is called : HybridCache records the current time as the invalidation timestamp for that tag. Nothing is physically deleted from L1 or L2.

2. First GetOrCreateAsync after invalidation : HybridCache finds the old cached value, but sees its CreationTimestamp is ≤ the tag's invalidation timestamp → treated as a cache miss. The factory is called to fetch fresh data.

3. The fresh data is stored as a new cache entry with a new CreationTimestamp (which is now — i.e., after the tag invalidation timestamp). The new entry is written to both L1 (in-memory) and L2 (distributed cache). You can see this in the source code : the implementation even handles the edge case where the invalidation and the new write happen in the same measured instant by injecting an artificial delay to ensure the new timestamp is strictly greater than the invalidation timestamp.

4. Second and all subsequent GetOrCreateAsync calls HybridCache finds the new cached value. Its CreationTimestamp is after the tag invalidation timestamp → cache hit. The factory is not called. The cached value is returned directly.

The factory is called exactly once after RemoveByTagAsync : on the next GetOrCreateAsync. That call produces a fresh value with a creation timestamp that is strictly after the invalidation timestamp, so all subsequent reads treat it as a valid cache hit. Caching behavior is fully preserved; it does not defeat the purpose of the cache.

The earlier triage summary's phrasing may have been a bit ambiguous on this point : the timestamp comparison only invalidates entries created before the invalidation, not entries created after it.

( @tdykstra for triage )

[khteh]

Are all processes aware of the invalidation timestamp? And which CreationTimestamp does it refer to? If it is the CreationTimestamp of the L1 cache of this specific process alone, wouldn't there be a race condition? Here is the scenario:

P1 calls RemoveByTagAsync("someTag")
P2 calls GetOrCreateAsync because it's the first time it runs a specific business logic that requires that cache key/entry -> CreationTimestamp of the L1 cache with tag someTag. If it updates the CreationTimestamp of the L2 cache as well, what happens the next time P1 calls GetOrCreateAsync?

Somehow related to #36758