In the preceding article, we introduced the concept of generating cache keys for custom types by implementing
the ICacheKey interface. We created an aspect that implements this interface automatically for all the fields or
properties of a custom class annotated with the [CacheKeyMember] attribute.
However, two issues remain with this approach. Firstly, how do we handle types for which we don't have the source code? Secondly, what if the user of this aspect tries to include an item whose type is not supported? We are now adding two requirements to our aspect:
- Add a mechanism to generate a cache key for externally-defined types, and
- Report an error when the aspect's user attempts to include an unsupported type in the cache key.
ICacheKeyBuilder
To address these challenges, we have introduced the concept of cache key builders — objects capable of building
a
cache key for another object. We define the ICacheKeyBuilder interface as follows:
1public interface ICacheKeyBuilder<T>
2{
3 public string? GetCacheKey(in T value, ICacheKeyBuilderProvider provider);
4}
The generic type parameter in the interface represents the relevant object type. The benefit of using a generic
parameter is performance: we can generate the cache key without boxing value-typed values into an object.
For instance, here is an implementation for byte[]:
1internal class ByteArrayCacheKeyBuilder : ICacheKeyBuilder<byte[]?>
2{
3 public string? GetCacheKey(in byte[]? value, ICacheKeyBuilderProvider provider)
4 {
5 if (value == null)
6 {
7 return null;
8 }
9
10 return string.Join(' ', value);
11 }
12}
Compile-time API
To enable compile-time reporting of errors when attempting to include an unsupported type in the cache key, we need a
compile-time configuration API for the caching aspects. We accomplish this via a concept named hierarchical options,
which is explained in more detail in Making aspects configurable. We define a new compile-time class, CachingOptions,
to map types to their respective builders. It implements the IHierarchicalOptions<T>
for all levels where the options can be defined, i.e. the whole compilation, namespace, or type. The class is designed
as immutable and represents an incremental change in configuration compared to its base level, but without knowing its
base configuration. Because of this unusual requirements, designing aspect options can be complex.
Here is the top-level option class:
1using Metalama.Framework.Code;
2using Metalama.Framework.Options;
3
4public record CachingOptions :
5 IHierarchicalOptions<IMethod>,
6 IHierarchicalOptions<INamedType>,
7 IHierarchicalOptions<INamespace>,
8 IHierarchicalOptions<ICompilation>
9{
10 private readonly IncrementalKeyedCollection<string, CacheBuilderRegistration>
11 _cacheBuilderRegistrations;
12
13 public static CachingOptions Default { get; } = new();
14
15 public CachingOptions() : this(IncrementalKeyedCollection<string, CacheBuilderRegistration>
16 .Empty)
17 {
18 }
19
20 private CachingOptions(
21 IncrementalKeyedCollection<string, CacheBuilderRegistration> cacheBuilderRegistrations)
22 {
23 this._cacheBuilderRegistrations = cacheBuilderRegistrations;
24 }
25
26 internal IEnumerable<CacheBuilderRegistration> Registrations => this._cacheBuilderRegistrations;
27
28 public CachingOptions UseToString(Type type) =>
29 new(this._cacheBuilderRegistrations.AddOrApplyChanges(
30 new CacheBuilderRegistration(TypeFactory.GetType(type), null)));
31
32 public CachingOptions UseCacheKeyBuilder(Type type, Type builderType) =>
33 new(this._cacheBuilderRegistrations.AddOrApplyChanges(new CacheBuilderRegistration(
34 TypeFactory.GetType(type),
35 TypeFactory.GetType(builderType))));
36
37 public object ApplyChanges(object changes, in ApplyChangesContext context)
38 => new CachingOptions(
39 this._cacheBuilderRegistrations.AddOrApplyChanges(
40 ((CachingOptions)changes)._cacheBuilderRegistrations)
41 );
42}
The class relies on IncrementalKeyedCollection to represent a change in the
collection. Items in these collections are represented by the CacheBuilderRegistration class.
1using Metalama.Framework.Code;
2using Metalama.Framework.Options;
3
4internal class CacheBuilderRegistration : IIncrementalKeyedCollectionItem<string>
5{
6 public CacheBuilderRegistration(IType keyType, IType? builderType)
7 {
8 // We are using ToDisplayString for the key and not SerializableTypeId because
9 // SerializableTypeId is too strict -- it includes too much nullability information.
10 this.KeyType = keyType.ToDisplayString(CodeDisplayFormat.FullyQualified);
11 this.BuilderType = builderType?.ToSerializableId();
12 }
13
14 public object ApplyChanges(object changes, in ApplyChangesContext context)
15 => changes;
16
17 public string KeyType { get; }
18 public SerializableTypeId? BuilderType { get; }
19
20 public bool UseToString => this.BuilderType == null;
21
22 string IIncrementalKeyedCollectionItem<string>.Key => this.KeyType;
23}
Configuring the caching API using a fabric is straightforward:
1using Metalama.Framework.Fabrics;
2
3public class Fabric : ProjectFabric
4{
5 public override void AmendProject(IProjectAmender amender)
6 {
7 var cachingOptions = CachingOptions.Default
8 .UseToString(typeof(int))
9 .UseToString(typeof(long))
10 .UseToString(typeof(string))
11 .UseCacheKeyBuilder(typeof(byte[]), typeof(ByteArrayCacheKeyBuilder));
12
13 amender.SetOptions(cachingOptions);
14 }
15}
For those unfamiliar with the term, fabrics are compile-time types whose AmendProject method executes before any
aspect. The AmendProject method acts as a compile-time entry point, triggered solely by its existence, much
like Program.Main, but at compile time. Refer to Fabrics for additional information.
ICacheKeyBuilderProvider
At run time, it is convenient to abstract the process of obtaining ICacheKeyBuilder instances with a provider pattern.
We can achieve this by defining the ICacheKeyBuilderProvider interface.
1public interface ICacheKeyBuilderProvider
2{
3 ICacheKeyBuilder<TValue> GetCacheKeyBuilder<TValue, TBuilder>(in TValue value)
4 where TBuilder : ICacheKeyBuilder<TValue>, new();
5}
Note that the new() constraint on the generic parameter allows for a trivial implementation of the class.
The implementation of ICacheKeyBuilderProvider should be pulled from the dependency injection container. To allow
cache key objects to be instantiated independently from the dependency container, we update the ICacheKey interface to
receive the provider from the caller:
1public interface ICacheKey
2{
3 string ToCacheKey(ICacheKeyBuilderProvider provider);
4}
Generating the cache key item expression
The logic to generate the expression that gets the cache key of an object has now grown in complexity. It includes support for three cases plus null-handling.
- Implicit call to
ToString. - Call to
ICacheKeyBuilderProvider.GetCacheKeyBuilder. - Call to
ICacheKey.ToCacheKey.
It is now easier to build the expression with ExpressionBuilder rather
than with a template. We have moved this logic to CachingOptions.
82internal static bool TryGetCacheKeyExpression(this CachingOptions cachingOptions,
83 IExpression expression,
84 IExpression cacheKeyBuilderProvider,
85 [NotNullWhen(true)] out IExpression? cacheKeyExpression)
86{
87 var expressionBuilder = new ExpressionBuilder();
88 var typeId = expression.Type.ToNonNullableType()
89 .ToDisplayString(CodeDisplayFormat.FullyQualified);
90
91 if (GetRegistrations(cachingOptions)
92 .TryGetValue(typeId, out var registration))
93 {
94 if (registration.UseToString)
95 {
96 expressionBuilder.AppendExpression(expression);
97
98 if (expression.Type.IsNullable == true)
99 {
100 expressionBuilder.AppendVerbatim("?.ToString() ?? \"null\"");
101 }
102 }
103 else
104 {
105 expressionBuilder.AppendExpression(cacheKeyBuilderProvider);
106 expressionBuilder.AppendVerbatim(".GetCacheKeyBuilder<");
107 expressionBuilder.AppendTypeName(expression.Type);
108 expressionBuilder.AppendVerbatim(", ");
109 expressionBuilder.AppendTypeName(
110 registration.BuilderType!.Value.Resolve(expression.Type.Compilation));
111 expressionBuilder.AppendVerbatim(">(");
112 expressionBuilder.AppendExpression(expression);
113 expressionBuilder.AppendVerbatim(")");
114
115 if (expression.Type.IsNullable == true)
116 {
117 expressionBuilder.AppendVerbatim("?? \"null\"");
118 }
119 }
120 }
121 else if (expression.Type.Is(typeof(ICacheKey)) ||
122 (expression.Type is INamedType namedType &&
123 namedType.Enhancements().HasAspect<GenerateCacheKeyAspect>()))
124 {
125 expressionBuilder.AppendExpression(expression);
126 expressionBuilder.AppendVerbatim(".ToCacheKey(");
127 expressionBuilder.AppendExpression(cacheKeyBuilderProvider);
128 expressionBuilder.AppendVerbatim(")");
129
130 if (expression.Type.IsNullable == true)
131 {
132 expressionBuilder.AppendVerbatim("?? \"null\"");
133 }
134 }
135 else
136 {
137 cacheKeyExpression = null;
138 return false;
139 }
140
141
142 cacheKeyExpression = expressionBuilder.ToExpression();
143 return true;
144}The ExpressionBuilder class essentially acts as a StringBuilder wrapper.
We can add any text to an ExpressionBuilder, as long as it can be parsed back into a valid C# expression.
Reporting errors for unsupported types
We report an error whenever an unsupported type is used as a parameter of a cached method, or when it is used as a type
for a field or property annotated with [CacheKeyMember].
To achieve this, we add the following code to CachingOptions:
37internal static bool VerifyCacheKeyMember<T>(this CachingOptions cachingOptions, T expression,
38 ScopedDiagnosticSink diagnosticSink)
39 where T : IExpression, IDeclaration
40{
41 // Check supported intrinsics.
42 switch (expression.Type.SpecialType)
43 {
44 case SpecialType.Boolean:
45 case SpecialType.Byte:
46 case SpecialType.Decimal:
47 case SpecialType.Double:
48 case SpecialType.SByte:
49 case SpecialType.Int16:
50 case SpecialType.UInt16:
51 case SpecialType.Int32:
52 case SpecialType.UInt32:
53 case SpecialType.Int64:
54 case SpecialType.UInt64:
55 case SpecialType.String:
56 case SpecialType.Single:
57 return true;
58 }
59
60 // Check registered types.
61 var registrations = GetRegistrations(cachingOptions);
62
63 var typeId = expression.Type.ToNonNullableType()
64 .ToDisplayString(CodeDisplayFormat.FullyQualified);
65 if (registrations.ContainsKey(typeId))
66 {
67 return true;
68 }
69
70 // Check ICacheKey.
71 if (expression.Type.Is(typeof(ICacheKey)) ||
72 (expression.Type is INamedType { BelongsToCurrentProject: true } namedType &&
73 namedType.Enhancements().HasAspect<GenerateCacheKeyAspect>()))
74 {
75 return true;
76 }
77
78 diagnosticSink.Report(_error.WithArguments(expression.Type), expression);
79 return false;
80}
81The first line defines an error kind. Metalama requires the DiagnosticDefinition
to be defined in a static field or property. Then, if the type of the expression is invalid, this error is reported
for that property or parameter. To learn more about reporting errors, see Reporting and suppressing diagnostics.
This method needs to be reported from the BuildAspect method of the CacheAttribute and GenerateCacheKeyAspect
aspect classes. We cannot report errors from template methods because templates are typically not executed at design
time unless we are using the preview feature.
However, a limitation prevents us from detecting unsupported types at design time. When Metalama runs inside the editor, at design time, it doesn't execute all aspects for all files at every keystroke, but only does so for the files that have been edited, plus all files containing the ancestor types. Therefore, at design time, your aspect receives a partial compilation. It can still see all the types in the project, but it doesn't see the aspects that have been applied to these types.
So, when CachingOptions.VerifyCacheKeyMember evaluates Enhancements().HasAspect<GenerateCacheKeyAspect>() at design
time, the expression does not yield an accurate result. Therefore, we can only run this method when we have a complete
compilation, i.e., at compile time.
To verify parameters, we need to include this code in the CacheAttribute aspect class:
18public override void BuildAspect(IAspectBuilder<IMethod> builder)
19{
20 base.BuildAspect(builder);
21
22 if (!builder.Target.Compilation.IsPartial)
23 {
24 var cachingOptions = builder.Target.Enhancements().GetOptions<CachingOptions>();
25
26 foreach (var parameter in builder.Target.Parameters)
27 {
28 cachingOptions.VerifyCacheKeyMember(parameter, builder.Diagnostics);
29 }
30 }
31}
32Aspects in action
The aspects can be applied to some business code as follows:
1public class BlobId
2{
3 public BlobId(string container, byte[] hash)
4 {
5 this.Container = container;
6 this.Hash = hash;
7 }
8
9 [CacheKeyMember] public string Container { get; }
10
11 [CacheKeyMember] public byte[] Hash { get; }
12}
1using System;
2using System.Text;
3
4public class BlobId
5: ICacheKey
6{
7 public BlobId(string container, byte[] hash)
8 {
9 this.Container = container;
10 this.Hash = hash;
11 }
12
13 [CacheKeyMember] public string Container { get; }
14
15 [CacheKeyMember] public byte[] Hash { get; }
16protected virtual void BuildCacheKey(StringBuilder stringBuilder, ICacheKeyBuilderProvider provider)
17 {
18 stringBuilder.Append(Container);
19 stringBuilder.Append(", ");
20 stringBuilder.Append(provider.GetCacheKeyBuilder<byte[], global::ByteArrayCacheKeyBuilder>(this.Hash));
21 }
22 public string ToCacheKey(ICacheKeyBuilderProvider provider)
23 {
24 var stringBuilder = new StringBuilder();
25 BuildCacheKey(stringBuilder, provider);
26 return stringBuilder.ToString();
27 }
28}
1public class DatabaseFrontend
2{
3 public int DatabaseCalls { get; private set; }
4
5
6 [Cache]
7 public byte[] GetBlob(string container, byte[] hash)
8 {
9 Console.WriteLine("Executing GetBlob...");
10 this.DatabaseCalls++;
11
12 return new byte[] { 0, 1, 2 };
13 }
14
15 [Cache]
16 public byte[] GetBlob(BlobId blobId)
17 {
18 Console.WriteLine("Executing GetBlob...");
19 this.DatabaseCalls++;
20
21 return new byte[] { 0, 1, 2 };
22 }
23}
1using System;
2
3public class DatabaseFrontend
4{
5 public int DatabaseCalls { get; private set; }
6
7
8 [Cache]
9 public byte[] GetBlob(string container, byte[] hash)
10 {
11var cacheKey = $"DatabaseFrontend.GetBlob((string) {{{container}}}, (byte[]) {{{(_cacheBuilderProvider.GetCacheKeyBuilder<byte[], global::ByteArrayCacheKeyBuilder>(hash))}}})";
12 if (_cache.TryGetValue(cacheKey, out var value))
13 {
14 return (byte[])value;
15 }
16
17 byte[] result;
18 Console.WriteLine("Executing GetBlob...");
19 this.DatabaseCalls++;
20 result = new byte[] { 0, 1, 2 }; _cache.TryAdd(cacheKey, result);
21 return result;
22 }
23
24 [Cache]
25 public byte[] GetBlob(BlobId blobId)
26 {
27var cacheKey = $"DatabaseFrontend.GetBlob((BlobId) {{{blobId.ToCacheKey(_cacheBuilderProvider)}}})";
28 if (_cache.TryGetValue(cacheKey, out var value))
29 {
30 return (byte[])value;
31 }
32
33 byte[] result;
34 Console.WriteLine("Executing GetBlob...");
35 this.DatabaseCalls++;
36 result = new byte[] { 0, 1, 2 }; _cache.TryAdd(cacheKey, result);
37 return result;
38 }
39private ICache _cache;
40 private ICacheKeyBuilderProvider _cacheBuilderProvider;
41
42 public DatabaseFrontend(ICache? cache = default(global::ICache?), ICacheKeyBuilderProvider? cacheBuilderProvider = default(global::ICacheKeyBuilderProvider?))
43 {
44 this._cache = cache ?? throw new System.ArgumentNullException(nameof(cache)); this._cacheBuilderProvider = cacheBuilderProvider ?? throw new System.ArgumentNullException(nameof(cacheBuilderProvider));
45 }
46}