Light Freshness Edit: ASP.NET - Caching by GitHubber17 · Pull Request #37087 · dotnet/AspNetCore.Docs

GitHubber17 · 2026-05-01T06:07:29Z

This PR contains light freshness updates to five articles:

Overview of caching in ASP.NET Core (+1 include)
Cache in-memory in ASP.NET Core
Distributed caching in ASP.NET Core (+1 include)
Output caching middleware in ASP.NET Core
Response caching in ASP.NET Core

For details, see ADO request 568764.

Internal previews

📄 File	🔗 Preview link
aspnetcore/performance/caching/distributed.md	customer intent: As an ASP.NET developer, I want to use an ASP.NET Core distributed cache, so I can improve app performance and scalability.
aspnetcore/performance/caching/memory.md	Cache in-memory in ASP.NET Core
aspnetcore/performance/caching/output.md	customer intent: As an ASP.NET developer, I want to configure output caching middleware in ASP.NET Core, so I can use output caching in my apps.
aspnetcore/performance/caching/overview.md	Overview of caching in ASP.NET Core
aspnetcore/performance/caching/response.md	aspnetcore/performance/caching/response

GitHubber17 · 2026-05-01T06:27:40Z

@tdykstra - Refreshed topics for your review. See the top comment for details.

Cc @cmastr @wadepickett

wadepickett

Reviewed. Great work! A few minor items suggested.
I will wait for @tdykstra to review before this is merged since he owns these topics.

GitHubber17 · 2026-05-01T16:58:13Z

+The output caching middleware can be used in all types of ASP.NET Core apps: [Minimal APIs](xref:fundamentals/minimal-apis), [Web API with controllers](xref:web-api/index), [MVC](xref:mvc/overview), and [Razor Pages](xref:razor-pages/index). Code examples are provided for Minimal APIs and controller-based APIs. The controller-based API examples show how to use attributes to configure caching. These attributes can also be used in MVC and Razor Pages apps.

