Description

The Microsoft.SharePoint.WebControls.PostCacheSubstitutionText class inherits from the System.Web.UI.Control class providing required functionality for ASP.NET server controls. Understanding the use of the PostCacheSubsitutionText control is heavily related to the difference between fragment caching, where a small portion of the page is cached, as opposed to Post-Cache Substitution where the entire page is cached, except a much smaller segment that is kept dynamic. Post-Cache Substitution was introduced in ASP.NET 2.0 in order to dynamically update portions of cached WebForms for performance reasons.

When ASP.NET retrieves the cached page, the callback methods to the dynamic content are triggered, then that content is inserted into the cached page. The PostCacheSubstitutionText class provides inherent mechanisms to strongly type and manage this content, as well as ensure it is an actual user, and not a robot.

The type of content managed is determined by the PostCacheSubstitutionTextType enumeration. For example, there are SharePoint hooks to manage common text like Username, and web titles. For example, within the Microsoft.SharePoint.WebControls.PersonalActions the UserId is targeted by specifying the PostCacheSubstitutionText.TextType property to PostCacheSubstitutionTextType.UserId.

Usage Scenario

The primary usage of the PostCacheSubsitutionText class is internal to aid in the callbacks for different types of content that are cached defined by the Microsoft.SharePoint.WebControls.PostCacheSubstitutionTextType enumeration. However, use is analogous to any Control and is possible to use within custom development.

In the below, the MyClass class is inheriting from the Microsoft.SharePoint.WebControls.ToolBarMenuButton class since it is common to have controls such as user and identifier controls rendered through a ToolBarMenuButton control collection. In the overridden CreateChildControls method, a new PostCacheSubstitutionText object is being created with type PostCacheSubstitutionTextType.UserId, set to a declared prefix and suffix HTML string within the PostCacheSubstitutionTextType.PrefixHtml and PostCacheSubstitutionTextType.PrefixHtml properties. Following, the created PostCacheSubstitutionText object is added to the current instance control collection.

C# Code Example

public class MyClass : ToolBarButton
    {
        protected override void CreateChildControls()
        {
            PostCacheSubstitutionText text = new PostCacheSubstitutionText();
            text.TextType = PostCacheSubstitutionTextType.UserId;
            text.PrefixHtml = @"<prefix>";
            text.SuffixHtml = @"<suffix>";
            Controls.Add(text);
            base.CreateChildControls();
        }
    }

VB.NET Code Example

Public Class [MyClass]
    Inherits ToolBarButton
    Protected Overloads Overrides Sub CreateChildControls()
        Dim text As New PostCacheSubstitutionText()
        text.TextType = PostCacheSubstitutionTextType.UserId
        text.PrefixHtml = "<prefix>"
        text.SuffixHtml = "<suffix>"
        Controls.Add(text)
        MyBase.CreateChildControls()
    End Sub
End Class