IIS - Microsoft Internet Information Services

Home›Configuration Reference›system.webServer›staticContent›clientCache

Client Cache <clientCache>

Overview

The <clientCache> element of the <staticContent> element specifies cache-related HTTP headers that Internet Information Services (IIS) 7.0 sends to Web clients, which control how Web clients and proxy servers will cache the content that IIS 7.0 returns.

For example, the httpExpires attribute specifies a date and time that the content should expire, and IIS 7.0 will add an HTTP "Expires" header to the response. The value for the httpExpires attribute must be a fully-formatted date and time that follows the specification in RFC 1123. For example:

Fri, 01 Jan 2010 12:00:00 GMT

Note: To use the httpExpires attribute, you need to set the value of the cacheControlMode attribute to UseExpires.

The HTTP 1.1 specification in Request For Comments (RFC) 2616 specifies several possible values for the HTTP "Cache-Control" header, such as "no-cache," "private," "public," etc. Each of these header values lets Web clients and proxy servers know whether they should cache the content:

  • Content that contains a "no-cache" header should not be cached by any entity.
  • Content that contains a "private" header should not be cached a proxy server, but may be cached by a Web client.
  • Content that contains a "public" header may be cached by any entity.

    Note: The above list is not comprehensive - there are many additional values that can be specified by the "Cache-Control" header.

Additional directives can be added to the HTTP "Cache-Control" header, such as "max-age," which specifies the explicit expiration time for content. In IIS 7.0, the "max-age" directive is configured through the cacheControlMaxAge attribute. While the "Expires" and "max-age" settings are somewhat analogous, the "max-age" directive takes priority over "Expires".

Note: To use the cacheControlMaxAge attribute, you need to set the value of the cacheControlMode attribute to UseMaxAge.

For more information on HTTP caching headers and date/time formats, see the following Request For Comments (RFC) articles:

  • RFC 1123 - "Requirements for Internet Hosts -- Application and Support"
  • RFC 2616 - "Hypertext Transfer Protocol -- HTTP/1.1"

Compatibility

  IIS 7.0 IIS 6.0
Notes The <clientCache> element of the <staticContent> element is new in IIS 7.0. The <clientCache> element replaces the following IIS 6.0 metabase properties:

CacheControlCustom
CacheControlMaxAge
CacheControlNoCache
HttpExpires

Setup

The <clientCache> element of the <staticContent> element is included in the default installation of IIS 7.0.

How To

How to configure a cache expiration date for a Web site or application

  1. On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
  2. In the Connections pane, go to the site, application, or directory for which you want to disable caching.
  3. In the Home pane, double-click HTTP Response Headers.

    Enlarge

  4. In the HTTP Response Headers pane, click Set Common Headers... in the Actions pane.

    Enlarge

  5. In the Set Common HTTP Response Headers dialog box, check the box to expire Web content, select the option to expire after a specific interval or at a specific time, and then click OK.

    Enlarge

    Enlarge

How to disable caching for a Web site or application

  1. On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
  2. In the Connections pane, go to the site, application, or directory for which you want to disable caching.
  3. In the Home pane, double-click HTTP Response Headers.

    Enlarge

  4. In the HTTP Response Headers pane, click Set Common Headers... in the Actions pane.

    Enlarge

  5. In the Set Common HTTP Response Headers dialog box, check the box to expire Web content, select Immediately, and then click OK.

    Enlarge

Configuration

Attributes

Attribute Description
cacheControlCustom Optional string attribute.

Specifies custom HTTP 1.1 cache control directives.
cacheControlMaxAge Optional timeSpan attribute.

Specifies the maximum age (in seconds) of the cache control value.

The default value is 1.00:00:00 (1 day).
cacheControlMode Optional enum attribute.

Specifies the mode to use for client caching.

The cacheControlMode attribute can be one of the following possible values.

The default is NoControl.
Value Description
NoControl Does not add a Cache-Control or Expires header to the response.

The numeric value is 0.
DisableCache Adds a Cache-Control: no-cache header to the response.

The numeric value is 1.
UseMaxAge Adds a Cache-Control: max-age=<nnn> header to the response based on the value specified in the CacheControlMaxAge attribute.

The numeric value is 2.
UseExpires Adds an Expires: <date> header to the response based on the date specified in the httpExpires attribute.

The numeric value is 3.
httpExpires Optional string attribute.

Specifies the date and time after which a page that is cached on the client is considered stale. (The date and time is formatted according to the specification in Request for Comments 1123.) The value is returned to the browser in the HTML file header. The user agent compares the given value with the current date to determine whether to display a cached page or to request an updated page from the server.

Child Elements

None.

Configuration Sample

