Skip to content

OutputCacheModuleAsync.md

Latest commit

 

History

History
132 lines (96 loc) · 6.14 KB

OutputCacheModuleAsync.md

File metadata and controls

132 lines (96 loc) · 6.14 KB
Raw

Microsoft.AspNet.OutputCache.OutputCacheModuleAsync

Overview

OutputCacheModuleAsync is an asynchronous implementation of ASP.NET's (4.X) output caching module. It provides performance improvements for web applications by caching the output of HTTP responses to reduce the need to execute the same request processing multiple times.

Features

  • Asynchronous caching operations for better scalability
  • Conditional request processing (If-Modified-Since, If-None-Match)
  • Customizable cache expiration policies
  • VaryBy parameter support (VaryByHeader, VaryByParam, VaryByCustom)

Integrations

The OutputCacheModuleAsync is designed to work with any cache provider that implements the OutputCacheProviderAsync base class, allowing you to store cached content in various backends like SQL Server, Redis, or custom storage solutions. Two such providers are provided from the this same repository:

Requirements

  • .NET Framework 4.6.2 or later (Full framework - not .NET Core)

Usage

  1. Target your application to .NET Framework 4.6.2 or later

    The OutputCacheProviderAsync interface was introduced in .NET Framework 4.6.2, therefore you need to target your application to .NET Framework 4.6.2 or above in order to use the Async OutputCache Module. Download the .NET Framework 4.6.2 Developer Pack if you do not have it installed yet and update your application's web.config targetFramework attributes as demonstrated below:

    <system.web>
  <compilation debug="true" targetFramework="4.6.2"/>
  <httpRuntime targetFramework="4.6.2"/>
</system.web>

  2. Add the Microsoft.AspNet.OutputCache.OutputCacheModuleAsync NuGet package

    Use the NuGet package manager to install the Microsoft.AspNet.OutputCache.OutputCacheModuleAsync package. This will add a reference to the Microsoft.AspNet.OutputCache.OutputCacheModuleAsync.dll and add the following configuration into the web.config file.

    <system.webServer>
  <modules>
    <remove name="OutputCache"/>
    <add name="OutputCache" type="Microsoft.AspNet.OutputCache.OutputCacheModuleAsync, Microsoft.AspNet.OutputCache.OutputCacheModuleAsync" preCondition="integratedMode"/>
  </modules>
</system.webServer>

  3. Enable Output Caching in your application

    Configure web forms applications for output caching by adding the following to the applications web.config file:

    <system.web>
  <caching>
    <outputCache enableOutputCache="true" />
    <outputCacheSettings>
      <outputCacheProfiles>
        <add name="CacheFor60Seconds" duration="60" varyByParam="none" />
      </outputCacheProfiles>
    </outputCacheSettings>
  </caching>
</system.web>

    You can also enable output caching in your MVC applications by adding the OutputCache attribute to your controllers or actions. For example:

    [OutputCache(Duration = 60, VaryByParam = "none")]
public ActionResult Index()
{
    // This content will be cached for 60 seconds
    return View();
}

    Now the applications will start using the Async OutputCache Module.

    If there are special requirements of a cache store that are not met by these released providers, consider implementing an async OutputCache Provider of your own.

Cache key hardening in v1.1

As of version 1.1.0, OutputCacheModuleAsync uses a compact, versioned, length-framed string representation of the complete request variant when generating cache keys. The cache provider receives a bounded, SHA-256-based hashed key, while the cached value contains the full canonical ID used to generate it. A cached value is served only when that canonical ID matches the current request exactly. This prevents ambiguous vary-by values or a hashed-key collision from returning a different variant's response.

Canonical IDs are limited to 8,192 characters. A response is not cached when its canonical ID exceeds that limit. This bounds attacker-controlled vary-by metadata and avoids exceeding provider key limits.

Upgrading does not require a SQL or Cosmos DB table schema change. Existing entries use the legacy key format and are ignored by default, then expire normally as new requests populate hardened entries. Applications that need a temporary warm-cache transition can opt into legacy reads:

<appSettings>
  <add key="aspnet:AllowLegacyOutputCacheKeys" value="true" />
</appSettings>

This setting affects reads only; all new entries use hardened keys. Legacy entries do not contain an exact canonical ID, so enabling the setting also restores the legacy collision behavior for those entries until they expire or the cache is cleared. Leave the setting unset or false for the default hardened behavior. As with ASP.NET's other boolean app settings, a missing or malformed value uses the default of false.

Output caching is a performance feature and is not a security boundary.

Updates

v1.1.0

  • Added collision-resistant, versioned cache keys with exact canonical-ID verification.
  • Added optional legacy-key reads for warm-cache transitions.

v1.0.4

  • Bug Fix: Fixed an issue with cache expiration policies not being applied correctly.

v1.0.1

  • Added checks and support for kernel cache APIs in several places to ensure proper handling of kernel cache entries. Also updated the DependencyRemovedCallback method to invalidate kernel cache entries when dependencies change.
  • Added [Serializable] attributes to several classes to ensure they can be serialized correctly, which helps in caching scenarios.

v1.0.0

  • Initial release.