ASP.NET Cache Examples

Cache HTTP headers improve performance.

Caching with HTTP headers is important to every web site. There are many complicated rules and conflicts among the headers. HTTP headers are key in ASP.NET and the C# language.

Expires headers. First, we know that ASP.NET websites may use ASPX files or ASHX handlers to serve static content like images. Keeping with Yahoo's guidelines, use this ASP.NET C# code to set Expires in the far future.

Tip: IIS7 will set the Cache-Control header automatically when you specify SetExpires.

However: There are other options available. Please see the section on Cache-Control headers.

Page that uses Response.Cache: C#

using System;
using System.Web.UI;

public partial class _Default : Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
	// Set this ASPX response to expire in one year.
	// ... This is essentially 'never'.
	Response.Cache.SetExpires(DateTime.Now.AddYears(1));
    }
}

Static resources. Almost all big websites have static resources—certain images that never change, such as logos. Yahoo says to use "the Expires header in the HTTP response to tell the client how long a component can be cached."

Tip: Please see "Best Practices for Speeding Up Your Web Site" at developer.yahoo.com.

Info: Yahoo notes that "this is a far future Expires header... this response won't be stale until April 15, 2010."

Note: The time format is very specific and you will need to use a special DateTime format in the C# language.

Example Expires HTTP Header:

Expires: Thu, 15 Apr 2010 20:00:00 GMT

Dynamic pages. Yahoo recommends the Cache-Control header for dynamic pages. There are several variants. Yahoo's best practices: "For dynamic components: use an appropriate Cache-Control header to help the browser with conditional requests."

So: Using Cache-Control gives you overriding power on the cache setting, allowing you to specify options for proxies and the server.

Fiddler. You can use the Fiddler tool with HTTP headers. When developing ASP.NET applications with caching, you should use Fiddler, or another equivalent tool, to look at the HTTP headers. I have written about Fiddler.

Fiddler Tool

Cache-Control. Here we look at Cache-Control headers in ASP.NET. The implementation of caching on Response.Cache is complex and confusing in ASP.NET. Some options will trigger other options. These interactions are hard to understand.

Tip: Setting a page for one hour of caching is done like the following example. Cache-Control "helps browsers" with conditional requests.

Page that uses Response.Cache and Cache-Control: C#

using System;
using System.Web;
using System.Web.UI;

public partial class _Default : Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
	// Set cache for 1 hour on all computers and servers.
	// ... Proxies, browsers, and your server will cache it.
	Response.Cache.SetCacheability(HttpCacheability.Public);
	Response.Cache.SetMaxAge(new TimeSpan(1, 0, 0));
    }
}

Cache methods. Code-behind cache methods and properties are used to control the HTTP cache settings on your ASP.NET response. They must be called on the HttpResponse object, using the Response.Cache-style syntax.

Cache methods

AppendCacheExtension:
Adds a custom header to the Cache-Control header.

SetAllowResponseInBrowserHistory:
This overrides certain settings made by SetCacheability,
such as NoCache and ServerAndNoCache.

SetExpires:
Useful for static resources such as images.

SetLastModified:
Date your file and return a 304 when a user requests the same one again.
This doesn't save an HTTP request.
Yahoo recommends modified dates over ETags.

SetMaxAge:
This gives you a relative time window for a resource to be cached.
It is an alternative to the Expires header.
It overrides the Expires header.

SetSlidingExpiration:
Changes the logic of when the server expires its cache.
Has many quirks and you must carefully test it.

SetValidUntilExpires:
Don't listen to browsers when they say a resource is expired or stale.
Otherwise, they can invalidate caches.

ETag methods. These methods affect the ETag header sent from the server. Yahoo recommends avoiding ETags and instead using modified dates. But these methods are helpful in some contexts. Often, though, they are not needed.

ETag methods

SetETag:
Specify a string that is considered the tag of a resource.
This is not recommended by Yahoo and not normally needed.

SetETagFromFileDependencies:
Tells ASP.NET to assign random etags keyed to the file contents.
Simplifies ETag usage.
Not normally needed.

Vary methods. Several methods affect how the vary headers are returned by ASP.NET. This header controls proxy caching. Changing vary headers can eliminate certain hard-to-diagnose bugs. I describe them in slightly more detail.

Vary methods

SetOmitVaryStar:
This method changes a header when using vary parameters.
It is not often useful.

SetVaryByCustom:
Allows you to set the custom vary header.
Useful when you have the Vary header.

VaryByContentEncodings, VaryByHeaders, VaryByParams:
These are public getters only.
You cannot set these properties.
They are useful for debugging and diagnostics of your Vary header.

HttpCacheability. You need to call SetCacheability on the Response.Cache to set the main Cache-Control header. This header controls the location and general behavior of the cache. You need to combine this setting with other Cache class method calls.

HttpCacheability options

SetCacheability:
This is important and sets the Cache-Control header.
See the list of HttpCacheability enums below.

