Caching Multiple Versions of a User Control Based on Parameters

Article
10/12/2006

You can vary user-control output to the cache in two ways: by specifying the user control name along with either a query string or a form POST parameter, or by specifying the ID property of an ASP.NET server control contained in the user control. For the former, use the VaryByParam attribute of the @ OutputCache directive or include the VaryByParams property in the PartialCachingAttribute located in the user control's code-behind file. For the latter, use the VaryByControl attribute or include the VaryByControls property in the PartialCachingAttribute.

Note Varying user control output to the cache based on query string or form POST parameters will work only if the user control posts back and processes the postback itself. You cannot post back to the containing page and expect this type of caching of user control output to function properly.

To cache multiple versions of a user control declaratively by using the VaryByControl attribute

Create a user control that posts back.
Include an @ OutputCache directive in the .ascx file with Duration and VaryByControl attributes.

Note If you use the VaryByControl attribute in the directive, you do not need to also include the VaryByParam attribute.
Set the VaryByControl attribute to the ID attribute value for a control that is contained in the user control.

For example, the following @ OutputCache directive sets expirations for the user control to 60 seconds and varies the control's output by an ASP.NET server control with an ID property value of State.
```
<%@ OutputCache Duration="60" VaryByControl="State" %>
```

To cache multiple versions of a user control programmatically by using the VaryByControls property

In a code-behind class, create a user control code that posts back to itself.
Include a metadata PartialCaching attribute at the beginning of the user control code.
Include a value for the duration parameter and set the varyByControls parameter to the ID property value of the ASP.NET server control in the user control that you want to vary the user control output by.

When included before the code that extends the UserControl class, the following example sets duration to 60 seconds and varyByControls to "State".
```
[PartialCaching(60, null, State, null)]
[Visual Basic]<PartialCaching(60, null, State, null)>
```

To cache multiple versions of a user control declaratively by using the VaryByParam attribute

Create a user control that posts back to itself.
Include an @ OutputCache directive in the .ascx file with Duration and VaryByParam attributes.

Note If you include the VaryByControl attribute in the @ OutputCache directive for a user control, you do not need to also include the VaryByParam attribute. Regardless of which attribute you include, set its value to None if you do not want to use the functionality it provides.
Set the VaryByParam attribute to the GET query string or form POST parameter that you want to vary the user control by.

For example, the following @ OutputCache directive sets expirations for the user control to 60 seconds and varies the control's output by a State form POST or query string parameter.
```
<%@ OutputCache Duration="60" VaryByParam="State" %>
```

To cache multiple versions of a user control programmatically by using the VaryByParams property

In a code-behind class, create a user control code that posts back to itself.
Include a metadata PartialCaching attribute at the beginning of the user control code.
Include a value for the duration parameter and set the varyByParams parameter to the GET query string or form POST parameter that you want to vary the user control output by.

When included before the code that extends the UserControl class, the following example sets duration to 60 seconds and varyByParams to a State form POST or query string parameter.
```
[PartialCaching(60, State, null, null)]
[Visual Basic]<PartialCaching(60, State, null, null)>
```

The following example demonstrates a user control that posts back to itself by including the code for a ServerClick event in the code declaration block of the control. It also demonstrates using the VaryByControl parameter to vary user control output to the output cache, based on the State and Country form ID property values associated with the two DropDownList Web server controls contained in the user control. Also included is the Shared attribute, set to true to allow multiple pages to access the same cached user control output. It also includes a simple .aspx file that contains the user control. To use this example, name the user control file Sample.ascx.

<%@ Control Language="C#" %>
<%@ OutputCache Duration="30" VaryByControl="State;Country" Shared="true" %>
<%@ import namespace="System.Globalization"%>
<script runat=server>
  void SubmitBtn_Click(Object Sender, EventArgs e) {
    Label1.Text="You chose: " + state.SelectedItem.Text + " and " + country.SelectedItem.Text;
    TimeMsg.Text = DateTime.Now.ToString("T");
} 
</script>

<asp:DropDownList id="state" runat="server">
            <asp:ListItem> </asp:ListItem>  
            <asp:ListItem>Idaho</asp:ListItem>
            <asp:ListItem>Montana</asp:ListItem>
            <asp:ListItem>Nevada</asp:ListItem>
            <asp:ListItem>Oregon</asp:ListItem>
            <asp:ListItem>Washington</asp:ListItem>
            <asp:ListItem>Wyoming</asp:ListItem>
        </asp:DropDownList>
<br>

<asp:DropDownList id="country" runat="server">
      <asp:ListItem>  </asp:ListItem>
      <asp:ListItem>Austria</asp:ListItem>
      <asp:ListItem>France</asp:ListItem>
      <asp:ListItem>Italy</asp:ListItem>
      <asp:ListItem>Germany</asp:ListItem>
      <asp:ListItem>Spain</asp:ListItem>
      <asp:ListItem>Switzerland</asp:ListItem>
</asp:DropDownList>
<br>
<asp:button text="Submit" OnClick="SubmitBtn_Click" runat=server/>
<br>    
<asp:Label id=Label1 font-name="Verdana" font-size="10pt" runat="server">
          Select values from the lists
</asp:Label>

<br> <br>

Control generated at: <asp:label id="TimeMsg" runat="server" />
[Visual Basic]<%@ Language="VB" %>
<%@ OutputCache Duration="30" VaryByControl="State;Country" Shared="true" %>
<%@ import namespace="System.Globalization"%>
<script runat=server>
   Sub SubmitBtn_Click(Sender as Object, e as EventArgs)
            Label1.Text="You chose: " & state.SelectedItem.Text & " and " & country.SelectedItem.Text
       TimeMsg.Text = DateTime.Now.ToString("T")
    End Sub
</script>

<asp:DropDownList id=state runat="server">
            <asp:ListItem> </asp:ListItem>  
            <asp:ListItem>Idaho</asp:ListItem>
            <asp:ListItem>Montana</asp:ListItem>
            <asp:ListItem>Nevada</asp:ListItem>
            <asp:ListItem>Oregon</asp:ListItem>
            <asp:ListItem>Washington</asp:ListItem>
            <asp:ListItem>Wyoming</asp:ListItem>
        </asp:DropDownList>
<br>

<asp:DropDownList id=country runat="server">
            <asp:ListItem>  </asp:ListItem>
            <asp:ListItem>Austria</asp:ListItem>
            <asp:ListItem>France</asp:ListItem>
            <asp:ListItem>Italy</asp:ListItem>
            <asp:ListItem>Germany</asp:ListItem>
            <asp:ListItem>Spain</asp:ListItem>
            <asp:ListItem>Switzerland</asp:ListItem>
        </asp:DropDownList>
<br>
<asp:button text="Submit" OnClick="SubmitBtn_Click" runat=server/>
<br>    
<asp:Label id=Label1 font-name="Verdana" font-size="10pt" runat="server">
          Select values from the lists
        </asp:Label>

<br> <br>

Control generated at: <asp:label id="TimeMsg" runat="server" />
</script>

[sample.aspx]
<%@ Register TagPrefix="Sample" TagName="Places" 
             Src="sample.ascx" %>
<form runat=server>
   <Sample:Places id="Control1" runat=server />
</form>

Share via

Caching Multiple Versions of a User Control Based on Parameters

See Also

Additional resources