Share via

@ 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 | 
     ServerAndClient "
   Shared="True | False"
   VaryByControl="controlname"
   VaryByCustom="browser | customstring"
   VaryByHeader="headers"
   VaryByParam="parametername" 
   CacheProfile="cache profile name | ''"
   NoStore="true | false"
   SqlDependency="database/table name pair | CommandNotification"
%>

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.

    Note

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

  • CacheProfile
    The name of the cache settings to associate with the page. This is an optional attribute and defaults to an empty string ("").

    Note

    This attribute is not supported for @ OutputCache directives included in user controls (.ascx files). When specified on a page, the value must match the names of one of the available entries in the outputCacheProfiles element under the outputCacheSettings section. If the name does not match a profile entry, an exception is thrown.

  • NoStore
    A Boolean value that determines whether to prevent secondary storage of sensitive information.

    Note

    This attribute is not supported for @ OutputCache directives included in user controls (.ascx files). Setting this attribute to true is equivalent to the following code executed during the request:

                Response.Cache.SetNoStore();

  • 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).

  • SqlDependency
    A string value that identifies a set of database and table name pairs that a page or control's output cache depends on. Note that the SqlCacheDependency class monitors the table in a database that the output cache depends on, so that when items in a table are updated, those items are removed from the cache when using table-based polling. When using notifications (in Microsoft SQL Server 2005) with the value CommandNotification, ultimately a SqlDependency class is used to register for query notifications with the SQL Server 2005 server.

    Note

    The CommandNotification value for the SqlDependency attribute is valid only on Web (.aspx) pages. User controls can only use table-based polling with the @ OutputCache directive.

  • 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 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 combination of specified headers.

    Note

    Setting the VaryByHeader attribute enables caching items in all HTTP version 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 combination of specified parameters. Possible values include none, an asterisk (*), and any valid query string or POST parameter name.

    Warning

    Either this attribute or the VaryByControl attribute is required when you use the @ OutputCache directive on ASP.NET pages and user controls. 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 an asterisk (*).

  • 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

    Either this attribute or the VaryByParam attribute is required when you use the @ OutputCache directive on ASP.NET pages and user controls.

Remarks

Setting values for the page output cache is the same as manipulating the SetExpires and SetCacheability methods through the Cache property.

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 code example demonstrates how you can set the duration for which a page or user control is output cached.

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

The next code example demonstrates how you can instruct the output cache to cache a page or user control by its location and count form parameters from a form's POST method 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="10" VaryByParam="location;count" %>

See Also

Reference

Directive Syntax

Concepts

Caching ASP.NET Pages
Caching Portions of an ASP.NET Page
ASP.NET Web Page Syntax Overview