Use VaryByControl for Smart User Control Caching

ASP.NET's page output cache, which you can control declaratively with @ OutputCache directives, helps you optimize performance by preventing pages and user controls that contain relatively static content from being re-rendered unnecessarily. Placing this directive in an .aspx file lets ASP.NET cache the page's output for 60 seconds at a time:

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

Placing the same directive in an .ascx file allows only the output from that file to be cached without affecting whether other content on the page can be cached.

When used in an .ascx file, the @ OutputCache directive supports an attribute named VaryByControl. VaryByControl is more than a convenience - it's an outright necessity in some user controls. Unfortunately, the documentation is of little help in deciphering VaryByControl's meaning. VaryByControl lets you cache different versions of a user control based on variances in the properties of controls contained in the user control. As an example, consider this .ascx file:

<%@ OutputCache Duration="60"

  VaryByControl="MyDropDownList" %>

 

<asp:DropDownList ID="MyDropDownList" RunAt="server"

  OnSelectedIndexChanged="OnUpdateLabel">

  <asp:ListItem Text="Item 1" RunAt="server" />

  <asp:ListItem Text="Item 2" RunAt="server" />

  <asp:ListItem Text="Item 3" Selected="true"

    RunAt="server" />

  <asp:ListItem Text="Item 4" RunAt="server" />

  <asp:ListItem Text="Item 5" RunAt="server" />

</asp:DropDownList>

<asp:Label ID="Output" RunAt="server" />

 

<script language="C#" runat="server">

void OnUpdateLabel (Object sender, EventArgs e)

{

    Output.Text = MyDropDownList.SelectedItem.Text;

}

</script>

This user control declares two Web controls: a DropDownList control and a Label control. When the dropdown list fires a SelectedIndexChanged event, the OnUpdateLabel method updates the Label control to echo the item now selected in the dropdown list. Without VaryByControl, you couldn't cache this user control because the output cached the first time the control executes would include the output from the Label control and would not change until the cached output is discarded. VaryByControl fixes this problem by configuring ASP.NET to cache different versions of the control's output based on varying property values (in this case, on varying values of MyDropDownList.SelectedIndex) in the control or controls the user control contains. Simply identify the control or controls whose property values affect the rendering of the user control in a VaryByControl attribute and even user controls that vary their output based on the state of embedded controls suddenly become cache-compatible.

Jeff Prosise is author of several books, including Programming Microsoft .NET (Microsoft Press). He also is a co-founder of Wintellect (http://www.wintellect.com), a software consulting and education firm that specializes in .NET. Got a question for this column? Submit queries to [email protected].