This documentation is archived and is not being maintained.

Caching Versions of a Page, Based on HTTP Headers

The @ OutputCache directive's VaryByHeader attribute and the HttpCachePolicy.VaryByHeaders property allow you to cache multiple versions of a page, dependent on the value of an HTTP header that you specify. You can specify a single header, multiple headers, or all headers passed to your application, when the page is requested. Depending upon the header or combination of headers you choose, multiple versions of the page's output is cached.

To cache versions of a page declaratively, based on HTTP header values

  1. Include an @ OutputCache directive with the required Duration and VaryByParam attributes. The Duration attribute must be set to any integer greater than zero. If you do not want to use the functionality provided by the VaryByParam attribute, set its value to None.
  2. Include the VaryByHeader attribute in the body of the @ OutputCache directive, with its value set to the name of the HTTP header that you want to vary the cache content by. The following example sets versions of a page to be cached, based on the value passed with the Accept-Language HTTP header.
    <%@ OutputCache Duration="60" VaryByParam="None" VaryByHeader="Accept-Language" %>
    Note   If you want to vary the cached content by multiple headers, include a semicolon delimited list of header names. If you want to vary the cached content by all header values, set the VaryByHeader attribute equal to an asterisk (*).

To cache versions of a page programmatically, based on an HTTP header value

  1. In the page's code-declaration block or code-behind class, use Response.Cache syntax to set the expiration and visibility policies for the cached page content. You accomplish this using the HttpCachePolicy.SetExpires and HttpCachePolicy.SetCacheability methods, respectively.
  2. In the same code, specify the header name as the argument for the VaryByHeaders property, and set the property to true. The following code caches multiple versions of a page when requests arrive at the server that have different values assigned to the Accept-Language HTTP header.
    Response.Cache.VaryByHeaders["Accept-Language"] = true;
    [Visual Basic]
    Response.Cache.VaryByHeaders("Accept-Language") = true
    Note   If you want to vary the cache by multiple header values, set the VaryByHeaders property argument to a semicolon delimited list of valid HTTP header names. If you want to vary the pages in the cache by all HTTP header names, use the VaryByUnspecifiedParameters method.

The following discussion assumes that a page's output is cached by using the code from one of the procedures in this topic.

Four requests arrive for the page with the following Accept-Language headers.


Since the second and fourth requests have the same Accept-Language HTTP header values, only the response generated for the first request is cached. The other two Accept-Language values generate page output versions that are also cached. A total of three documents are rendered and cached for these four requests. Any further requests for the page with the same Accept-Language values are satisfied from the output cache until the cached pages expire. This example demonstrates how to cache the page output of globalized content, depending upon the locale settings for the requesting browser.

See Also

@ OutputCache | Caching ASP.NET Pages | HttpApplication.GetVaryByCustomString Method | VaryByParams | VaryByHeaders