There’s a problem that you run into when taking advantage of Page Output Caching. What if you want a page to display different content depending on the value of a query string or form parameter passed to the page?

This is a common scenario. For example, if you are creating an online store, it is common to have a single page that acts as the product page. Depending on the value of a query string passed to the page, the page displays information on different products.

If you use the OutputCache directive discussed in the previous section, however, your page will not work as expected. The first product requested will be cached and future query string parameters will be ignored. So, the same product will be shown every time the page is requested.

Fortunately, there is an easy way around this problem. You can take advantage of the VaryByParam attribute to create different cached versions of a page. You can create a different cached version of a page whenever different query string or form parameters are passed to the page.

The VaryByParam attribute can take three types of values:

To test the VaryByParam attribute, we’ll create a page that displays the value of a query string parameter named ID.

After you build the project, launch Internet Explorer and enter the following path in your browser’s address bar:

http://localhost/project name/TestVaryByParam.aspx?id=1

Next, request the same page but change the value of the ID query string parameter:

http://localhost/project name/TestVaryByParam.aspx?id=2

You should notice that the value 1 is still displayed by the Label control on the page. The first page that you requested is cached in memory for 60 seconds, so the page is not updated when you pass a different query string.

To create different cached versions of the TestVaryByParam.aspx page, do the following:

After you complete these steps, refresh the browser. Now the page will correctly output the value of the ID query string. The content of the page is regenerated every time you pass a different query string or form parameter to the page.

It is important to understand that the content of the page is still being cached when you use the VaryByParam attribute. However, a different cached version of the page is generated whenever different query string or form parameters are passed to the page.

If you place a Web Forms control in a cached page, the control will display the exact same content every time the page is requested. This creates problems when you want to provide a user with the ability to interact with the page.

For example, suppose that you want to display a list of product categories in a DropDownList control. If you cache the page, the same item will be selected in the DropDownList control every time a user requests the page. If a user selects a new item from the DropDownList control, the selection will be ignored.

You can get around this problem, once again, by taking advantage of the VaryByParam attribute. You can use the VaryByParam attribute not only with the names of form and query string parameters but also with the names of controls.

If you add a DropDownList control named DropDownList1 to a cached page, you can use the following OutputCache directive to correctly vary the cached content of the page:

<%@ OutputCache Duration="50" VaryByParam="DropDownList1" %>

This OutputCache directive automatically generates different cached versions of the page depending on the selected item in the DropDownList1 control.

If you think about it, there’s still a problem with the OutputCache directive. One of the most valuable features of Web Forms controls is that they will render different content depending on the browser being used to request the page. For example, a Web Form control will render Cascading Style Sheet attributes only when the control detects that a browser is capable of supporting these attributes.

However, if you cache the output of a page, the same content will be delivered to any browser that requests a page. For example, if the page is first requested by someone using an Internet Explorer 6.0 browser, everyone else will get the cached content generated for an Internet Explorer 6.0 browser.

One way around this problem is to use the VaryByHeader attribute. The VaryByHeader attribute enables you to generate different cached versions of a page depending on the value of a browser header. You can use this attribute with browser headers, such as the Accept-Language or the User-Agent header.

For example, suppose that you need to display both an English and German language version of a page. You can use the Accept-Language header to detect the preferred language of the user requesting the page:

C#. 

switch (Request.Headers[ "Accept-Language" ])
{
  case "en-us":
    // Display English Content
    break;
  case "de":
    // Display German Content
    break;
}

VB.NET. 

Select Case Request.Headers("Accept-Language")
  Case "en-us"
    ' Display English Content
  Case "de"
    ' Display German Content
End Select

If you want to cache both the English and German language version of the page, you can use the following OutputCache directive:

<%@ OutputCache Duration="60" VaryByParam="None" VaryByHeader="Accept-Language" %>

Another browser header that you can use with the VaryByHeader attribute is the User-Agent header. The User-Agent header indicates the type of browser being used to request the page. For example, my browser sends the following User-Agent header with each page request:

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; Q312461; .NET CLR 1.0.3705)

You might be tempted to use the User-Agent header with the OutputCache directive to cache different versions of a page, depending on the type of browser requesting the page. In general, this is not a good idea. The problem is that the User-Agent header is far too specific.

Notice that the User-Agent header not only contains the type of browser and the major version of the browser, it contains a number of other pieces of information. For example, my User-Agent header contains the platform, a quick fix number, and the version of the .NET Framework on my machine.

Because the information sent in the User-Agent header is likely to be different for the majority of users, you would not want to use this header with the VaryByHeader attribute. Instead, you should use the VaryByCustom attribute.

