How to: Extend Caching by Using the VaryByCustom Event Handler

You can extend and manipulate caching by creating a IVaryByCustomHandler interface. VaryByCustom is an ASP.NET caching feature that you can use to cache multiple versions of page output, based on custom strings. For example, you can use VaryByCustom if you want to display cached pages that display a different welcome string for each user. For more information about VaryByCustom in ASP.NET, see the Page Output Caching, Part 1 article on MSDN.

This topic covers the three basic steps that are required to use the VaryByCustom property to extend caching in Microsoft Office SharePoint Server 2007.

• Create a VaryByCustom handler that provides a list of custom strings that the output cache uses to vary content on the returned page.

• Register the handler in the Global.asax file.

• Define custom strings to vary for each cache profile in your Web application. The system passes these strings to the VaryByCustom handler, which determines how to vary the cache.

The example code varies content based on two parameters: whether the client browser supports cascading style sheets (CSS), and whether the current user is an administrator. Depending on the value of the custom string that is passed to the GetVaryByCustomString method, the function constructs a string that is based on one, both, or neither of these parameters. The caching system creates a separate cache for each value that GetVaryByCustomString returns. For example, if the value of custom is SupportsCSS, GetVaryByCustomString returns either a string containing True or False, depending on the result of sb.Append(context,Request.Browser.SupportsCss.ToString): one that supports CSS, and one that does not.

You can specify the value of the custom string for each cache profile in your Web application, as shown in the following code sample:

[C#]

//First, write a VaryByCustom handler. This example varies based on
//two parameters: whether the client browser supports CSS,
//and whether the current user is an administrator.
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Text;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using Microsoft.SharePoint.Publishing;
using Microsoft.SharePoint.ApplicationRuntime;
using Microsoft.SharePoint;

namespace CacheDemo
{
    public class CacheDemoHttpApplication ; SPHttpApplication, IVaryByCustomHandler
    {
        internal const string MyVaryByString1 = "SupportsCSS";
        internal const string MyVaryByString2 = "SiteAdmin";
        public override void Init()
        {
            base.Init();
            this.RegisterGetVaryByCustomStringHandler((Microsoft.SharePoint.ApplicationRuntime.IVaryByCustomHandler)this);
        }

        public string GetVaryByCustomString(HttpApplication app, HttpContext context, string custom)
        {
            //The code looks for parameters specified in the cache 
            //profile that are passed to the handler and parses those 
            //delimited by a semicolon.
            StringBuilder sb = new StringBuilder();
            string[] strings = custom.Split(';');
            bool appended = false;
            foreach (string str in strings)
            {
                switch (str)
                {
                    case MyVaryByString1:
                        if (appended)
                        {
                            sb.Append(';');
                        }
                        //If you want to vary based on a property of
                        //the request, work with the http context
                    sb.Append(context.Request.Browser.SupportsCss);
                        break;
                    case MyVaryByString2:
                        if (appended)
                        {
                            sb.Append(';');
                        }
                        //If you want to vary by whether the current
                        //user is the site administrator,
                        //examine the SPContext
                        sb.Append(SPContext.Current.Web.UserIsSiteAdmin.ToString());
                        break;

                    default:
                        continue;
                }
                appended = true;
            }
            return sb.ToString();
        }
    }
}

Next, register the VaryByCustom event handler in the Global.asax file. You must modify the Assembly tag to specify the assembly that you build with the preceding code.

//Register the VaryByCustom string in the Global.asax file
<%@ Assembly Name="Microsoft.SharePoint"%>
<%@ Assembly Name="cachedemo"%>
<%@ Import Namespace="cachedemo" %>
<%@ Application Language="C#" Inherits="cachedemo.CacheDemoHttpApplication" %>

Finally, specify the custom string value for each cache profile in your Web application.

Edit each cache profile in your site collection

1. Navigate to the root site of your site collection.

2. Click Site Actions, point to Site Settings, and click Modify All Site Settings.

3. Click Site Collection Cache Profiles in the Site Collection Administration section.

4. Point to the cache profile that you want to modify, right-click, and click Edit.

5. Type the custom string that you want to add in the Vary By Custom Parameter field, such as SupportsCSS;SiteAdmin for use with this example, and then click OK.

See Also

Concepts

Output Caching and Cache Profiles
Custom Caching Overview
Object Caching