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
<PackageReference Include="IL.RulesBasedOutputCache" Version="2.2.0.1" />
<PackageVersion Include="IL.RulesBasedOutputCache" Version="2.2.0.1" />
<PackageReference Include="IL.RulesBasedOutputCache" />
paket add IL.RulesBasedOutputCache --version 2.2.0.1
#r "nuget: IL.RulesBasedOutputCache, 2.2.0.1"
#:package IL.RulesBasedOutputCache@2.2.0.1
#addin nuget:?package=IL.RulesBasedOutputCache&version=2.2.0.1
#tool nuget:?package=IL.RulesBasedOutputCache&version=2.2.0.1
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
VaryByUserand 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-storeorno-cache, anyVaryheader, ortext/event-streamcontent are not stored. Final headers includeOnStartingchanges. Arbitrary header variance is not implemented: aVaryresponse 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, andVaryByCultureare 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.
MaximumBodySizedefaults 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
OnStartingprivacy/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, orFileExtension.ExactPathmatches a complete path case-insensitively, e.g./products.- The historical
Regexname 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. FileExtensionaccepts values such as.jsor.js|.css|.png.RuleAction:AlloworDisallow. 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.ResponseExpirationTimeSpanis an optional, positive invariant TimeSpan, e.g.00:05:00; otherwiseDefaultCacheTimeoutapplies.
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 keyOutputCache.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 | Versions 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. |
-
net10.0
- IL.VirtualViews (>= 2.1.0.1)
- Microsoft.AspNetCore.OutputCaching.StackExchangeRedis (>= 10.0.15 && < 11.0.0)
- Microsoft.EntityFrameworkCore (>= 10.0.15 && < 11.0.0)
- Microsoft.EntityFrameworkCore.SqlServer (>= 10.0.15 && < 11.0.0)
-
net11.0
- IL.VirtualViews (>= 2.1.0.1)
- Microsoft.AspNetCore.OutputCaching.StackExchangeRedis (>= 11.0.0 && < 12.0.0)
- Microsoft.EntityFrameworkCore (>= 11.0.0 && < 12.0.0)
- Microsoft.EntityFrameworkCore.SqlServer (>= 11.0.0 && < 12.0.0)
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 |