How To Perform Fragment Caching in ASP.NET by Using Visual Basic .NET

This article demonstrates how to implement fragment caching in ASP.NET. Fragment caching does not actually cache a Web Form's code fragments directly; fragment caching refers to the caching of individual user controls (.ascx) within a Web Form. Each user control can have independent cache durations and implementations of how the caching behavior is to be applied. The sample code in this article illustrates how to achieve this functionality.

Fragment caching is useful when you need to cache only a subset of a page. You should use fragment caching and other forms of output caching in situations where the output does not necessarily need to be dynamically generated for each request. Good candidates for fragment caching are navigation bars, headers, footers, and other code fragments that can be implemented as user controls and may benefit from the performance gains that are associated with having their output retrieved from a cache.

Requirements

• Microsoft Windows 2000
• Microsoft Internet Information Server (IIS)
• Microsoft .NET Framework
• Microsoft ASP.NET

Create an ASP.NET Web Application Using Visual Basic .NET

The following steps demonstrate how to create a new ASP.NET Web application named FragmentCache.

1. Start Microsoft Visual Studio .NET
2. On the File menu, point to New, and then click Project.
3. In the New Project dialog box, click Visual Basic Projects under Project Types, and then click ASP.NET Web Application under Templates.
4. In the Name box, type FragmentCache. In the Location box, select the appropriate server. If you are using the local server, you can leave the server name as http://localhost.

Create the User Controls

This section provides the sample code and explanations of each user control that you will use in this article. You can copy and paste the sample code into the associated .ascx file and code-behind page as described.

User Control 1 (FragmentCtrl1.ascx)

The following user control, FragmentCtrl1.ascx, is very simple. FragmentCtrl1.ascx writes out the time that the cache entry for the item occurs. As with all of the controls that are created for this article, a basic description is provided for the control to make it easier to distinguish the settings and the associated behaviors at run time in the later sections.

1. In Visual Studio .NET, create a new user control as follows:
   1. In Solution Explorer, right-click the project node, point to Add, and then click Add Web User Control.
   2. Name the control FragmentCtrl1.ascx, and then click Open.
2. Make sure that the Design tab is selected. Click and drag a Web Form Label control from the Web Forms section of the toolbox, and drop the Label control onto the page.
3. Click the Label control. In the Properties pane of the Visual Studio .NET integrated development environment (IDE), type CacheEntryTime in the ID property, and leave the Text property blank.
4. Switch to HTML view, and add the following @OutputCache directive to the top of the page:

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

5. Right-click the .ascx file, and then click View Code to display the code-behind page source.
6. Add the following code to the Page_Load event, which sets the CacheEntryTime label's Text property:

   Private Sub Page_Load(ByVal sender As System.Object, _
                         ByVal e As System.EventArgs) Handles MyBase.Load
           CacheEntryTime.Text = "FragmentCtrl1: " & DateTime.Now.TimeOfDay.ToString()
   End Sub
   					

User Control 2 (FragmentCtrl2.ascx)

Although you can simply create another version of the first control with a different cache duration to show how multiple user controls can have independent behaviors in the same page, this section makes the second control, FragmentCtrl2.ascx, more interesting. FragmentCtrl2.ascx is used to introduce the VaryByControl attribute. VaryByControl allows different cache entries to be made based on the values for a specified control. This functionality is made much clearer at run time in the next section.

1. In Visual Studio .NET, create a new user control as follows:
   1. In Solution Explorer, right-click the project node, point to Add, and then click Add Web User Control.
   2. Name the control FragmentCtrl2.ascx, and then click Open.
2. Make sure that the Design tab is selected. Click and drag a Web Form Label control from the Web Forms section of the toolbox, and then drop the Label control onto the page.
3. Click the Label control. In the Properties pane, type CacheEntryTime in the ID property, and leave the Text property blank.
4. Position the cursor directly after the Label control, and then press ENTER to move to the next line in the page.
5. Click and drag a Web Form RadioButtonList control from the Web Forms section of the toolbox, and drop it onto the page. The RadioButtonList control should appear by itself on the line after the Label control.
6. Click the RadioButtonList control. In the Properties window, type MyRadioButtonList in the ID property.
7. In the Properties pane, locate the Items property for the MyRadioButtonList control, click Collection, and then click the ellipsis (...) button that appears next to Collection.
8. In the ListItem Collection Editor window, add ListItem members as follows:
   1. Under Members, click Add.
   2. In the ListItem properties section, set Text and Value to Yes, and set Selected to True.
   3. Under Members, click Add again.
   4. In the ListItem properties section, set Text and Value to No, and set Selected to False.
   5. Under Members, click Add one last time.
   6. In the ListItem properties section, set Text and Value to Maybe, and set Selected to False.
   7. Click OK to return to the .ascx file in Design view. Notice that three radio buttons appear that are contained within the RadioButtonList control: Yes, No, and Maybe.
9. Position the cursor directly after the RadioButtonList control, and press ENTER to move to the next line in the page.
10. Click and drag a Web Form Button control from the Web Forms section of the toolbox, and drop it onto the page. The Button control should appear by itself on the line after the RadioButtonList control.
11. Click the Button control. In the Properties pane, type Submit in the Text property.
12. Switch to HTML view, and add the following @OutputCache directive to the top of the page:

    <%@ OutputCache Duration="60" VaryByParam="none" VaryByControl="MyRadioButtonList"%>
    					

13. Right-click the .ascx file, and then click View Code to display the code-behind page source.
14. Add the following code to the Page_Load event, which sets the CacheEntryTime label's Text property:

    Private Sub Page_Load(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) Handles MyBase.Load
            CacheEntryTime.Text = "FragmentCtrl2: " & DateTime.Now.TimeOfDay.ToString()
    End Sub
    					

Create the Web Form to Contain the User Controls

You can now create the Web Form (.aspx) to contain the newly developed user control. To create the Web Form, follow these steps:

1. Add a new Web Form named FragmentCaching.aspx to your project in Visual Studio .NET as follows:
   1. In Solution Explorer, right-click the project node, point to Add, and then click Add Web Form.
   2. Name the Web Form FragmentCaching.aspx, and then click Open.
2. Make sure that the Design tab is selected. Click and drag a Web Form Label control from the Web Forms section of the toolbox, and drop it onto the page.
3. Click the Label control. In the Properties pane, type Time in the ID property, and leave the Text property empty.
4. Position the cursor directly after the Label control, and press ENTER to move to the next line in the page.
5. Drag FragmentCtrl1.ascx, and drop it onto the Web Form so that it is positioned after the Label control on a line by itself. Position the cursor directly after the control, and press ENTER to move to the next line in the page.
6. Drag FragmentCtrl2.ascx, and drop it onto the Web Form so that it is positioned after FragmentCtrl1.ascx on a line by itself.
7. In HTML view, the Web Form should appear similar to the following code:

   <%@ Page Language="vb" AutoEventWireup="false" 
   Codebehind="FragmentCaching.aspx.vb" 
   Inherits="FragmentCache.FragmentCaching"%>
   <%@ Register TagPrefix="uc1" TagName="FragmentCtrl1" Src="FragmentCtrl1.ascx" %>
   <%@ Register TagPrefix="uc1" TagName="FragmentCtrl2" Src="FragmentCtrl2.ascx" %>
   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   <HTML>
      <HEAD>
         <title></title>
         <meta name="GENERATOR" content="Microsoft Visual Studio.NET 7.0">
         <meta name="CODE_LANGUAGE" content="Visual Basic 7.0">
         <meta name="vs_defaultClientScript" content="JavaScript">
         <meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie5">
      </HEAD>
      <body>
         <form id="Form1" method="post" runat="server">
            <P>
               <asp:Label id="Time" runat="server"></asp:Label>
            </P>
            <P>
               <uc1:FragmentCtrl1 id="FragmentCtrl11" runat="server">
               </uc1:FragmentCtrl1>
            </P>
            <P>
               <uc1:FragmentCtrl2 id="FragmentCtrl21" runat="server">
               </uc1:FragmentCtrl2>
            </P>
         </form>
      </body>
   </HTML>
   						

   NOTE: Make sure that the controls are placed inside the
8. Right-click the .aspx file, and then click View Code to display the code-behind page source.
9. Add the following code to the Page_Load event, which sets the Time label's Text property:

   Private Sub Page_Load(ByVal sender As System.Object, _
                         ByVal e As System.EventArgs) Handles MyBase.Load
           Time.Text = "WebFormTime: " & DateTime.Now.TimeOfDay.ToString()
   End Sub
   					

10. From the File menu, click Save All to save the user controls, the Web Form, and other associated project files.
11. From the Build menu in the Visual Studio .NET integrated development environment (IDE), click Build to build the project.

Run the Sample

This section demonstrates how to view the code at run time to witness the caching behavior and then briefly describes why the code performs the way that it does.

1. In the Visual Studio .NET IDE Solution Explorer, right-click the FragmentCaching.aspx Web Form, and then click View in Browser to run the code.
2. After the page appears in the browser, right-click the page, and then click Refresh to refresh the page. You can also press the F5 key to refresh the page if you are viewing the page in a browser that is external to the Visual Studio .NET IDE.
   
   Notice that the time on the Web Form has been updated, but the user controls still display the time when their associated cache entry was made.
3. In the second control, click Submit. Notice that the control displays an updated time. This is in response to the VaryByControl attribute setting for the user control that references the RadioButtonList control.
4. Click No, and then click Submit again. Notice that the time is updated again in the user control's display. This is because a new cache entry is made for the control based on this No value setting.
   
   Repeat this step except with the Maybe option. You see the same behavior.
5. Click Yes, and then click Submit again. Repeat this operation with the No and Maybe options. Notice that these selections for the control are cached and that they display the previous cache entry time. If you continue to click Submit past the @ OutputCache directive's duration setting, the user control's time is updated for each specific value selection for the RadioButtonList control.

NOTE: It is not the goal of this article to cover all of the possible settings and scenarios for fragment caching. For more information, see the References section at the end of this article.

Troubleshooting

• Do not try to programmatically manipulate a user control that is output-cached. This is because the control is only dynamically created when it is run the first time before the cache entry occurs. The output cache satisfies all other requests until the control expires.
• If the Web Form in which user controls are hosted has an output cache duration that is longer than the duration times of the user controls, the Web Form's setting dictates the caching behavior of the controls.

For additional information, click the article numbers below to view the articles in the Microsoft Knowledge Base: For more information, refer to the .NET Framework Software Development Kit (SDK) at the following MSDN Web site: For information about and samples of ASP.NET caching from the ASP.NET QuickStart guides, visit the following Microsoft Web site: