Specifies a section on an output-cached Web page that is exempt from caching. At this location, dynamic content is retrieved and substituted for the control.
Assembly: System.Web (in System.Web.dll)
'Declaration <AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _ <AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _ Public Class Substitution _ Inherits Control 'Usage Dim instance As Substitution
Use the control to specify a section on an output-cached Web page where you want dynamic content substituted for the control. The control offers a simplified solution to partial page caching for pages where the majority of the content is cached. You can output-cache the entire page, and then use controls to specify the parts of the page that are exempt from caching. Cached regions execute only once and are replayed from the cache until the cache entry expires or is purged. Dynamic regions execute each time the page is requested. This caching model simplifies the code for pages that are primarily static, because you do not have to encapsulate the sections to cache in Web user controls. For example, this caching model is useful in a scenario where you have a page that contains static content, such as news stories, and an AdRotator control that displays advertisements. The news stories do not change, which means that they can be cached. However, each time a user requests the page, you want to display a new advertisement. The AdRotator control directly supports post-cache substitution and renders a new advertisement each time the page posts back, regardless of whether the page is cached.
You can place a control in a user control that is contained in a cached page. However, you cannot place a control in an output-cached user control.
When the control executes, it calls a method that returns a string. The string that the method returns is the content to display on the page at the location of the control. Use the MethodName property to specify the name of the callback method to invoke when the control executes. The callback method that you specify must be a static method on the page or user control that contains the control. The signature for the callback method must match the signature for an HttpResponseSubstitutionCallback delegate that takes an HttpContext parameter and returns a string.
To manipulate the output cache for a page, you can use the @ OutputCache directive, the HttpCachePolicy class, or the Cache property. For more information on caching pages, see Caching ASP.NET Pages and Caching Portions of an ASP.NET Page.
As an alternative to using the control, you can also get substitution caching behavior using a HttpResponseSubstitutionCallback delegate. In addition, you can get substitution caching behavior on controls, such as the AdRotator control, that directly support this feature. For more information, see Dynamically Updating Portions of a Cached Page.
The following code example demonstrates how to add a control declaratively to an output-cached Web page. When the page loads, the current date and time are displayed to the user in a label. This section of the page is cached and updated only every 60 seconds. When the control executes, it calls the GetCurrentDateTime method. The string returned by GetCurrentDateTime is displayed to the user. This section of the page is not cached and is updated each time the page is refreshed.
<%@ outputcache duration="60" varybyparam="none" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <script runat="server" language="VB"> Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) ' Display the current date and time in the label. ' Output caching applies to this section of the page. CachedDateLabel.Text = DateTime.Now.ToString() End Sub ' The Substitution control calls this method to retrieve ' the current date and time. This section of the page ' is exempt from output caching. Shared Function GetCurrentDateTime(ByVal context As HttpContext) As String Return DateTime.Now.ToString() End Function </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head id="Head1" runat="server"> <title>Substitution Class Example</title> </head> <body> <form id="Form1" runat="server"> <h3>Substitution Class Example</h3> <p>This section of the page is not cached:</p> <asp:substitution id="Substitution1" methodname="GetCurrentDateTime" runat="Server"> </asp:substitution> <br /> <p>This section of the page is cached:</p> <asp:label id="CachedDateLabel" runat="Server"> </asp:label> <br /><br /> <asp:button id="RefreshButton" text="Refresh Page" runat="Server"> </asp:button> </form> </body> </html>
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.