Caching Multiple Versions of User Control Output
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 the GET query string or form POST parameter values, or by varying the output 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 attribute 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 twenty-five 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 by setting the Shared property on the control's PartialCachingAttribute attribute 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 VaryByParams property of the PartialCachingAttribute class, 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 the VaryByControls property of the PartialCachingAttribute class to vary the output-cached user control according to the ID property of an ASP.NET server control contained by the user control.
You can use the VaryByCustom attribute or the VaryByCustom property of the PartialCachingAttribute class 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 VaryByControl attribute technique for varying page output caching. For more information, see How to: Cache Versions of a Page Using 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 more information on each of these topics, see How to: Cache Multiple Versions of a User Control Based on Parameters and How to: Cache Multiple Versions of a User Control by Using Declarative Attributes.
See Also
Tasks
How to: Cache Multiple Versions of a User Control Based on Parameters
How to: Cache Multiple Versions of a User Control by Using Declarative Attributes
Concepts
Caching Multiple Versions of a Page