MethodCache.SqlServer 1.0.0-rc.16

This is a prerelease version of MethodCache.SqlServer.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package MethodCache.SqlServer --version 1.0.0-rc.16
                    
NuGet\Install-Package MethodCache.SqlServer -Version 1.0.0-rc.16
                    
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="MethodCache.SqlServer" Version="1.0.0-rc.16" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MethodCache.SqlServer" Version="1.0.0-rc.16" />
                    
Directory.Packages.props
<PackageReference Include="MethodCache.SqlServer" />
                    
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 MethodCache.SqlServer --version 1.0.0-rc.16
                    
#r "nuget: MethodCache.SqlServer, 1.0.0-rc.16"
                    
#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 MethodCache.SqlServer@1.0.0-rc.16
                    
#: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=MethodCache.SqlServer&version=1.0.0-rc.16&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=MethodCache.SqlServer&version=1.0.0-rc.16&prerelease
                    
Install as a Cake Tool

MethodCache.SqlServer

SQL Server as MethodCache's distributed cache. Results are shared between application instances, and invalidations reach every instance's in-memory cache through a table that each instance polls.

Install it at the same version as MethodCache.

Why this package

  • One shared cache for every instance. Results live in each instance's memory and in SQL Server, so a result one instance computed is a hit for the others, and survives restarts.
  • Invalidation reaches every instance. Invalidating a key or tag removes it from SQL Server, and every other instance drops its in-memory copy on its next poll (every second by default).
  • Tags work across instances, without tag tables: invalidating a tag stores when it happened, stored atomically so a late, older invalidation never undoes a newer one.
  • No new infrastructure. If you already run SQL Server, the schema and tables are created when the application starts.
  • SQL Server never breaks your app. Calls are capped at one second, a circuit breaker skips SQL Server while it is down, and invalidations are queued until it is back.

Microsoft's AddDistributedSqlServerCache() (SqlServerCache) can't be used for this: it has no atomic invalidation timestamps, so MethodCache rejects it at startup, and it has no way to tell other instances to drop their in-memory copies. This package uses the same table layout, adds both, and keeps its own cache instance so your app's IDistributedCache is left alone.

SQL Server or Redis?

SQL Server Redis
Infrastructure The SQL Server you already have A Redis server
Other instances drop their in-memory copy On their next poll (every second by default) At once (pub/sub)
Load when idle Every instance polls the invalidations table None
Each distributed cache read or write A SQL Server query A Redis command

Choose SQL Server when you already run it and a delay of about a second before other instances see an invalidation is fine; choose Redis when invalidations must reach other instances at once, or many instances would poll the database.

Only Microsoft SQL Server is supported: the package uses T-SQL locking hints and Microsoft.Data.SqlClient. For PostgreSQL, use MethodCache.PostgreSql, whose backplane also reaches other instances at once; MySQL and other databases are not supported.

Usage

builder.Services.AddMethodCache(mc => mc.UseSqlServer(builder.Configuration.GetConnectionString("Cache")!));

With options:

builder.Services.AddMethodCache(mc => mc.UseSqlServer(options =>
{
    options.ConnectionString = connectionString;
    options.SchemaName = "cache";
    options.BackplanePollingInterval = TimeSpan.FromMilliseconds(500);
}));

Invalidations only

When each process should keep its own values and only hear about invalidations, such as a worker that changes data an API caches, set StoreValuesByDefault = false in every process. Values stay in each process's memory, for cached methods and manual calls alike, only those that set Distributed to true are written to SQL Server, and an invalidation in one process reaches all of them on their next poll:

builder.Services.AddMethodCache(mc => mc
    .UseSqlServer(builder.Configuration.GetConnectionString("Cache")!)
    .Distributed(o => o.StoreValuesByDefault = false));   // values stay in memory; invalidations reach every process

The tables are the same as for a full distributed cache. See Invalidations only.

Tables

By default the schema and three tables are created when the application starts, if they do not exist. Startup waits at most three seconds for that; if SQL Server is down, creation is retried in the background and methods run uncached until it succeeds.

  • MethodCache holds the entries, in the layout Microsoft.Extensions.Caching.SqlServer uses (the same as dotnet sql-cache create).
  • MethodCacheSchema contains the schema version (currently 1). Existing unversioned or unknown schemas are rejected.
  • MethodCacheInvalidations holds recent invalidations for the backplane. Applications that share it are kept apart by KeyPrefix (compared exactly, whatever the SQL collation).

If the application's login may not create tables, set CreateTablesIfMissing = false and create them in a migration instead.

Required backplane schema

The invalidations table needs a Scope binary(32) NOT NULL column and the indexes Index_Scope_Id (Scope, Id) and Index_Scope_CreatedAt (Scope, CreatedAt). MethodCache refuses a table without them instead of changing it, and logs the error; an error found during the startup wait also fails startup. With CreateTablesIfMissing = false, create the current schema yourself.

