Setting the Cacheability of a Page

The cacheability of a page or user control defines which HTTP 1.1 Internet devices a document can be cached on. These devices include the client making the request, the Web server responding to the request, and any cache-capable devices, such as proxy servers, that are in the request or response stream. When a Web server sends a response, it passes a Cache-Control HTTP header that, among other things, defines the devices on which the document can be cached. ASP.NET defines these values in the HttpCacheability enumeration. This enumeration has six values, four that map directly to Cache-Control HTTP header settings and two special values called HttpCacheability.ServerAndPrivate and HttpCacheability.ServerAndNoCache. ServerAndPrivate allows a response to be cached only on the origin server and the requesting client. ServerAndNoCache allows a response to be cached only on the origin server.

Depending on the needs of your application, you may choose to define which devices can and cannot cache specific pages. For example, you would want the cacheability settings for a user logon page to be different from those for a page that displays a selection of products from a catalog. In the case of the logon page, for security reasons you would want to cache the page on only the server, while the catalog page could probably be cached on any cache-capable device.

You can set the cacheability of a page's output declaratively by including a Location attribute in the @ OutputCache directive and specifying one of the OutputCacheLocation enumeration values.

You can set the cacheability of a page's output programmatically by using the HttpCachePolicy.SetCacheability method to specify an HttpCacheability value for the page. The method is accessible through the HttpResponse.Cache property, which is accessible using Response.Cache syntax in the page's code-behind class or code-declaration block.

Note   If you use the @ OutputCache directive to set your page's cacheability, you must declare the Duration and VaryByParam attributes along with the Location attribute. The Duration attribute must be set to a value larger than zero. You can set the VaryByParam attribute to None if you do not want to use the functionality it provides. For more information, see Setting Expirations for Page Caching and Caching Multiple Versions of a Page.

In contrast, if you use the HttpCachePolicy class to set cacheability, you do not need to set expirations if you have established a validation policy.

To set a page's cacheability declaratively

1. Include an @ OutputCache directive in the .aspx file and define the required Duration and VaryByParam attributes.

2. Include a Location attribute in the @ OutputCache directive and define its value as one of the supported values. These include Any, Client, Downstream, Server, or None.

   Note   The default is Any. If you do not define a Location attribute, the page output can be cached on all cache-capable network applications that are involved in the response. These include the requesting client, the origin server, and any proxy servers through which the response passes.

To set a page's cacheability programmatically

• In the page's code-declaration block or code-behind class file, use Response.Cache syntax to access the HttpCachePolicy.SetCacheability method. The following code sets the Cache-Control HTTP header to Public.

  Response.Cache.SetCacheability(HttpCacheability.Public);
  [Visual Basic]
  Response.Cache.SetCacheability(HttpCacheability.Public)
  

  Note If you set cacheability to HttpCacheability.NoCache or HttpCacheability.ServerAndNoCache, the requesting client will not cache pages in its History folder. For example, any time a user clicks a back or forward button, a new version of the response will be requested. You can override this behavior by setting the HttpCachePolicy.SetAllowResponseInBrowserHistory method to true.

  Response.Cache.SetAllowResponseInBrowserHistory(true);
  [Visual Basic]
  Response.Cache.SetAllowResponseInBrowserHistory(true)
  

  If you set cacheability to any value other than NoCache or ServerAndNoCache, ASP.NET ignores the value set by the SetAllowResponseInBrowserHistory method.

See Also

Caching ASP.NET Pages | HttpCacheability Enumeration | HttpResponse Class | @ OutputCache Directive