CachingProfileElement Class

Article
05/24/2022

Configures caching for a given request extension.

Syntax

class CachingProfileElement : CollectionElement

Methods

This class contains no methods.

Properties

The following table lists the properties exposed by the CachingProfileElement class.

Name	Description
`Duration`	A read/write `datetime` value that specifies the amount of time a response should remain in the cache. The default is 30 seconds. The valid time range is from 0 through 365 days.
`Extension`	A required unique read/write `string` value that specifies the extension of a request that will use the cache profile. The extension must be in the form "EXT" or "", where EXT* is the extension. The key property. Note: No overlapping extension entries are allowed. Each request maps to exactly one `CachingProfileElement` object. If an entry with a "*" exists, other caching profiles with more specific extensions will override the profile with the asterisk. The ordering of profile entries is not important.
`KernelCachePolicy`	A read/write `sint32` value that configures the kernel caching policy. The possible values are listed later in the Remarks section.
`Location`	A read/write `sint32` value that specifies possible locations for the output cache. The possible values are listed later in the Remarks section.
`Policy`	A read/write `sint32` value that configures the output caching policy. The possible values are listed later in the Remarks section.
`VaryByHeaders`	A read/write `string` value that contains a comma-delimited list of header names that the server will use to vary cached responses to the URL.
`VaryByQueryString`	A read/write `string` value that contains a comma-delimited list of query string parameter names that the server will use to vary cached responses to the URL.

Subclasses

This class contains no subclasses.

Remarks

This class corresponds to the <profiles> element under the <system.webServer/caching> section in the ApplicationHost.config file. Instances of this class are contained in the Profiles array property of the CachingProfileSettings class.

The following table lists the possible values for the KernelCachePolicy property. The default is 0 (DontCache).

Value	Keyword	Description
0	`DontCache`	The response will not be cached in the kernel. However, output caching can still occur. Note: This setting overrides any conflicting settings in the `Location` property.
1	`CacheUntilChange`	The response is cached in the HTTP.SYS cache until the entry is invalidated or until it expires after the period of inactivity specified by the `Duration` property.
2	`CacheForTimePeriod`	The response is cached for the amount of time specified by the `Duration` property, even if the entry is invalidated in the interim.
3	`DisableCache`	The cache is disabled and no caching will occur.

The following table lists the possible values for the Location property. The default is 3 (Server).

Value	Keyword	Description
0	`Any`	The response can be cached on the client, Web server, or proxy server.
1	`Client`	The response is cached only on the client.
2	`Downstream`	The response is cached on proxy servers and on the client, but not on the Web server.
3	`Server`	The response is cached only on the Web server.
4	`None`	The response is not cached anywhere.
5	`ServerAndClient`	The response is cached on both the Web server and the client, but not on proxy servers. Note: You can use this setting to avoid sharing content among multiple users on proxy caches when the server has varying behavior for private content.

The following table lists the possible values for the Policy property. The default is 0 (DontCache).

Value	Keyword	Description
0	`DontCache`	The response will not be placed in the output cache. However, kernel caching can still occur.
1	`CacheUntilChange`	The response is cached until the entry is invalidated or until it expires after the period of inactivity specified by the `Duration` property.
2	`CacheForTimePeriod`	The response is cached for the amount of time specified by the `Duration` property, even if the entry is invalidated in the interim.
3	`DisableCache`	The cache is disabled and no caching will occur.

Example

The following example displays all of the CachingProfileElement objects for the default Web site.

' Connect to the WMI WebAdministration namespace.  
Set oWebAdmin = GetObject("winmgmts:root\WebAdministration")  
  
' Get the caching section for the default Web site.  
Set oSite = oWebAdmin.Get("Site.Name='Default Web Site'")  
oSite.GetSection "CachingSection", oSection  

' Display the path and location.  
Wscript.Echo "Path: " & oSection.Path  
Wscript.Echo "Location: " & oSection.Location  
Wscript.Echo

' Display all of the caching profiles for the default Web site.  
For Each oCachingProfileElement In oSection.Profiles.Profiles  
    Wscript.Echo
    WScript.Echo "[ " & oCachingProfileElement.Extension & _  
        " ] Caching Profile"  
    WScript.Echo "-----------------------------------"  
    WScript.Echo "Duration: " & oCachingProfileElement.Duration  
    WScript.Echo "KernelCachePolicy: " & _  
        CachePolicyText(oCachingProfileElement.KernelCachePolicy)  
    WScript.Echo "Location: " & _  
        LocationText(oCachingProfileElement.Location)  
    WScript.Echo "Policy: " & _  
        CachePolicyText(oCachingProfileElement.Policy)  
    WScript.Echo "VaryByHeaders: " & _  
        oCachingProfileElement.VaryByHeaders  
    WScript.Echo "VaryByQueryString: " & _  
        oCachingProfileElement.VaryByQueryString  
    WScript.Echo
Next  

' Provide text for KernelCachePolicy and Policy enumeration values.  
Function CachePolicyText(enumval)  

    Select Case enumval  
        Case 0  
            CachePolicyText="DontCache"  
        Case 1  
            CachePolicyText="CacheUntilChange"  
        Case 2  
            CachePolicyText="CacheForTimePeriod"  
        Case 3  
            CachePolicyText="DisableCache"  
        Case Else  
            CachePolicyText="Undefined enumeration value"  
    End Select  

End Function  

' Provide text for Location enumeration values.  
Function LocationText(enumval)  

    Select Case enumval  
        Case 0  
            LocationText="Any"  
        Case 1  
            LocationText="Client"  
        Case 2  
            GetLocationText="Downstream"  
        Case 3  
            LocationText="Server"  
        Case 4  
            LocationText="None"  
        Case 5  
            LocationText="ServerAndClient"  
        Case Else  
            LocationText="Undefined enumeration value"  
    End Select  

End Function

Inheritance Hierarchy

CollectionElement

CachingProfileElement

Requirements

Type	Description
Client	- IIS 7.0 on Windows Vista - IIS 7.5 on Windows 7 - IIS 8.0 on Windows 8 - IIS 10.0 on Windows 10
Server	- IIS 7.0 on Windows Server 2008 - IIS 7.5 on Windows Server 2008 R2 - IIS 8.0 on Windows Server 2012 - IIS 8.5 on Windows Server 2012 R2 - IIS 10.0 on Windows Server 2016
Product	- IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0
MOF file	WebAdministration.mof

Share via