-The code examples refer to a [Gravatar class](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/caching/output/samples/7.x/Gravatar.cs) that generates an image and provides a "generated at" date and time. The class is defined and used only in [the sample app](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/performance/caching/output/samples/7.x). Its purpose is to make it easy to see when cached output is being used. For more information, see [How to download a sample](xref:fundamentals/index#how-to-download-a-sample) and [Preprocessor directives in sample code](xref:index#preprocessor-directives-in-sample-code).
+The code examples refer to a [Gravatar class](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/caching/output/samples/7.x/Gravatar.cs) that generates an image and provides a "generated at" date and time. The class is defined and used only in [the sample app](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/performance/caching/output/samples/7.x). Its purpose is to make it easy to see when cached output is being used. For more information, see [How to download a sample](xref:fundamentals/index#how-to-download-a-sample) and [Preprocessor directives](/dotnet/csharp/fundamentals/program-structure/preprocessor-directives).


@wadepickett - The <xref:index#preprocessor-directives-in-sample-code> link redirects to the top of the Overview page, which provides no information about preprocessor directives. I tried to find a replacement. Can you identify a more appropriate link?

Co-authored-by: Wade Pickett <wpickett@microsoft.com>

wadepickett · 2026-05-01T17:37:51Z

I deleted my suggestion for the link change for preprocessor-directives, but that also deleted the conversation history. So I'll note it here:

The link I suggested resolved to the top of the overview page which made it useless. At some point we deleted that section in the overview. Sorry to mess that up. You aleady had the best link we can provide.

Follow up for me: I will also look through the entire repo to see if that original outdated link is anywhere else and get it fixed. Thanks for finding this issue to begin with!

wadepickett

Approved. Great work, thanks!

@tdykstra will also provide a review and then merge.

tdykstra

Looks good.
One important update -- there's a new Azure Redis service

tdykstra · 2026-05-01T14:55:05Z

+  Serialization is configured as part of registering the service, with support for type-specific and generalized serializers via the `WithSerializer` and `WithSerializerFactory` methods, chained from the `AddHybridCache` call. By default, the service handles `string` and `byte[]` types internally, and uses the `System.Text.Json` namespace for everything else. `HybridCache` can be configured for other types of serializers, such as protobuf or XML.

-To see the relative simplicity of the `HybridCache` API, compare code that uses it to code that uses `IDistributedCache`. Here's an example of what using `IDistributedCache` looks like:
+To see the relative simplicity of the `HybridCache` API, compare code that uses it to code that uses the `IDistributedCache` interface. Here's an example of a configuration with the `IDistributedCache` interface:


Please revert line 20 to the original text.

tdykstra · 2026-05-01T15:00:56Z

-* <xref:performance/caching/hybrid>
-* [Hybrid Cache API proposal (`dotnet/aspnetcore` #54647)](https://github.com/dotnet/aspnetcore/issues/54647)
-* [`HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Abstractions/Hybrid/HybridCache.cs,8c0fe94693d1ac8d) <!--keep-->
+* [HybridCache library in ASP.NET Core](xref:performance/caching/hybrid)


The original form of link here is fine. It gets the link text from the title of the article.

tdykstra · 2026-05-01T15:31:01Z

+An app configures the cache implementation with a <xref:Microsoft.Extensions.Caching.StackExchangeRedis.RedisCache> instance by calling the <xref:Microsoft.Extensions.DependencyInjection.StackExchangeRedisCacheServiceCollectionExtensions.AddStackExchangeRedisCache%2A> method. For [output caching](xref:performance/caching/output#cache-storage), use the <xref:Microsoft.Extensions.DependencyInjection.StackExchangeRedisOutputCacheServiceCollectionExtensions.AddStackExchangeRedisOutputCache%2A> method.

-We recommend production apps use the Distributed Redis Cache because it's the most performant. For more information see [Recommendations](#recommendations).
+1. Create an Azure Cache for Redis.


Suggested change

1. Create an Azure Cache for Redis.

1. Create an instance of Azure Cache for Redis.

tdykstra · 2026-05-01T15:32:09Z

+1. Create an Azure Cache for Redis.

-[Redis](https://redis.io/) is an open source in-memory data store, which is often used as a distributed cache.  You can configure an [Azure Cache for  Redis](/azure/azure-cache-for-redis/cache-overview) for an Azure-hosted ASP.NET Core app, and use an Azure Cache for Redis for local development.
+1. Copy the Primary connection string (StackExchange.Redis) to [Configuration](xref:fundamentals/configuration/index).


Suggested change

1. Copy the Primary connection string (StackExchange.Redis) to [Configuration](xref:fundamentals/configuration/index).

1. Copy the primary connection string (StackExchange.Redis) to [Configuration](xref:fundamentals/configuration/index).

tdykstra · 2026-05-01T15:51:16Z

-     * Azure: Save the connection string in a secure store such as [Azure Key Vault](/azure/key-vault/general/overview)
+   - **For Azure**: Save the connection string in a secure store such as [Azure Key Vault](/azure/key-vault/general/overview).

 The following code enables the Azure Cache for Redis:


change Azure Cache for Redis to Azure Managed Redis and link to
the Azure Managed Redis overview page
Azure Cache for Redis is retiring

tdykstra · 2026-05-01T16:11:20Z

+When the sample app starts, the <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> instance is injected into the _Program.cs_ file. The current time is cached by using the <xref:Microsoft.Extensions.Hosting.IHostApplicationLifetime> interface. (For more information, see [.NET Generic Host: IHostApplicationLifetime](xref:fundamentals/host/generic-host#ihostapplicationlifetime).)

 [!code-csharp[](~/performance/caching/distributed/samples/6.x/DistCacheSample/Program.cs?name=snippet_Configure)]

-The sample app injects <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> into the `IndexModel` for use by the Index page.
+The sample app injects the <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> instance into the `IndexModel` object for use by the Index page.


Good catch here and throughout these docs, adding instance and object, etc. where appropriate instead of the API reference by itself.

tdykstra · 2026-05-01T16:35:17Z

+* [Cache in-memory in ASP.NET Core](xref:performance/caching/memory)
+* [Detect changes with change tokens in ASP.NET Core](xref:fundamentals/change-tokens)
+* [Response caching in ASP.NET Core](xref:performance/caching/response)
+* [Response caching middleware in ASP.NET Core](xref:performance/caching/middleware)
+* [Host ASP.NET Core in a web farm](xref:host-and-deploy/web-farm)


Quite a few links were removed. I would like to keep the ones that people might otherwise not think of looking for and drop those that are nearby in the TOC.

tdykstra · 2026-05-01T18:48:34Z

+The [RFC 9111: HTTP Caching (Section 5.2. Cache-Control)](https://www.rfc-editor.org/rfc/rfc9111#field.cache-control) specification requires a cache to honor a valid `Cache-Control` header sent by the client. A client can make requests with a `no-cache` header value and force the server to generate a new response for every request.

-Always honoring client `Cache-Control` request headers makes sense if you consider the goal of HTTP caching. Under the official specification, caching is meant to reduce the latency and network overhead of satisfying requests across a network of clients, proxies, and servers. It isn't necessarily a way to control the load on an origin server.
+Always honoring client `Cache-Control` request headers makes sense if you consider the goal of HTTP caching. Under the official specification, caching is meant to reduce the latency and network overhead of satisfying requests across a network of clients, proxies, and servers. The approach isn't necessarily a way to control the load on an origin server.


"It" here most likely refers back to "caching" in "caching is meant to reduce..."

"The approach" doesn't fit as well with what comes before or what comes after.

The requested change would have taken us out of the scope of light freshness edit. we will save the Redis change for another issue.

tdykstra

Approved, will merge when comments are addressed., except ignore the Redis service change.

GitHubber17 · 2026-05-05T18:20:40Z

@tdykstra - Thank you for your review. I applied your requested changes and held off on changes related to comments about changing the Azure Redis service.

GitHubber17 added 2 commits April 30, 2026 23:05

refresh content

6f648ec

edits

8de2c29

GitHubber17 marked this pull request as ready for review May 1, 2026 06:26

GitHubber17 requested a review from tdykstra as a code owner May 1, 2026 06:26

wadepickett reviewed May 1, 2026

View reviewed changes

Comment thread aspnetcore/performance/caching/output.md Outdated

wadepickett reviewed May 1, 2026

View reviewed changes

Comment thread aspnetcore/performance/caching/response.md Outdated

wadepickett reviewed May 1, 2026

View reviewed changes

Comment thread aspnetcore/performance/caching/response.md Outdated

wadepickett reviewed May 1, 2026

View reviewed changes

Comment thread aspnetcore/performance/caching/distributed.md Outdated

wadepickett requested changes May 1, 2026

View reviewed changes

GitHubber17 commented May 1, 2026

View reviewed changes

Apply suggestions from code review

5b82897

Co-authored-by: Wade Pickett <wpickett@microsoft.com>

GitHubber17 requested a review from wadepickett May 1, 2026 17:02

wadepickett approved these changes May 1, 2026

View reviewed changes

tdykstra previously requested changes May 1, 2026

View reviewed changes

tdykstra self-requested a review May 1, 2026 22:05

tdykstra approved these changes May 1, 2026

View reviewed changes

add edits after code review

0beb9f5

	1. Create an Azure Cache for Redis.
	1. Create an instance of Azure Cache for Redis.

	1. Copy the Primary connection string (StackExchange.Redis) to [Configuration](xref:fundamentals/configuration/index).
	1. Copy the primary connection string (StackExchange.Redis) to [Configuration](xref:fundamentals/configuration/index).

Conversation

GitHubber17 commented May 1, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Internal previews

Uh oh!

GitHubber17 commented May 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wadepickett left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wadepickett commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wadepickett left a comment

Choose a reason for hiding this comment

Uh oh!

tdykstra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdykstra left a comment

Choose a reason for hiding this comment

Uh oh!

GitHubber17 commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

GitHubber17 commented May 1, 2026 •

edited by github-actions Bot

Loading

wadepickett commented May 1, 2026 •

edited

Loading