MetalamaCommented examplesCachingStep 4.​ Supporting external types
Open sandboxFocusImprove this doc

Caching example, step 4: cache key for external types

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:

  1. Add a mechanism to generate a cache key for externally-defined types, and
  2. 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> _cacheBuilderRegistrations;
11
12    public static CachingOptions Default { get; } = new();
13
14    public CachingOptions() : this( IncrementalKeyedCollection<string, CacheBuilderRegistration>.Empty ) { }
15
16    private CachingOptions( IncrementalKeyedCollection<string, CacheBuilderRegistration> cacheBuilderRegistrations )
17    {
18        this._cacheBuilderRegistrations = cacheBuilderRegistrations;
19    }
20
21    internal IEnumerable<CacheBuilderRegistration> Registrations => this._cacheBuilderRegistrations;
22
23    public CachingOptions UseToString( Type type ) =>
24        new( this._cacheBuilderRegistrations.AddOrApplyChanges(
25            new CacheBuilderRegistration( TypeFactory.GetType( type ), null ) ) );
26
27    public CachingOptions UseCacheKeyBuilder( Type type, Type builderType ) =>
28        new(this._cacheBuilderRegistrations.AddOrApplyChanges( new CacheBuilderRegistration(
29            TypeFactory.GetType( type ),
30            TypeFactory.GetType( builderType ) ) ));
31
32    public object ApplyChanges( object changes, in ApplyChangesContext context )
33        => new CachingOptions(
34
35            this._cacheBuilderRegistrations.AddOrApplyChanges(
36                ((CachingOptions) changes)._cacheBuilderRegistrations )
37        );
38}
39
40

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.Outbound.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.

80    internal static bool TryGetCacheKeyExpression( this CachingOptions cachingOptions, IExpression expression,
81        IExpression cacheKeyBuilderProvider,
82        [NotNullWhen( true )] out IExpression? cacheKeyExpression )
83    {
84        var expressionBuilder = new ExpressionBuilder();
85        var typeId = expression.Type.ToNonNullableType().ToDisplayString( CodeDisplayFormat.FullyQualified );
86
87        if ( GetRegistrations( cachingOptions )
88            .TryGetValue( typeId, out var registration ) )
89        {
90            if ( registration.UseToString )
91            {
92                expressionBuilder.AppendExpression( expression );
93
94                if ( expression.Type.IsNullable == true )
95                {
96                    expressionBuilder.AppendVerbatim( "?.ToString() ?? \"null\"" );
97                }
98            }
99            else
100            {
101                expressionBuilder.AppendExpression( cacheKeyBuilderProvider );
102                expressionBuilder.AppendVerbatim( ".GetCacheKeyBuilder<" );
103                expressionBuilder.AppendTypeName( expression.Type );
104                expressionBuilder.AppendVerbatim( ", " );
105                expressionBuilder.AppendTypeName(
106                    registration.BuilderType!.Value.Resolve( expression.Type.Compilation ) );
107                expressionBuilder.AppendVerbatim( ">(" );
108                expressionBuilder.AppendExpression( expression );
109                expressionBuilder.AppendVerbatim( ")" );
110
111                if ( expression.Type.IsNullable == true )
112                {
113                    expressionBuilder.AppendVerbatim( "?? \"null\"" );
114                }
115            }
116        }
117        else if ( expression.Type.Is( typeof(ICacheKey) ) ||
118                  (expression.Type is INamedType namedType &&
119                   namedType.Enhancements().HasAspect<GenerateCacheKeyAspect>()) )
120        {
121            expressionBuilder.AppendExpression( expression );
122            expressionBuilder.AppendVerbatim( ".ToCacheKey(" );
123            expressionBuilder.AppendExpression( cacheKeyBuilderProvider );
124            expressionBuilder.AppendVerbatim( ")" );
125
126            if ( expression.Type.IsNullable == true )
127            {
128                expressionBuilder.AppendVerbatim( "?? \"null\"" );
129            }
130        }
131        else
132        {
133            cacheKeyExpression = null;
134            return false;
135        }
136
137
138        cacheKeyExpression = expressionBuilder.ToExpression();
139        return true;
140    }

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:

35    internal static bool VerifyCacheKeyMember<T>( this CachingOptions cachingOptions, T expression,
36        ScopedDiagnosticSink diagnosticSink )
37        where T : IExpression, IDeclaration
38    {
39         
40        // Check supported intrinsics.
41        switch ( expression.Type.SpecialType )
42        {
43            case SpecialType.Boolean:
44            case SpecialType.Byte:
45            case SpecialType.Decimal:
46            case SpecialType.Double:
47            case SpecialType.SByte:
48            case SpecialType.Int16:
49            case SpecialType.UInt16:
50            case SpecialType.Int32:
51            case SpecialType.UInt32:
52            case SpecialType.Int64:
53            case SpecialType.UInt64:
54            case SpecialType.String:
55            case SpecialType.Single:
56                return true;
57        }
58
59        // Check registered types.
60        var registrations = GetRegistrations( cachingOptions );
61        
62        var typeId = expression.Type.ToNonNullableType().ToDisplayString( CodeDisplayFormat.FullyQualified );
63        if ( registrations.ContainsKey( typeId ) )
64        {
65            return true;
66        }
67
68        // Check ICacheKey.
69        if ( expression.Type.Is( typeof(ICacheKey) ) ||
70             (expression.Type is INamedType { BelongsToCurrentProject: true } namedType &&
71              namedType.Enhancements().HasAspect<GenerateCacheKeyAspect>()) )
72        {
73            return true;
74        }
75
76        diagnosticSink.Report( _error.WithArguments( expression.Type ), expression );
77        return false;
78    }

The 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:

18    public 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    }

Aspects in action

The aspects can be applied to some business code as follows:

Source Code



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}
Transformed Code
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(this.Container);
19        stringBuilder.Append(", ");
20        stringBuilder.Append(provider.GetCacheKeyBuilder<global::System.Byte[], global::ByteArrayCacheKeyBuilder>(this.Hash));
21    }
22    public string ToCacheKey(ICacheKeyBuilderProvider provider)
23    {
24        var stringBuilder = new StringBuilder();
25        this.BuildCacheKey(stringBuilder, provider);
26        return stringBuilder.ToString();
27    }
28}
Source Code


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}
Transformed Code
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 (this._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 };
21        this._cache.TryAdd(cacheKey, result);
22        return result;
23    }
24
25    [Cache]
26    public byte[] GetBlob( BlobId blobId )
27    {
28var cacheKey = $"DatabaseFrontend.GetBlob((BlobId) {{{blobId.ToCacheKey(_cacheBuilderProvider)}}})";
29        if (this._cache.TryGetValue(cacheKey, out var value))
30        {
31            return (byte[])value;
32        }
33
34        byte[] result;
35        Console.WriteLine("Executing GetBlob...");
36        this.DatabaseCalls++;
37        result = new byte[] { 0, 1, 2 };
38        this._cache.TryAdd(cacheKey, result);
39        return result;
40    }
41private ICache _cache;
42    private ICacheKeyBuilderProvider _cacheBuilderProvider;
43
44    public DatabaseFrontend
45(ICache? cache = default(global::ICache?), ICacheKeyBuilderProvider? cacheBuilderProvider = default(global::ICacheKeyBuilderProvider?))
46    {
47        this._cache = cache ?? throw new System.ArgumentNullException(nameof(cache)); this._cacheBuilderProvider = cacheBuilderProvider ?? throw new System.ArgumentNullException(nameof(cacheBuilderProvider));
48    }
49}