This documentation is archived and is not being maintained.

Checking the Validity of a Cached Page

When the output cache has an existing entry that it would like to use as a response to a client request, it must first check with the origin server (or an intermediate cache, such as a proxy server, with a fresh response) to determine if the cached entry is still usable. This process is called validating the cache entry. To avoid wasting resources either from regenerating and retransmitting the page if the cached entry is valid or from an extra round trip if the cached entry is invalid, ASP.NET provides a mechanism for you to validate a cached page programmatically.

Note   For more information about cache validity and its requirements, see the HTTP 1.1 specification at www.w3.org.

To determine the validity of a cached page, you must define an event handler with the same signature as the HttpCacheValidateHandler delegate. This handler should perform a check to determine if the page stored in the cache remains valid, then assign one of the HttpValidationStatus enumeration values to the possible returns from the check. This enumeration has three values:

  • Invalid, which indicates that the cached page is invalid, the page is evicted from the cache, and the request is handled as a cache miss.
  • IgnoreThisRequest, which causes the request to be treated as a cache miss and the page is executed, but the cached page is not invalidated.
  • Valid, which indicates that the cached page remains valid.

In one of the page lifecycle events, the HttpCachePolicy.AddValidationCallback method takes your event handler as a parameter. Before the response is served from the Web server cache, all registered handlers are queried to ensure resource validity. If any handler sets a flag that indicates the resource is invalid, the entry is marked invalid and evicted from the cache. The request is then handled as if it were a cache miss.

To check the validity of a cached page

  1. Define an event handler of type HttpCacheValidateHandler that checks the validity of the cached page response.

    The following example creates an event handler, Validate, that checks the Text property value of a myText TextBox Web server control. Depending upon the value entered in the text box, Validate returns the appropriate HttpValidationStatus enumeration value.

    public void Validate(HttpContext context, Object data, ref HttpValidationStatus status) 
    {
        if (myText.Text == "false") {
          status = HttpValidationStatus.Invalid;
        } else if (myText.Text == "ignore") {
          status = HttpValidationStatus.IgnoreThisRequest;
        } else {
          status = HttpValidationStatus.Valid;
        }
    }
    [Visual Basic]
    Public Sub Validate(context As HttpContext, data As [Object], ByRef status As HttpValidationStatus)
       If myText.Text = "false" Then
          status = HttpValidationStatus.Invalid
       Else
          If myText.Text = "ignore" Then
             status = HttpValidationStatus.IgnoreThisRequest
          Else
             status = HttpValidationStatus.Valid
          End If
       End If
    End Sub 'Validate
    
  2. From one of the page lifecycle events, call the HttpCachePolicy.AddValidationCallback method, passing the event handler you defined in the first parameter argument in step 1.

    In the following code example, the Page_Load method calls AddValidationCallback with the Validate event handler that was passed in the first parameter argument in step 1.

    public void Page_Load(){
        Response.Cache.AddValidationCallback(new HttpCacheValidateHandler(Validate), null);
      }
    [Visual Basic]
    Public Sub Page_Load()
       Response.Cache.AddValidationCallback(New HttpCacheValidateHandler(Validate), Nothing)
    End Sub 'Page_Load
    

The following example uses the event handler defined in step one with the code in step 2 and writes a time stamp to the page.

Note   This example is intended to easily show how a page in the cache can be invalidated. Most scenarios you create should validate the page against some state on the server, which is associated with the page that changes.
<%@ OutputCache Duration=100 varybyparam="none" %>
<Script Language="C#" runat="server">

  public void Page_Load(){

    if(!IsPostback) {
       myText.Text = "Enter validation request." ;
    }

    Response.Cache.AddValidationCallback(new HttpCacheValidateHandler(Validate), null);
    stamp.InnerHtml = DateTime.Now.ToString("r");
  }

public void Button1_Click(){  
   Validate();
}  

public void Validate(HttpContext context, Object data, ref HttpValidationStatus status) {
    if (myText.Text == "false") {
      status = HttpValidationStatus.Invalid;
    } else if (myText.Text == "ignore") {
      status = HttpValidationStatus.IgnoreThisRequest;
    } else {
      status = HttpValidationStatus.Valid;
    }
  }
</Script>
<form runat="server" >
<asp:textbox id="myText" runat="server" />
<br>
<asp:button id="mybutton" click="Button1_Click" text="Click here to validate page." runat="server" />
</form>
<br>
<b>In the text box, enter false to invalidate the cached page, ignore to ignore the current request, or any other string to leave the output cached page valid. </b>
<br>
<br>
<Font size=6><B id=stamp runat=server /></Font>
[Visual Basic]
<%@ OutputCache Duration=100 varybyparam="none" %>
<Script Language="VB" runat="server">

Public Sub Page_Load()
   
   If Not IsPostback Then
      myText.Text = "Enter validation request."
   End If
   
   Response.Cache.AddValidationCallback(New HttpCacheValidateHandler(Validate), Nothing)
   stamp.InnerHtml = DateTime.Now.ToString("r")
End Sub 'Page_Load

Public Sub Button1_Click()
   
   Validate()
End Sub 'Button1_Click
 
Public Sub Validate(context As HttpContext, data As [Object], ByRef status As HttpValidationStatus)
   If myText.Text = "false" Then
      status = HttpValidationStatus.Invalid
   Else
      If myText.Text = "ignore" Then
         status = HttpValidationStatus.IgnoreThisRequest
      Else
         status = HttpValidationStatus.Valid
      End If
   End If
End Sub 'Validate
</Script>

<form runat="server" >
<asp:textbox id="myText" runat="server" />
<br>
<asp:button id="mybutton" click="Button1_Click" text="Click here to validate page." runat="server" />
</form>
<br>
<b>In the text box, enter false to invalidate the cached page, ignore to ignore the current request, or any other string to leave the output cached page valid. </b>
<br>
<br>
<Font size=6><B id=stamp runat=server /></Font>

See Also

Caching ASP.NET Pages | HttpValidationStatus Enumeration | HttpResponse Class | HttpRequest Class | HttpCachePolicy Class | HttpCachePolicy.AddValidationCallback Method | HttpCacheValidateHandler Delegate | @ OutputCache

Show: