Caching a User Control

Like ASP.NET pages, user controls can be cached to improve performance. Caching a user control involves saving and reusing the output of the control. We will briefly discuss the options that ASP.NET provides for user control caching ”also called fragment caching ” and provide one complete sample. We'll point you to the IBuySpy Web sites (see the following sidebar) and to the .NET Framework SDK documentation for other samples.

The IBuySpy ASP.NET Demonstration Sites

The IBuySpy Web sites demonstrate how to utilize user controls in the design and layout of ASP.NET Web applications. There are two IBuySpy Web applications: a store (http://www.ibuyspystore.com) and a portal (http://www.ibuyspyportal.com). We strongly recommend that you visit the sites and look at the source code for user controls. The documentation page for the store (http://www.ibuyspystore.com/docs/docs.htm) contains links to the source code for user controls used in the IBuySpy store. The documentation page for the portal (http://www.ibuyspyportal.com/docs/docs.htm) contains links to the source code for user controls used in the IBuySpy portal.

To enable caching of your user control, apply the OutputCache directive at the top of your control's .ascx file. There are four variations of the OutputCache directive:

Specify the cache duration using the Duration attribute:
```
 <%@OutputCache  Duration="1200"  VaryByParam="None"%> 
```
The Duration attribute specifies the period (in seconds) for which the control will be cached. In this version of caching, the VaryByParam attribute is not used but must be included and set to None . A cache entry is created corresponding to each instance of the user control and reused for the specified period. Use this version to cache a control that does not depend on input parameters. For an example, see the source code for the PopularItems user control in the IBuySpy store documentation (http://www.ibuyspystore.com/docs /docs.htm).
Specify the Duration and VaryByParam attributes:
```
 <%@OutputCacheDuration="100"  VaryByParam="category"  %> 
```
The VaryByParam attribute specifies GET query string parameters or form POST parameters. A new cache entry is created for each new name /value pair in the parameter list of the VaryByParam attribute. To specify multiple parameters, separate them by semicolons (for example, VaryByParam="category; selectionID") . If VaryByParam="*" is specified, all the parameters for the request are used to govern caching. Use this version of caching if the output of your user control depends on GET or POST parameters for the containing page ”for instance, if your user control displays a database entry based on a user request. For an example, see the source for the Menu user control in the IBuySpy store documentation (http://www.ibuyspystore.com/docs/docs.htm).
Specify the Duration and VaryByControl attributes:
```
 <%@OutputCacheDuration="150"  VaryByControl="list1;radio1"  %> 
```
The VaryByControl attribute specifies the ID s of one or more child controls that correspond to form controls contained within the user control. A new cache entry is created for each new combination of inputs to the specified controls. Use this type of caching if your user control contains form controls such as DropDownList , RadioButton , and TextBox and you want to govern caching behavior by the values of these controls. In the next subsection, we'll show an example of caching using the VaryByControl attribute.
Specify the Duration and the VaryByCustom attributes:
```
 <%@OutputCacheDuration="60"VaryByParam="None"  VaryByCustom="CustomString"%>  
```
The VaryByCustom attribute specifies a string that is used to govern caching. In this version of caching, the VaryByParam attribute is not used but must be included and set to None . The VaryByCustom attribute works the same way in a user control as it does in a page. For an example of page caching with this attribute, see "Caching Versions of a Page, Based on Custom Strings" in the .NET Framework SDK documentation.

When you use the VaryByCustom attribute, you have to override the GetVaryByCustomString method in the Global.asax file for your application. You can implement logic within the GetVaryByCustomString method so that its return value is dependent on the custom string. Here is a simple user control that is cached using the VaryByCustom attribute:
```
 <%@ControlLanguage="c#"ClassName="VaryByCustomUser"%> <%@OutputCacheDuration=20VaryByParam="none" VaryByCustom="myCustomString"%> <%=DateTime.Now%> 
```
Here is how you could override the GetVaryByCustomString method in the Global.asax file. The example does not do anything useful; it merely illustrates the concept:
```
 <%@Language=c#debug=true%> <scriptrunat="server"> publicoverridestringGetVaryByCustomString(HttpContextcontext, stringcustom){ switch(custom){ case"myCustomString": returnRequest.QueryString["foo"]; //Othercasesforothercustomstrings } returnnull; } </script> 
```

VaryByControl Example

The user control shown in Listing 4-16, CachedUserControl , uses the VaryByControl attribute to govern caching. CachedUserControl creates cache entries based on the selected item in its DropDownList control. To demonstrate caching behavior, we have added a timestamp in CachedUserControl to indicate when the code for the user control is executed.

Listing 4-16 CachedUserControl.ascx

 <%@ControlLanguage="C#"ClassName="CachedUserControl"%> <%@OutputCacheDuration="60"VaryByControl="language"%> <scriptrunat="server"> publicvoidPage_Load(objectsender,EventArgse){ label1.Text="Theselectedlanguageis"+ language.SelectedItem.Text+"."; timeLabel.Text=DateTime.Now.TimeOfDay.ToString(); } </script> <p/> Timestamponusercontrol: <asp:labelid="timeLabel"runat="server"/> <p/>

 Selectaprogramminglanguage. <p/> <asp:DropDownListwidth="100"id="language"runat="server"> <asp:ListItem>C#</asp:ListItem> <asp:ListItem>VisualBasic.NET</asp:ListItem> <asp:ListItem>JScript.NET</asp:ListItem> </asp:DropDownList> <p/> <asp:labelid="label1"runat="server"/> <p/>

The page shown in Listing 4-17 uses CachedUserControl . The page has a timestamp that indicates when it's executed.

Listing 4-17 CachedUserControlTest.aspx

 <%@Pagelanguage="C#"%> <%@RegisterTagPrefix="mspuc"TagName="CachedUserControl" src="UserControls/CachedUserControl.ascx"%> <html> <head> <scriptrunat="server"> voidPage_Load(objectsender,EventArgse){ timeLabel.Text="Timestamponpage:"+ DateTime.Now.TimeOfDay.ToString(); } </script> </head> <body> <formrunat="server"> <asp:Labelid="timeLabel"runat="server"/> <p/> Thefollowingusercontroliscachedusingthe VaryByControlattribute. <mspuc:CachedUserControlid="user"runat="server"/> <asp:ButtonFont-Bold="true"Text="Submit" runat="server"id="Button1"/> <p/> </form> </body> </html>

For a demonstration of user control caching, access the page CachedUserControlTest.aspx in your browser. Notice that the timestamp on the page changes with each request. However, during the cache process, the time stamp on the user control changes only if you change the selection in the DropDownList .

How User Control Caching Works

When the page parser encounters a declarative instance of a user control with an OutputCache directive, it creates an instance of the StaticPartialCachingControl class and adds it in the logical position of the user control in the control tree. (We described the control tree in Chapter 2.) If a user control with an OutputCache directive is dynamically added to a page, the parser creates an instance of the PartialCachingControl class instead. A StaticPartialCachingControl (or PartialCachingControl ) object is capable of adding entries to and retrieving them from the ASP.NET Cache object. If the StaticPartialCachingControl (or PartialCachingControl ) object does not find a cache entry for a given combination of inputs, it dynamically creates an instance of the user control and adds the user control instance to its own control tree, executes the code for the user control, and adds a corresponding entry to the cache.

If a user control has an OutputCache directive applied, you must check for the user control's existence (for example, myUserID != null ) before accessing it programmatically from a containing page. This step is necessary because when a cache entry exists, an instance of the user control is not created, and you could get a null reference exception when you access the user control.