@ OutputCache

  • Article

Declaratively controls the output caching policies of an ASP.NET page or a user control contained in a page. For more information about the output cache, see ASP.NET Caching Features.

<%@ OutputCache Duration="#ofseconds" Location="Any | Client | Downstream | Server | None" Shared="True | False" VaryByControl="controlname" VaryByCustom="browser | customstring" VaryByHeader="headers" VaryByParam="parametername" %>

Attributes

  • Duration
    The time, in seconds, that the page or user control is cached. Setting this attribute on a page or user control establishes an expiration policy for HTTP responses from the object and will automatically cache the page or user control output.

    Note   This attribute is required. If you do not include it, a parser error occurs.

  • Location
    One of the OutputCacheLocation enumeration values. The default is Any.

    CAUTION   This attribute is not supported for @ OutputCache directives included in user controls (.ascx files).

  • Shared
    A Boolean value that determines whether user control output can be shared with multiple pages. The default is false. For more information, see the Remarks section.

    Note   This attribute is not supported for @ OutputCache directives included in ASP.NET pages (.aspx files).

  • VaryByCustom
    Any text that represents custom output caching requirements. If this attribute is given a value of browser, the cache is varied by browser name and major version information. If a custom string is entered, you must override the HttpApplication.GetVaryByCustomString method in your application's Global.asax file.

  • VaryByHeader
    A semicolon-separated list of HTTP headers used to vary the output cache. When this attribute is set to multiple headers, the output cache contains a different version of the requested document for each specified header.

    Note   Setting the VaryByHeader attribute enables caching items in all HTTP 1.1 caches, not just the ASP.NET cache. This attribute is not supported for @ OutputCache directives in user controls.

  • VaryByParam
    A semicolon-separated list of strings used to vary the output cache. By default, these strings correspond to a query string value sent with GET method attributes, or a parameter sent using the POST method. When this attribute is set to multiple parameters, the output cache contains a different version of the requested document for each specified parameter. Possible values include none, *, and any valid query string or POST parameter name.

    CAUTION   This attribute is required when you output cache ASP.NET pages. It is required for user controls as well unless you have included a VaryByControl attribute in the control's @ OutputCache directive. A parser error occurs if you fail to include it. If you do not want to specify a parameter to vary cached content, set the value to none. If you want to vary the output cache by all parameter values, set the attribute to *.

  • VaryByControl
    A semicolon-separated list of strings used to vary a user control's output cache. These strings represent the ID property values of ASP.NET server controls declared in the user control. For more information, see Caching Portions of an ASP.NET Page.

    Note   This attribute is required in a user control @ OutputCache directive unless you have included a VaryByParam attribute. This attribute is not supported for @ OutputCache directives in ASP.NET pages.

Remarks

Setting values for the page output cache is the same as manipulating the HttpCachePolicy.SetExpires and HttpCachePolicy.SetCacheability methods through the HttpResponse.Cache property. Setting the VaryByParam attribute when creating a user control implements partial-page caching for that control.

If a Web Forms page requires authorization to be viewed by a user, the output cache sets the Cache-Control HTTP header to private. For more information on all these subjects, see Caching ASP.NET Pages.

If you set the Shared attribute to true, cached user control output can be accessed by multiple Web Forms pages. If you do not set it to true, the default behavior is to cache one version of user control output for each page that contains that user control. You can potentially save a significant amount of memory by enabling the Shared attribute. For more information, see Caching Portions of an ASP.NET Page.

Example

The following example demonstrates how you can set the duration that a page or user control is output cached.

<%@ OutputCache Duration="100" VaryByParam="none" %>

The next example demonstrates how you can instruct the output cache to cache a page or user control by the location and count form parameters from a form's POST or from a query string. Each HTTP request that arrives with a different location or count parameter (or both) is cached for ten seconds. Any subsequent requests with the same parameter values are satisfied from the cache until the entry expires.

<%@ OutputCache Duration="100" VaryByParam="location;count" %>

See Also

Caching ASP.NET Pages | Caching Portions of an ASP.NET Page | ASP.NET Web Forms Syntax | Directive Syntax