In this article

Response caching reduces the number of requests a client or proxy makes to a web server. Response caching also reduces the amount of work the web server performs to generate a response. Response caching is controlled by headers that specify how you want client, proxy, and middleware to cache responses.

HTTP-based response caching

The HTTP 1.1 Caching specification describes how Internet caches should behave. The primary HTTP header used for caching is Cache-Control, which is used to specify cache directives. The directives control caching behavior as requests make their way from clients to servers and as reponses make their way from servers back to clients. Requests and responses move through proxy servers, and proxy servers must also conform to the HTTP 1.1 Caching specification.

On requests: A cache must not use a stored response to satisfy the request. Note: The origin server re-generates the response for the client, and the middleware updates the stored response in its cache.

On responses: The response must not be used for a subsequent request without validation on the 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. It isn't necessarily a way to control the load on an origin server.

There's no current developer control over this caching behavior when using the Response Caching Middleware because the middleware adheres to the official caching specification. Future enhancements to the middleware will permit configuring the middleware to ignore a request's Cache-Control header when deciding to serve a cached response. This will offer you an opportunity to better control the load on your server when you use the middleware.

Other caching technology in ASP.NET Core

In-memory caching

In-memory caching uses server memory to store cached data. This type of caching is suitable for a single server or multiple servers using sticky sessions. Sticky sessions means that the requests from a client are always routed to the same server for processing.

Distributed Cache

Use a distributed cache to store data in memory when the app is hosted in a cloud or server farm. The cache is shared across the servers that process requests. A client can submit a request that's handled by any server in the group if cached data for the client is available. ASP.NET Core offers SQL Server and Redis distributed caches.

Distributed Cache Tag Helper

You can cache the content from an MVC view or Razor Page in distributed cloud or web farm scenarios with the Distributed Cache Tag Helper. The Distributed Cache Tag Helper uses SQL Server or Redis to store data.

ResponseCache attribute

The ResponseCacheAttribute specifies the parameters necessary for setting appropriate headers in response caching.

Warning

Disable caching for content that contains information for authenticated clients. Caching should only be enabled for content that doesn't change based on a user's identity or whether a user is signed in.

VaryByQueryKeys varies the stored response by the values of the given list of query keys. When a single value of * is provided, the middleware varies responses by all request query string parameters. VaryByQueryKeys requires ASP.NET Core 1.1 or later.

The Response Caching Middleware must be enabled to set the VaryByQueryKeys property; otherwise, a runtime exception is thrown. There isn't a corresponding HTTP header for the VaryByQueryKeys property. The property is an HTTP feature handled by the Response Caching Middleware. For the middleware to serve a cached response, the query string and query string value must match a previous request. For example, consider the sequence of requests and results shown in the following table.

Request

Result

http://example.com?key1=value1

Returned from server

http://example.com?key1=value1

Returned from middleware

http://example.com?key1=value2

Returned from server

The first request is returned by the server and cached in middleware. The second request is returned by middleware because the query string matches the previous request. The third request isn't in the middleware cache because the query string value doesn't match a previous request.

The ResponseCacheAttribute is used to configure and create (via IFilterFactory) a ResponseCacheFilter. The ResponseCacheFilter performs the work of updating the appropriate HTTP headers and features of the response. The filter:

Removes any existing headers for Vary, Cache-Control, and Pragma.

Writes out the appropriate headers based on the properties set in the ResponseCacheAttribute.

Updates the response caching HTTP feature if VaryByQueryKeys is set.

Vary

This header is only written when the VaryByHeader property is set. It's set to the Vary property's value. The following sample uses the VaryByHeader property:

Location and Duration

To enable caching, Duration must be set to a positive value and Location must be either Any (the default) or Client. In this case, the Cache-Control header is set to the location value followed by the max-age of the response.

Note

Location's options of Any and Client translate into Cache-Control header values of public and private, respectively. As noted previously, setting Location to None sets both Cache-Control and Pragma headers to no-cache.

Below is an example showing the headers produced by setting Duration and leaving the default Location value:

Cache profiles

Instead of duplicating ResponseCache settings on many controller action attributes, cache profiles can be configured as options when setting up MVC in the ConfigureServices method in Startup. Values found in a referenced cache profile are used as the defaults by the ResponseCache attribute and are overridden by any properties specified on the attribute.