Page Fragment Caching

In addition to output caching an entire page, ASP.NET provides a simple way for you to output cache regions of page content, which is appropriately named fragment caching. You delineate regions of your page with a user control, and mark them for caching using the @ OutputCache directive introduced in the previous section. This directive specifies the duration (in seconds) that the output content of the user control should be cached on the server, as well as any optional conditions by which it should be varied. For example, the following directive instructs ASP.NET to output cache the user control for 120 seconds, and to vary the caching using the "CategoryID" and "SelectedID" querystring or form post parameters.

<%@ OutputCache Duration="120" VaryByParam="CategoryID;SelectedID"%>

The VaryByParam attribute is extremely powerful and allows user control authors to instruct ASP.NET to cache/store multiple instances of an output cache region on the server. For example, the following URLs to the host page of the previous user control cache separate instances of the user control content.

Logic within a user control can then dynamically generate different content (which is cached separately) depending on the arguments provided.

In addition to supporting the VaryByParam attribute, fragment caching also supports a VaryByControl attribute. Whereas the VaryByParam attribute varies cached results based on name/value pairs sent using POST or GET, the VaryByControl attribute varies the cached fragment by controls within the user control. For example:

<%@ OutputCache Duration="120" VaryByParam="none" VaryByControl="Category" %>

Note that similar to output-cached pages, explicit use of either VaryByParam or VaryByControl is required even if neither is used. If the user control contained a drop-down select box control named Category, the user control's output would vary based on the selected value within that control.

The following sample code demonstrates how to cache two menu sections of a page using a declarative user control.

The following sample code shows the implementation of the "Acme:Menu" user control with caching support.

Note that this example output caches the response of each user control for a period of 120 seconds. All logic necessary to recreate each menu user control in the event of a cache miss (either because 120 seconds has expired or because memory conditions on the server have become scarce) is encapsulated cleanly within the user control.

The following example shows simple fragment caching. The sample caches the output from a control that retrieves data from an SQL Server database, while keeping the dynamic properties of the parent page. You can see that the page is dynamic because the time is updated with every refresh, while the control is only updated every 60 seconds.

Note: Attempts to programmatically manipulate an output-cached control from its containing page result in an error. For example, attempts to use a declarative data binding expression on the user control tag generate parser errors, as shown in the following code.

<!-- The following tags generate parser errors. -->
<Acme:Menu Category='<%# Container.DataItem("Category")'  runat="server"/>

The reason for this is simple. In cases when the content of a user control is output cached, an instance of the control is created only on the first request; thus, once cached, the control is no longer available. Instead, you should encapsulate all the logic necessary to create the content of a user control directly within the control itself; this is typically done within the user control's Page_Load event or Page_PreRender event.

You can declare and use other declarative property parameters to customize the control. For example, the previous user control can be customized as follows:

<Acme:Menu Category="LeftMenu" runat=server/>
<Acme:Menu Category="RightMenu" runat=server/>

These declarations cause the appropriate code to be generated and executed by the page compiler in the event that the control is created as a result of a cache miss. User control developers can then access these settings just as they would in a non-cached user control scenario.

Fragment Caching API New in 2.0

In addition to using the @ OutputCache directive, you can now programatically adjust the caching options for user controls using the CacheAPI. In the following example, the control varies the time its cached for based on the state that is selected in the dropdown. You can see the time the control was rendered and the time when the cache entry will be cleared.