This documentation is archived and is not being maintained.

Substitution Class

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 Substitution control.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

public class Substitution : Control
public class Substitution extends Control
public class Substitution extends Control
Not applicable.

Use the Substitution control to specify a section on an output-cached Web page where you want dynamic content substituted for the control. The Substitution 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 Substitution 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 Substitution control in a user control that is contained in a cached page. However, you cannot place a Substitution control in an output-cached user control.

When the Substitution 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 Substitution control. Use the MethodName property to specify the name of the callback method to invoke when the Substitution control executes. The callback method that you specify must be a static method on the page or user control that contains the Substitution 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 Substitution 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 Substitution 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 Substitution 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"
<script runat="server" language="C#">  
  void Page_Load(object sender, System.EventArgs e)
    // Display the current date and time in the label.
    // Output caching applies to this section of the page.
    CachedDateLabel.Text = DateTime.Now.ToString();    
  // The Substitution control calls this method to retrieve
  // the current date and time. This section of the page
  // is exempt from output caching. 
  public static string GetCurrentDateTime (HttpContext context)
    return DateTime.Now.ToString ();

<html xmlns="" >
<head runat="server">
  <title>Substitution Class Example</title>
  <form id="form1" runat="server">
    <h3>Substitution Class Example</h3>  
    <p>This section of the page is not cached:</p>
    <asp:substitution id="Substitution1"
    <br />
    <p>This section of the page is cached:</p>
    <asp:label id="CachedDateLabel"
    <br /><br />
    <asp:button id="RefreshButton"
      text="Refresh Page"


  • AspNetHostingPermission  for operating in a hosted environment. Demand value: LinkDemand; Permission value: Minimal.
  • AspNetHostingPermission  for operating in a hosted environment. Demand value: InheritanceDemand; Permission value: Minimal.


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0