IL.RulesBasedOutputCache 2.2.0.1

dotnet add package IL.RulesBasedOutputCache --version 2.2.0.1
                    
NuGet\Install-Package IL.RulesBasedOutputCache -Version 2.2.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="IL.RulesBasedOutputCache" Version="2.2.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="IL.RulesBasedOutputCache" Version="2.2.0.1" />
                    
Directory.Packages.props
<PackageReference Include="IL.RulesBasedOutputCache" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add IL.RulesBasedOutputCache --version 2.2.0.1
                    
#r "nuget: IL.RulesBasedOutputCache, 2.2.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package IL.RulesBasedOutputCache@2.2.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=IL.RulesBasedOutputCache&version=2.2.0.1
                    
Install as a Cake Addin
#tool nuget:?package=IL.RulesBasedOutputCache&version=2.2.0.1
                    
Install as a Cake Tool

Rules-based output cache

Rule-controlled ASP.NET Core response caching with optional Redis storage, tag eviction, SQL-backed rules, and an authenticated administration UI.

Supported frameworks

The library and tests target .NET 10 and .NET 11 only. Use SDK 11 to build both targets and install both ASP.NET Core runtimes to test them. EF Core and Redis output-cache dependencies use compatible 10.x/11.x versions. The admin panel view is compiled at build time by IL.VirtualViews 2.x; neither this package nor its dependencies use Razor runtime compilation, and consuming applications do not need a runtime C# compiler.

Setup

The cache is disabled by default. Enable it and explicitly allow public routes in configuration:

{
  "RulesBasedOutputCache": {
    "OutputCacheEnabled": true,
    "DefaultCacheTimeout": "00:05:00",
    "CachingRules": [
      {
        "RuleTemplate": "/public/*",
        "RuleType": "Regex",
        "RuleAction": "Allow",
        "VaryByQueryString": true,
        "VaryByHost": true
      }
    ]
  }
}
using IL.RulesBasedOutputCache.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.AddRulesBasedOutputCache();
var app = builder.Build();

// Run authentication and request localization before this middleware when used.
await app.UseRulesBasedOutputCacheAsync();
app.MapGet("/public/example", () => "cacheable response");
await app.RunAsync();

UseRulesBasedOutputCacheAsync asynchronously migrates/seeds SQL storage before installing the middleware. Supply its cancellationToken when startup must be cancellable. There is no blocking compatibility startup wrapper. Service registration itself is synchronous because it performs no I/O.

Cache safety and variation

  • Only successful, fully buffered GET / 200 responses are stored. HEAD, mutation methods, requests with Authorization or Range headers, and enabled admin routes pass through without cache lookup/storage.
  • Authenticated requests bypass shared caching unless the matching rule explicitly enables VaryByUser and the primary authenticated identity has a nonempty name. User keys also distinguish authentication type and name identifier when supplied.
  • Responses with Set-Cookie, Cache-Control: private, no-store or no-cache, any Vary header, or text/event-stream content are not stored. Final headers include OnStarting changes. Arbitrary header variance is not implemented: a Vary response passes through rather than risking the wrong representation.
  • Cookie-personalized endpoints that do not set a response cookie or declare privacy must still be explicitly disallowed or opt out. The library cannot infer all application-specific personalization.
  • VaryByQueryString, VaryByHost, and VaryByCulture are opt-in. Enable every dimension on which the response depends, especially host variance in multi-tenant applications. Culture variance uses the full current culture and UI culture names, including regions.
  • Keys are versioned, length-framed, and hashed; component boundaries cannot collide. Path base, scheme, and rule variance/expiration policy are included. Old unversioned entries are never replayed and can expire naturally.
  • MaximumBodySize defaults to 32 MiB. Oversize/uncacheable streams and explicit opt-out release the single per-key request-coalescing lock early. Waiting for that lock honors request cancellation. Coalescing is process-local, not a Redis distributed lock.
  • Cache read/write/deserialization and rule-store read failures are logged and fail open to the endpoint; downstream endpoint failures still propagate. If rules cannot be read, shared entries are not replayed. The response stream and request feature are restored on every exit.
  • Responses that have not started are not stored: their OnStarting privacy/cookie/status callbacks may still be pending. Explicitly started empty responses remain eligible if otherwise safe.

Tags and eviction

Public helpers are in IL.RulesBasedOutputCache.Extensions:

httpContext.ApplyCustomOutputCacheTagToCurrentRequest("product:42");
httpContext.ApplyCustomOutputCacheTagsToCurrentRequest(new HashSet<string> { "catalog", "product:42" });
httpContext.IgnoreRulesBasedOutputCacheForCurrentRequest();

Tags and opt-out are checked until the endpoint completes, including calls after the first body write. Opt-out cannot retract a response already served from a previous cache hit; exclude such routes before lookup using a disallow rule when necessary.

Use ASP.NET Core's configured store to evict tagged entries:

await store.EvictByTagAsync("product:42", httpContext.RequestAborted);

Eviction does not promise a transaction with concurrent response generation. Coordinate application writes/invalidation when stronger consistency is required.

Rules

  • RuleType: ExactPath, Regex, or FileExtension.
  • ExactPath matches a complete path case-insensitively, e.g. /products.
  • The historical Regex name means an anchored * wildcard glob, not .NET regular-expression syntax. Multiple stars work, e.g. /private/*/secret/*; * matches zero or more characters, including path separators.
  • FileExtension accepts values such as .js or .js|.css|.png.
  • RuleAction: Allow or Disallow. Every matching Disallow takes precedence over Allow. Within an action, priority increases from FileExtension to ExactPath to Regex. Equal-priority ties use ordinal case-insensitive template order.
  • ResponseExpirationTimeSpan is an optional, positive invariant TimeSpan, e.g. 00:05:00; otherwise DefaultCacheTimeout applies.

Invalid templates/enums/durations fail configuration or mutation validation; a bulk mutation is validated before any of it is applied. Invalid legacy/custom-repository data disables caching for that request rather than dropping a deny rule or failing the application. Priority is derived, not trusted from submitted forms. Repository snapshots are read-only, independently owned records.

Storage and configuration

AddRulesBasedOutputCache reads the RulesBasedOutputCache section. When disabled it registers no cache middleware/repositories; it only adds a no-op IOutputCacheStore if the host has not already provided one.

  • DefaultCacheTimeout: positive default duration, five minutes by default.
  • MaximumBodySize: nonnegative maximum buffered bytes, 32 MiB by default.
  • OutputCustomHeader / CustomHeaderKey: optional cache-hit marker header; default key OutputCache.
  • CachingRules: startup rules, used to seed an empty SQL rule store.
  • SqlConnectionStringName: the name of a SQL Server connection string. Startup migration requires appropriate database permissions.
  • RedisConnectionStringName / RedisInstanceName: optional Redis connection-string name and application-specific key prefix. Use separate instance names for unrelated applications.

In-memory rules belong to one application service provider, not the process. SQL contexts share application-local, database-bound read state; local writes invalidate that snapshot immediately. Changes made by another process are detected by the metadata poll, at most five minutes later. SQL duplicate suppression is application-local: cross-process concurrent uniqueness is not guaranteed without a database-level constraint. Do not mutate rule tables directly without updating their metadata.

The configuration schema describes the supported settings.

Consumer-controlled dependency versions

Runtime PackageReferences use explicit compatibility windows rather than exact pins:

Dependency net10 net11
IL.VirtualViews 2.1.0.1 (minimum) 2.1.0.1 (minimum)
EF Core / SqlServer / Redis output cache [10.0.15,11.0.0) [11.0.0,12.0.0)

Bounds are inclusive/exclusive respectively. IL.VirtualViews 2.x compiles views at build time and has no Razor RuntimeCompilation dependency.

A consuming project can choose a version inside the window with a direct PackageReference, or a central PackageVersion plus direct reference (or explicitly enabled transitive pinning). A bare NuGet version already means a minimum; [version] is an exact pin. These bounded ranges declare a compatible family and do not automatically select latest. Future in-range versions are not all certified by these tests. Private compiler/test tooling was not broadened as part of this consumer policy.

Secure administration

Administration is off by default. Set AdminPanel:AdminPanelEnabled for the page and AdminPanel:AdminPanelApiEnabled for its API; enable both for the interactive UI. AdminPanel:AdminPanelUrl defaults to /rulesBasedCache/adminPanel.

Both page and API require AdminPanel:AuthorizationPolicy, default RulesBasedOutputCacheAdmin. The default policy requires an authenticated principal with the CacheAdmin role. The host must configure a real authentication scheme/login flow. You may select another explicitly registered policy. Existing endpoint-configuration callbacks can add further requirements; they are not required to turn authorization on.

For cookie authentication, configure the host's normal cookie scheme and middleware before installing the cache:

builder.Services.AddAuthentication("Cookies").AddCookie("Cookies");
// ... build the app after registering cache services ...
app.UseAuthentication();
app.UseAuthorization();
await app.UseRulesBasedOutputCacheAsync();

All mutations are POST and validate real antiforgery tokens. The rendered forms include tokens automatically. API-only clients obtain { requestToken, headerName } from authenticated GET /api/rulesBasedCache/antiforgery, retain its antiforgery cookie, and send both cookie and the returned token header on POST addRule, deleteRule, and evictAllCacheEntries. GET eviction is not supported. Invalid forms/tokens return 400 without mutation. Administrative responses are marked no-store and bypass this cache.

Build and test

dotnet restore
dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-build --no-restore
dotnet list package --vulnerable --include-transitive

Use --framework net10.0 or --framework net11.0 on the test command to select one runtime. Local tests use TestServer, fake cache stores, and EF's in-memory provider; they do not certify live SQL Server migrations, real Redis behavior, or multi-node consistency.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.2.0.1 0 11/18/2026
2.1.1.1 515 7/21/2026
2.1.0.5 148 7/19/2026
2.1.0.4 324 5/4/2026
2.1.0.3 133 5/4/2026
2.1.0.2 119 5/4/2026
2.1.0.1 145 5/4/2026
2.0.1.2 231 3/20/2026
2.0.1.1 144 3/20/2026
2.0.0.2 476 1/7/2026
2.0.0.1 178 1/5/2026
2.0.0 318 11/26/2025
1.6.1 446 11/15/2025
1.6.0 349 10/30/2025
1.5.2 559 8/20/2025
1.5.1 272 8/20/2025
1.5.0 1,419 4/11/2025
1.4.4 328 4/8/2025
1.4.3 1,527 1/7/2025
1.4.2 277 1/6/2025
Loading failed