Substitution Web Server Control Overview

Substitution Web Server Control Ove...

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

ASP.NET

Substitution Web Server Control Overview

The Substitution control lets you create areas on the page that can be updated dynamically and then integrated into a cached page.

This topic contains:

Scenarios
Background
Code Examples
Class Reference

Scenarios

Use the Substitution control to specify a section of an output-cached Web page where you want to display dynamic content. 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 read from the cache until the cache entry expires or is purged. Dynamic regions execute every time that 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 frequently, which means that they can be cached. However, every time that 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 every time that the page posts back, regardless of whether the page is cached.

Background

When an ASP.NET page is cached, by default the entire output of the page is cached. On the first request, the page runs and caches its output. On subsequent requests, the request is fulfilled from the cache and code on the page does not run.

In some circumstances, you might want to cache an ASP.NET page but update selected portions of the page on every request. For example, you might want to cache the majority of a page but be able to dynamically update time-sensitive information on the page.

You can use the Substitution control to insert dynamic content into the cached page. The Substitution control does not render any markup. Instead, you bind the control to a method on the page or on a parent user control. You create a static method that returns the information that you want to insert into the page. The method called by the Substitution control must meet the following criteria:

It must be a static method (shared in Visual Basic).
It must accept a parameter of type HttpContext.
It must return a value of type String.

Other controls on the page are not accessible to the Substitution control—that is, you cannot examine or change the value of other controls. However, the code does have access to the current page context by using the parameter passed to it.

When the page runs, the Substitution control calls the method and then substitutes the return value from the method for the Substitution control on the page.

Code Examples

The following example shows how to use the Substitution control to create dynamically updated content on a cached page. Code in the page's Load event updates a Label control with the current time. Because the page's cache duration is set to 60 seconds, the text of the Label control does not change even if the page is requested multiple times during the 60-second period. A Substitution control on the page calls the static method GetTime, which returns the current time as a string. Every time that the page is refreshed, the value represented by the Substitution control is updated.

Visual Basic

<%@ Page Language="VB" %>
<%@ OutputCache Duration=60 VaryByParam="None" %>

<script runat="server">
    Sub Page_Load()
        Label1.Text = DateTime.Now.ToString()
    End Sub

    Public Shared Function GetTime(ByVal context As HttpContext) _
            As String
        Return DateTime.Now.ToString()
    End Function
</script>

<html>
<head runat="server"></head>
<body>
    <form id="form1" runat="server">
    <div>
    <p>
    <asp:Label runat="server" ID="Label1" />
    </p>
    <p>
    <asp:Substitution runat="server" 
        ID="Substitution1" 
        MethodName="GetTime" />
    </p>
    <p>
    <asp:Button runat="server" ID="Button1" Text="Submit"/>
    </p>
    </div>
    </form>
</body>
</html>

<%@ Page Language="C#" %>
<%@ OutputCache Duration=60 VaryByParam="None" %>

<script runat="server">
    void Page_Load()
    {
        Label1.Text = DateTime.Now.ToString();
    }
    
    public static String GetTime(HttpContext context)
    {
      return DateTime.Now.ToString();
    }
</script>
<html>
<head runat="server"></head>
<body>
    <form id="form1" runat="server">
    <div>
    <p>
    <asp:Label runat="server" ID="Label1" />
    </p>
    <p>
    <asp:Substitution runat="server" 
        ID="Substitution1" 
        MethodName="GetTime" />
    </p>
    <p>
    <asp:Button runat="server" ID="Button1" Text="Submit"/>
    </p>
    </div>
    </form>
</body>
</html>

Class Reference

The following table lists the classes that relate to the Substitution control.

Member	Description
Substitution	The main class for the control.

Concepts

Dynamically Updating Portions of a Cached Page