Caching Multiple Versions of User Control Output

  • Article

Just as you can vary the versions of a page that are output-cached, you can output-cache regions of a page with user controls. You can do this by varying the user control output by the control's name and GET query string or form POST parameter values, or by parameter values alone. You can also cache multiple versions of a user control on a page by declaring it more than once in its containing .aspx file. You can use any of these techniques, whether you specify output caching for the user control with the @ OutputCache directive in the .ascx file or with the PartialCachingAttribute when you develop the user control in a code-behind class.

The @ OutputCache directive for user controls supports four attributes, VaryByParam, VaryByCustom, VaryByControl, and Shared. The PartialCachingAttribute class includes four properties, VaryByParams VaryByControls, VaryByCustom, and Shared, that allow you to use the same techniques by adding an attribute to a user control in a code-behind class.

When an ASP.NET page that contains a user control with output-cache settings is first requested, an instance of the control's output is saved to memory. By default, each page that contains the same user control will add another instance of the control's output to memory when it is requested.

For example, if you created a user control named sample.ascx with output-cache settings and added sample.ascx to 25 ASP.NET pages in your application, there would be at least that many versions of sample.ascx stored in the output cache. In addition, if you use the VaryByControl, VaryByCustom, or VaryByParam attribute to modify the caching behavior of the user control, there could be many more versions of user control output in the cache. For example, assume that you include a TextBox Web server control in your user control and set its ID property to MyTextBox. If you set the VaryByControl attribute to MyTextBox, there will be a version of user control output stored in the cache for every value that the MyTextBox control receives.

If the same user control is used in multiple pages within the same application, you can save memory by setting the Shared attribute of the user control's @ OutputCache directive to true or setting the PartialCachingAttribute.Shared property to true. This means that each page will access the same instance of user control output. Using the Shared property in commonly used and frequently cached user controls can save a significant amount of memory.

There is a major difference between adding user-control output to the output cache and doing the same for page output. While the output cache for both supports using GET query string and form POST parameters to create and cache multiple versions of output, user controls do not support caching based on HTTP headers.

There are four techniques you can use to vary output-cached user controls:

  • You can use the VaryByParam attribute or the PartialCachingAttribute.VaryByParams property, which provide the same functionality as that provided for page output caching. You can set either to any string, but you need to make it equal to the GET query string or form POST parameters that are associated with the user control you create.
  • You can use the VaryByControl attribute or PartialCachingAttribute.VaryByControls property to vary the output-cached user control according to the ID of an ASP.NET server control contained by the user control.
  • You can use the VaryByCustom attribute or PartialCachingAttribute.VaryByCustom property to define code for a custom string that you want to vary the cached user control output by. This works in the same manner as the VaryByCustom technique for varying page output caching. For more information, see Caching Versions of a Page, Based on Custom Strings.
  • You can include multiple instances of a user control in an ASP.NET page. Unless you set the Shared attribute of the @ OutputCache directive to true, output for each instance of the control will be cached.

For detailed information on each of these topics, see Caching Multiple Versions of a User Control, Based on Parameters and Caching Multiple Versions of a User Control Using Declarative Attributes.

See Also

Caching Portions of an ASP.NET Page | Caching Multiple Versions of a User Control, Based on Parameters | Caching Multiple Versions of a User Control Using Declarative Attributes | @ OutputCache | UserControl Class | Web Forms User Controls