Default implementation of ICacheKeyBuilder that builds cache item keys and dependency keys.
Namespace: Metalama.Patterns.Caching.Formatters
Assembly: Metalama.Patterns.Caching.dll
Syntax
public class CacheKeyBuilder : IDisposable, ICacheKeyBuilderRemarks
Key Building Strategy
This class generates cache keys by combining method signature information with formatted argument values.
Method keys follow this format:
Namespace.DeclaringType.MethodName<GenericArgs>(this={instance}, (ParamType) paramValue, ...)For example: MyApp.Services.UserService.GetUser(this={MyApp.Services.UserService}, (int) 42)
Dependency keys are formatted representations of the dependency object using the registered formatters.
Key Compression (Hashing)
When HashingAlgorithm is set to XxHash64 or XxHash128, keys exceeding KeyCompressingThreshold characters are compressed using a hash. This is useful for backends with key length limits (e.g., Redis, Memcached).
For method keys: The class and method name are preserved as a prefix (with generic arguments stripped),
followed by a tilde (~) and the base64-encoded hash of the full key.
Example: MyApp.Services.UserService.GetUser~9XwmlUowFDE
For dependency keys: The entire key is replaced with the base64-encoded hash (no prefix).
XxHash64 produces ~11 character hashes; XxHash128 produces ~22 character hashes.
Customization
To customize key generation, either derive from this class and override the virtual methods, or implement ICacheKeyBuilder directly. Register custom implementations using WithKeyBuilder(Func<IFormatterRepository, CacheKeyBuilderOptions, ICacheKeyBuilder>).
Constructors
| Name | Description |
|---|---|
| CacheKeyBuilder(IFormatterRepository, CacheKeyBuilderOptions) | Initializes a new instance of the CacheKeyBuilder class specifying the maximal key size and optionally a IFormatterRepository. |
Properties
| Name | Description |
|---|---|
| Formatters | Gets the formatters used to build the caching key. |
| HashingAlgorithm | Gets the algorithm used to compress the key if its length is above KeyCompressingThreshold. |
| IgnoredParameterSentinel | Gets a sentinel object that means that the parameter is not a part of the cache key, and should be ignored. |
| KeyCompressingThreshold | Gets the length above which a key will be compressed if HashingAlgorithm is not None. |
| MaxKeySize | Gets the maximal number of characters in cache keys. |
Methods
| Name | Description |
|---|---|
| AppendArgument(UnsafeStringBuilder, Type, object?) | Appends a method argument to an UnsafeStringBuilder. To avoid ambiguities between different overloads of the same method, the default implementation appends both the parameter type and the value key. |
| AppendBufferHash(StringBuilder, ReadOnlySpan<byte>) | Hashes a buffer using HashingAlgorithm and appends the result to a StringBuilder. |
| AppendMethod(UnsafeStringBuilder, MethodInfo) | Appends the method name and generic arguments to an UnsafeStringBuilder. |
| AppendObject(UnsafeStringBuilder, object) | Appends a string representing an object to an UnsafeStringBuilder. |
| AppendType(UnsafeStringBuilder, Type) | Appends a Type name to an UnsafeStringBuilder. |
| BuildDependencyKey(object) | Builds a dependency key for a given object. |
| BuildMethodKey(CachedMethodMetadata, object?, IList<object?>) | Builds a cache key for a given method call. |
| CompressKey(UnsafeStringBuilder, bool, int) | Compresses the key if necessary. |
| Dispose() | |
| Dispose(bool) | Disposes the current object. |
| GetHashLength(CacheKeyHashingAlgorithm) | Gets the maximum length of the hash string for the specified algorithm. |