The VaryByCustom attribute accepts the special value browser. When you assign this value to the VaryByCustom attribute, a different cached version of a page is generated depending on the type of browser and the major version of the browser.

For example, if a user requests a page from Internet Explorer 5.0, the page will be generated and cached. If another user requests a page from Internet Explorer 6.0, a new page will be generated and cached. But if a third user requests from Internet Explorer 5.5, a new page will not be generated—the first cached page will be served.

You can use the VaryByCustom attribute by adding the following directive to the HTML source of a page:

<%@ OutputCache Duration="60" VaryByParam="None" VaryByCustom="browser" %>

You might be wondering why this attribute is called the VaryByCustom attribute. The VaryByCustom attribute, in reality, enables you to generate different cached versions of a page depending on any custom criteria that you specify. When using the VaryByCustom attribute, you can add a method to the Global.asax file that contains your custom criteria.

For example, suppose that you want to create different cached versions of a page depending on a user’s SessionID (the unique string that identifies each user session).

Whenever a new user visits your Web site, the user will get different versions of all the pages. If the pages contain any custom user information, the information will appear correctly.

Of course, you can provide any criteria that you want within the GetVaryByCustomString() method. You can create different cached versions of pages depending on the time of day, a randomly generated number, or the weather in Columbus, Ohio.

By default, when you use the OutputCache direction, the page is not only cached on the server. The page is actually cached in three possible locations—the server, any proxy servers, and the browser.

You can control exactly where a page is cached by taking advantage of the location attribute of the OutputCache directive. This attribute accepts any of the following values:

For example, the following OutputCache directive causes the page to be cached only on the Web server:

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

Suppose that you want to place a control within a Web User Control. For example, you might want to add a DropDownList control to a Web User Control that enables a user to pick a product category or a DataList control that functions as a menu. However, if you cache the content of the Web User Control, the Web User Control will display the same content every time the page that contains the control is rendered. In other words, the state of the control contained within the Web User Control will be ignored.

When you use controls, such as DropDownList controls, in a cached Web User Control, you need to take advantage of an attribute of the OutputCache directive called the VaryByControl attribute. The VaryByControl attribute causes different versions of a Web User Control to be generated depending on the state of a control.

For example, if you add a DropDownList control named DropDownList1 to a Web User Control, you can cache different versions of the Web User Control depending on the state of the DropDownList1 control by using the following OutputCache directive:

<%@ OutputCache Duration="1000" VaryByControl="DropDownList1" %>

If you add this directive to a Web User Control, a new cached version of the Web User Control is generated whenever a user selects a new item from the dropdown list. If you have multiple controls inside the Web User Control, you can use a semicolon-delimited list to list more than one control with the VaryByControl attribute.

You cannot programmatically modify a property exposed by a cached Web User Control. You should never attempt to refer to a cached Web User Control within the Web Form Page that contains it.

For example, suppose that you have created a Web User Control named Menu.ascx that has a property named Color. Additionally, suppose that you decide to include the Web User Control in a Web Form Page named TestMenu.aspx. Adding the following Page_Load handler to the TestMenu.aspx page will generate an error:

C#. 

protected Menu Menu1;

private void Page_Load(object sender, System.EventArgs e)
{
  Menu1.Color = "blue";
}

VB.NET. 

Protected Menu1 As Menu
Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles
 MyBase.Load
  Menu1.Color = "blue"
End Sub

The page will work correctly the first time you request it. However, if you refresh the page, you’ll receive a Null Reference exception. The error is generated because you are referring to the Menu1 Web User Control within the Page_Load handler.

On the other hand, there is nothing wrong with declaratively setting the value of a property. Within the HTML source of the TestMenu.aspx page, you can assign a value to the Color property as follows:

<uc1:Menu id="Menu1" runat="server" color="blue"></uc1:Menu>

You can insert a new item into the Cache by using the Insert method as follows:

C#. 

Cache.Insert( "someItem", someItem );

VB.NET. 

Cache.Insert( "someItem", someItem )

Or, and this does the very same thing, you can insert an item like the following:

C#. 

Cache[ "someItem" ] = someItem;

VB.NET. 

Cache( "someItem" ) = someItem

After you add an item to the Cache, the item can be retrieved from the Cache within any Web Form Page located within the same application. You retrieve an item from the Cache as follows:

C#. 

someItem = Cache[ "someItem" ];

VB.NET. 

someItem = Cache( "someItem" )

When items are retrieved from the Cache, the items are returned as instances of the Object class. When programming with C#, or using Option Strict with VB.NET, you’ll need to cast the item returned from the Cache to the appropriate type as follows:

C#. 

someItem = (DataSet)Cache[ "someItem" ];

VB.NET. 

someItem = CType( Cache( "someItem" ), DataSet )