The following configuration sample adds an HTTP "Cache-Control: no-cache" header to the response, thereby disabling caching of requests.

<configuration>
   <system.webServer>
      <staticContent>
         <clientCache cacheControlMode="DisableCache" />
      </staticContent>
   </system.webServer>
</configuration>

The following configuration sample adds an HTTP "Expires: Tue, 19 Jan 2038 03:14:07 GMT" header to the response, which configures requests to expire several years from now.

<configuration>
   <system.webServer>
      <staticContent>
         <clientCache cacheControlMode="UseExpires"
            httpExpires="Tue, 19 Jan 2038 03:14:07 GMT" />
      </staticContent>
   </system.webServer>
</configuration>

Sample Code

The following code samples add an HTTP "Cache-Control: no-cache" header to the response, thereby disabling caching of requests.

AppCmd.exe

appcmd.exe set config "Default Web Site" -section:system.webServer/staticContent /clientCache.cacheControlMode:"DisableCache"

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using(ServerManager serverManager = new ServerManager())
      { 
         Configuration config = serverManager.GetWebConfiguration("Default Web Site");
         ConfigurationSection staticContentSection = config.GetSection("system.webServer/staticContent");

         ConfigurationElement clientCacheElement = staticContentSection.GetChildElement("clientCache");
         clientCacheElement["cacheControlMode"] = @"DisableCache";

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample

   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Default Web Site")
      Dim staticContentSection As ConfigurationSection = config.GetSection("system.webServer/staticContent")

      Dim clientCacheElement As ConfigurationElement = staticContentSection.GetChildElement("clientCache")
      clientCacheElement("cacheControlMode") = "DisableCache"

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site";

var staticContentSection = adminManager.GetAdminSection("system.webServer/staticContent", "MACHINE/WEBROOT/APPHOST/Default Web Site");
var clientCacheElement = staticContentSection.ChildElements.Item("clientCache");
clientCacheElement.Properties.Item("cacheControlMode").Value = "DisableCache";

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site"

Set staticContentSection = adminManager.GetAdminSection("system.webServer/staticContent", "MACHINE/WEBROOT/APPHOST/Default Web Site")
Set clientCacheElement = staticContentSection.ChildElements.Item("clientCache")
clientCacheElement.Properties.Item("cacheControlMode").Value = "DisableCache"

adminManager.CommitChanges()

The following code samples add an HTTP "Expires: Tue, 19 Jan 2038 03:14:07 GMT" header to the response, which configures requests to expire several years from now.

AppCmd.exe

appcmd.exe set config "Default Web Site" -section:system.webServer/staticContent /clientCache.cacheControlMode:"UseExpires"

appcmd.exe set config "Default Web Site" -section:system.webServer/staticContent /clientCache.httpExpires:"Tue, 19 Jan 2038 03:14:07 GMT"

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using(ServerManager serverManager = new ServerManager())
      { 
         Configuration config = serverManager.GetWebConfiguration("Default Web Site");
         ConfigurationSection staticContentSection = config.GetSection("system.webServer/staticContent");

         ConfigurationElement clientCacheElement = staticContentSection.GetChildElement("clientCache");
         clientCacheElement["cacheControlMode"] = @"UseExpires";
         clientCacheElement["httpExpires"] = @"Tue, 19 Jan 2038 03:14:07 GMT";

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample

   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Default Web Site")
      Dim staticContentSection As ConfigurationSection = config.GetSection("system.webServer/staticContent")

      Dim clientCacheElement As ConfigurationElement = staticContentSection.GetChildElement("clientCache")
      clientCacheElement("cacheControlMode") = "UseExpires"
      clientCacheElement("httpExpires") = "Tue, 19 Jan 2038 03:14:07 GMT"

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site";

var staticContentSection = adminManager.GetAdminSection("system.webServer/staticContent", "MACHINE/WEBROOT/APPHOST/Default Web Site");
var clientCacheElement = staticContentSection.ChildElements.Item("clientCache");
clientCacheElement.Properties.Item("cacheControlMode").Value = "UseExpires";
clientCacheElement.Properties.Item("httpExpires").Value = "Tue, 19 Jan 2038 03:14:07 GMT";

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site"

Set staticContentSection = adminManager.GetAdminSection("system.webServer/staticContent", "MACHINE/WEBROOT/APPHOST/Default Web Site")
Set clientCacheElement = staticContentSection.ChildElements.Item("clientCache")
clientCacheElement.Properties.Item("cacheControlMode").Value = "UseExpires"
clientCacheElement.Properties.Item("httpExpires").Value = "Tue, 19 Jan 2038 03:14:07 GMT"

adminManager.CommitChanges()

Configuration Settings