HttpCacheability.NoCache:
Tells the browser, the server, and proxies to never cache this resource.
Useful for advertisements and resources that are always changing.

HttpCacheability.Private:
Only cache on the browser.
This will provide bandwidth savings for your users.
Your server won't store a cached copy of the output.
This is adequate for many sites.

HttpCacheability.Public:
The ultimate cache setting.
Tells the server to save the page, proxy caches to save the page,
and the browser to save the page.

HttpCacheability.Server:
Only cache the page on the server (output caching without browser caching).
However, when your visitors click on your static pages, they will be reloaded.

HttpCacheability.ServerAndNoCache:
The same as NoCache except it allows the server to store the page.
Has slightly different meaning for remote clients and proxies.

HttpCacheability.ServerAndPrivate:
Tells proxy caches to never cache this page.
But allow the browser and the server to cache it.

Private caches. Private is a term that means the web browser on your users' computers. By using private, your users won't download or re-request the pages they have viewed. This reduces the work your server does and the bandwidth you use.

And: It refuses proxy servers and your own server caches, meaning you still have much CPU use and bandwidth use.

Expires, Max-Age. The two HTTP headers both target the client-side caching, but have a semantic difference. Max-Age, part of the Cache-Control, is relative to the current time, making it easier to use in many cases.

And: It "specifies the maximum amount of time that a representation will be considered fresh."

Further: Max-Age is "similar to Expires... relative to the time of the request, rather than absolute."

Caching Tutorial

Max-Age, Expires. When looking at the specification for HTTP, you will see that Max-Age and Expires conflict. From the HTTP spec: "If a response includes both an Expires header and a max-age directive, the max-age directive overrides the Expires header."

Hypertext Transfer Protocol

Public proxy caches. There are complexities when considering proxy caching. I am not certain how common public proxy caches are, but when available, they can reduce your bandwidth and improve access times. They serve up your pages for you, for free.

Squid reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. [It] optimizes the data flow between client and server.

Squid: Optimizing Web Delivery

Vary. If you look at the HTTP headers of MySpace, for example, you see the header "Vary: Accept-Encoding". This means that the caches will be separate for each encoding. This improves localization. You can use SetVaryByCustom to change this.

Note: This is a suggestion to proxy servers, and does not improve the rate of cache hits.

Handler.ashx. First, you can use HTTP handlers in ASP.NET for a faster way to server dynamic content than Web Form pages. Handler.ashx is the default name for an ASP.NET generic handler. We use the HttpContext parameter and access the Response.

ASHX Handler

HTTP Handler that uses caching: C#

<%@ WebHandler Language="C#" Class="Handler" %>

using System;
using System.Web;

public class Handler : IHttpHandler {

    public void ProcessRequest (HttpContext context) {
	// Cache this handler response for 1 hour.
	HttpCachePolicy c = context.Response.Cache;
	c.SetCacheability(HttpCacheability.Public);
	c.SetMaxAge(new TimeSpan(1, 0, 0));
    }

    public bool IsReusable {
	get {
	    return false;
	}
    }
}

Remove Cache-Control. You can remove the Cache-Control header in ASP.NET by configuring the application. When you use the Expires header on static resources such as JavaScript, CSS, and images, you do not need the Cache-Control header.

Info: Cache-Control and Expires are alternatives and are not both needed. You can disable the HTTP Cache-Control header in Web.config.

Also: This setting is defeated if you change cache headers during execution. The setting is overridden.

Example Web.config: XML

<?xml version="1.0"?>
<configuration>
    <appSettings/>
    <connectionStrings/>
    <system.web>
	<httpRuntime sendCacheControlHeader="false"/>
    <!-- More XML here. -->

DateTime. As noted above, HTTP dates have a specific format you must follow. Fortunately, the .NET Framework provides a format pattern string for this. You can use a special format string, after converting the date into the current time zone.

Tip: For more information on HTTP date formats, such as the RFC1123 pattern, please see the Microsoft site.

Standard Date and Time Format: MSDNDateTime

Page that converts DateTime: C#

using System;
using System.Web.UI;

public partial class _Default : Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
	DateTime d = DateTime.UtcNow;
	string s = d.ToUniversalTime().ToString("r");
	Response.Write(s);
    }
}

Options. There is a Cache object you can use to store data programmatically. This is separate from the methods shown here, and has many different options. This document focuses on HTTP headers.

And: On the server-side, the Cache[] object is useful. But it does not address the client-side caching in browsers.

Response.Cache. There are several different ways to access the Cache. The examples above show how you can access it in the Page class and also from generic handlers. However, Cache is an intrinsic object.

HttpContext Request

Performance of using properties. My research indicates that accessing the Response.Cache property in each method call may not be ideal, and storing the HttpCachePolicy as a variable is better.

Response.Write

Summary. We used HTTP headers in ASP.NET to enhance performance of pages. We did not cover server-side database caching and other complex topics. We focused on the client-side HTTP headers and client-side caching.

Related Links