There are two warnings that you should always keep in mind when using the Cache object. First, and this is true even when you are programming with VB.NET, the Cache object is case sensitive. So, retrieving an item named SomeItem is very different from retrieving an item named someItem.

Second, you should always remember that an item that you have added to the Cache object is not guaranteed to be there when you later attempt to retrieve it. Items are automatically scavenged from the Cache. For this reason, you should always check whether an item exists before using it by comparing the item to either null or Nothing as in the following:

C#. 

if (Cache[ "someItem" ]!= null )
{
  // Use someItem
}

VB.NET. 

If Not Cache("someItem") Is Nothing Then
  ' Use someItem
End If

If you do want to explicitly remove an item from the Cache, you can use the Remove() method:

C#. 

Cache.Remove( "someItem" );

VB.NET. 

Cache.Remove( "someItem" )

For example, you might want to explicitly Remove() a DataSet from the Cache if you have just updated a record in the underlying database table.

The Cache object supports something called a file dependency. After you add an item to the Cache with a file dependency, if the file is modified, the item is automatically dropped from the Cache. You can create a file dependency for a single file, a group of files, or even a directory.

For example, suppose that you want to create a drop-down list that displays a list of companies. Additionally, suppose that you want to store the list of companies in an XML file. You can cache the contents of the XML file in memory and create a file dependency. That way, if the contents of the XML file are modified, you can automatically reload the XML file into the Cache.

Let’s try this example. First, we need to create the XML file.

Next, we need to create a Web Form Page that displays the list of companies from the XML file in a DropDownList control. We’ll cache the XML file with a file dependency on the XML file.

When the page first opens, the list of companies appears in the DropDownList control. The Label control displays the message Retrieving from File!. If you click Refresh, the message disappears because the XML file is now stored in the Cache.

The XML file will remain in the Cache unless the Companies.xml file is modified. You can test this by doing the following:

When you refresh the PickCompany.aspx page, the changes you made to the XML file appear immediately. When you modified the XML file, the file was automatically dropped from the Cache and reloaded when you refreshed the page.

You can automatically dump items from the Cache at timed intervals by supplying either an absolute or sliding expiration policy for an item that you add to the Cache.

An absolute expiration policy is a date and time when you want an item to be automatically dropped. You can supply any date and time that you want. For example, if you are caching a list of banner advertisements, you might want to drop the banner advertisements from the Cache every hour to check for expired advertisements. You can do this by supplying an expiration time with the Insert() method as follows:

C#. 

Cache.Insert(
  "Ads",
  Ads,
  null,
  DateTime.Now.AddHours( 1 ),
  System.Web.Caching.Cache.NoSlidingExpiration );

VB.NET. 

Cache.Insert( _
  "Ads", _
  Ads, _
  Nothing, _
  DateTime.Now.AddHours(1), _
  System.Web.Caching.Cache.NoSlidingExpiration )

A sliding expiration policy works differently than an absolute expiration policy. A sliding expiration policy specifies an interval of time. As long as the item is requested within that interval, the item will remain in the Cache.

Sliding expiration policies are useful when you need to store a large number of items in the Cache. Using a sliding expiration policy, you can cache a large number of items and only the items that are most frequently accessed will remain in the Cache.

The following adds an item to the Cache with a sliding expiration policy of 10 minutes:

C#. 

Cache.Insert(
  "someItem",
  someItem,
  null,
  System.Web.Caching.Cache.NoAbsoluteExpiration,
  TimeSpan.FromMinutes( 10 ));

VB.NET. 

Cache.Insert( _
  "someItem", _
  someItem, _
  Nothing, _
  System.Web.Caching.Cache.NoAbsoluteExpiration, _
  TimeSpan.FromMinutes(10) )

Be aware that you cannot add an item to the Cache with both an absolute expiration policy and sliding expiration policy. You must pick one or the other.

You can set different item priorities for items added to the Cache. When memory resources become low, items with lower priorities will be dropped before items with higher priorities.

The item priority is represented by values from the CacheItemPriority enumeration. The following lists the values from this enumeration in order of priority:

For example, you would use the following code to add an item to the Cache with High priority:

C#. 

Cache.Insert(
  "someItem",
  someItem,
  null,
  System.Web.Caching.Cache.NoAbsoluteExpiration,
  System.Web.Caching.Cache.NoSlidingExpiration,
  System.Web.Caching.CacheItemPriority.High,
  null);

VB.NET. 

Cache.Insert( _
  "Ads", _
  Ads, _
  Nothing, _
  System.Web.Caching.Cache.NoAbsoluteExpiration, _
  System.Web.Caching.Cache.NoSlidingExpiration, _
  System.Web.Caching.CacheItemPriority.High, _
  Nothing)