When SQL Server is down

MethodCache keeps answering from memory and your methods; SQL Server never fails or stalls a call.

  • Every SQL Server call is capped at OperationTimeout (1 second).
  • After a failure or timeout, MethodCache skips SQL Server for CircuitBreakerDuration (10 seconds), then one call checks whether it is back. The first failure and the recovery are logged.
  • Invalidations that SQL Server doesn't accept are queued and retried until it does. They never throw. Until they are stored, this instance doesn't read entries from SQL Server, so an invalidated value can't come back.
  • A value set directly while SQL Server is down stays in this instance's memory; the value it replaced is removed from SQL Server and the other instances once SQL Server is back.
  • ClockSkewTolerance (2 seconds) covers servers whose clocks differ: a tag invalidation also applies to entries created up to that long after it.
builder.Services.AddMethodCache(mc => mc.Distributed(options =>
{
    options.OperationTimeout = TimeSpan.FromMilliseconds(500);
    options.CircuitBreakerDuration = TimeSpan.FromSeconds(30);
}));

Options

Option Default Description
ConnectionString (required) SQL Server connection string
SchemaName dbo Schema of the cache, invalidations and schema-version tables
TableName MethodCache Table for cache entries
InvalidationsTableName MethodCacheInvalidations Table the backplane uses
ConnectionStringFactory none Resolves a connection string once from DI at binding
CreateTablesIfMissing true Create the schema and tables at startup
EnableBackplane true Share invalidations with other instances
BackplanePollingInterval 1 second How often each instance reads new invalidations
BackplaneRetention 1 hour How long invalidations are kept; at least one minute. Instances that share a KeyPrefix keep them as long as the longest retention any of them has used

How it works

  • Cache commands never join your TransactionScope: MethodCache sets Enlist=false on its connection string, so a scope that rolls back doesn't undo cache writes or invalidations, and never becomes a distributed transaction.
  • MethodCache reads SQL Server on an in-memory miss and writes new results to both.
  • Expired rows are removed by one DELETE every 5 minutes on each instance. With a very large table, keep an index on ExpiresAtTime (dotnet sql-cache create and CreateTablesIfMissing add one).
  • Values are JSON by default. A method whose results don't read back unchanged stays in memory only, with one warning (Serialization). For MessagePack, add MethodCache.Serialization.MessagePack and call UseMessagePack().
  • Keys are stored as a SHA-256 hash of the exact key, so keys that SQL collation would treat as equal (casing, trailing spaces) stay distinct, and keys of any length fit.
  • Invalidating a tag stores the time of the invalidation, and entries with that tag written before it are treated as missing, so no tag tables are needed. An older invalidation that arrives late never undoes a newer one.
  • Every invalidation also adds a row to the invalidations table. Other instances read new rows every BackplanePollingInterval and drop their in-memory copies. A long-running transaction elsewhere never holds back newer invalidations.
  • An instance that couldn't read the invalidations table for half of BackplaneRetention may have missed invalidations, so it clears its in-memory cache.
  • Each instance deletes its prefix's old invalidation rows every minute. Rows are kept for the longest BackplaneRetention any instance of the prefix has used, so a rolling deployment never deletes rows another instance still needs. Rows of a prefix that no application uses any more are never deleted; delete them by hand.
  • DistributedCacheOptions.KeyPrefix keeps applications that share the tables apart. The first instance that uses a prefix fixes its minimum TagRetention; a shorter setting fails at startup.

The exact behavior is in the distributed cache reference.

Upgrading from before 1.0

An invalidations table from before 1.0 has no schema version, and MethodCache refuses it. Stop every old instance, back up the database and run 0001-version-existing-schema.sql before starting the new version.

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. 
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
1.0.0-rc.20 54 11/12/2026
1.0.0-rc.19 60 11/10/2026
1.0.0-rc.18 62 11/10/2026
1.0.0-rc.17 54 11/10/2026
1.0.0-rc.16 58 11/8/2026
1.0.0-rc.15 56 11/8/2026
1.0.0-rc.14 56 11/8/2026
1.0.0-rc.13 63 11/7/2026
1.0.0-rc.12 52 11/7/2026
1.0.0-rc.11 54 11/7/2026
1.0.0-rc.10 56 11/6/2026
1.0.0-rc.9 56 11/5/2026
1.0.0-rc.8 65 11/5/2026
1.0.0-rc.7 67 11/5/2026
1.0.0-rc.6 58 11/5/2026
1.0.0-rc.5 60 11/4/2026
1.0.0-rc.4 59 11/4/2026
1.0.0-rc.3 62 11/4/2026
1.0.0-rc.2 77 10/20/2026
1.0.0-rc.1 74 10/19/2026