โ๏ธ Configuration¶
This guide describes the configuration options available in CoreSystem.Cache.
You'll learn how to configure:
- Cache provider behavior
- Serialization
- HTTP response cache expiration
- Cache key instance name
- Cache entry rehydration options
๐ Configuration Overview¶
The framework is configured through the AddCoreCache() extension.
builder.Services.AddCoreCache(options =>
{
// Configure the framework here
});
โ๏ธ Configuration Options¶
| Option | Description | Default |
|---|---|---|
| Enabled | Enables or disables the cache implementation | true |
| InstanceName | Optional prefix for cache keys | null |
| DefaultExpiration | HTTP response cache lifetime, used when [Cacheable] omits expirationSeconds |
30 minutes |
| SerializerType | Serialization format | JSON |
๐ Enable or Disable the Cache¶
The cache can be disabled while keeping the same ICoreCache abstraction available.
builder.Services.AddCoreCache(options =>
{
options.Enabled = false;
});
When disabled, AddCoreCache() still registers an ICoreCache, but it is a
no-op implementation rather than the pipeline-backed one. The registration is
there on purpose: resolving ICoreCache keeps working, so application code does
not need to change when the cache is switched off. The concrete type is
internal, so it cannot be named, substituted, or pattern-matched from another
assembly.
Every call to GetOrAddAsync() runs the factory and returns its result, since
nothing is ever stored. Each read, write, remove, and tag invalidation is a
no-op that returns the empty value for its type instead of throwing.
๐ท๏ธ Instance Name¶
Prefixes cache keys with an application or environment identifier, when an external provider is registered.
options.InstanceName = "CatalogApi";
The option is intended to help avoid key collisions when multiple applications share the same cache infrastructure.
The Memory provider does not apply this prefix, so the option has no effect when no external provider is registered.
โณ Cache Expiration¶
DefaultExpiration applies only to the HTTP response cache. It sets the
lifetime of a cached response when the endpoint's CacheableAttribute does not
specify expirationSeconds.
options.DefaultExpiration =
TimeSpan.FromMinutes(30);
It is not a fallback for direct cache operations. SetAsync and
GetOrAddAsync store the entry with no expiration at all when the expiration
argument is null, so each call that needs a lifetime must pass one explicitly.
await cache.SetAsync(
"products",
products,
TimeSpan.FromMinutes(5));
There is no entry-size limit. Entries of any size are cached; use
DefaultExpiration and the CacheableAttribute to control how long an HTTP
response stays cached.
๐ข Serialization¶
Choose the serializer used by the cache.
Serialization is provided by CoreSystem.Serialization.
๐งพ JSON¶
options.SerializerType =
SerializerType.Json;
JSON is the default serializer.
๐ฆ MessagePack¶
options.SerializerType =
SerializerType.MessagePack;
๐ฆ Protocol Buffers¶
options.SerializerType =
SerializerType.Protobuf;
๐ Cache Entry Rehydration¶
CacheEntryOptions provides the TrackForRehydration flag.
The fallback pipeline uses:
CacheEntryOptions.Rehydrate
when an operation is redirected from the primary storage to the fallback storage.
This marks the entry for rehydration when the external provider becomes available again.
The rehydration process itself belongs to the external-provider/recovery components and is not configured directly through the current CacheOptions class.
๐ External Providers¶
CoreSystem.Cache can operate with its Memory provider without an external cache provider.
When an external provider is registered, it becomes the primary storage and Memory is used as the fallback storage.
The external provider configuration is handled by the corresponding provider package and is not part of the CacheOptions class shown in the current CoreSystem.Cache implementation.
๐ก Recommended Configurations¶
๐งช Development¶
builder.Services.AddCoreCache(options =>
{
options.SerializerType = SerializerType.Json;
options.DefaultExpiration = TimeSpan.FromMinutes(5);
});
๐ญ Production¶
The core package does not define a production provider configuration inside CacheOptions.
When using an external provider, configure that provider through its corresponding package and keep the common cache settings in AddCoreCache().
โ Best Practices¶
- Use an
InstanceNamewhen multiple applications share the same cache infrastructure. - Configure
DefaultExpirationfor HTTP-cached responses, and pass an explicitexpirationon everySetAsyncorGetOrAddAsynccall that needs a lifetime. - Prefer an explicit expiration over relying on a default: without one, entries do not expire.
- Choose the serializer according to the application's requirements.
- Use the Memory provider when an external distributed provider is not required.
- Configure external provider options in the corresponding provider package.