Awesome
Matryoshki
<img src="assets/matryoshki.svg" align="right" /> "Matryoshki" (Матрёшки, Matryoshkas) is a metaprogramming framework based on C# source generators.
Key Features
- Define type-agnostic templates and create decorators based on them:
Decorate<IFoo>.With<LoggingAdornment>().Name<FooWithLogging>()
- Extract interfaces and automatically generate adapters from classes:
From<Bar>.ExtractInterface<IBar>()
.
Getting Started
Installation
The first step is to add package to the target project:
dotnet add package Matryoshki
Once the package is installed, you can proceed with creating adornments.
Adornments
<img src="assets/flower.png" width="48" align="left" />Adornments act as blueprints for creating type-agnostic decorators. They consist of a method template and can contain arbitrary members. Rather than being instantiated as objects, the code of adornment classes is directly injected into the decorator classes.
To create an adornment you need to create a class that implements IAdornment
. As a simple example, you can create an adornment that outputs the name of the decorated member to the console:
public class HelloAdornment : IAdornment
{
public TResult MethodTemplate<TResult>(Call<TResult> call)
{
Console.WriteLine($"Hello, {call.MemberName}!");
return call.Forward();
}
}
When creating a decorated method, call.Forward()
will be replaced with a call to the implementation. And TResult
will have the type of the actual return value. For void
methods, a special type Nothing
will be used.
An adornment for logging can serve as a slightly closer example to real-world usage:
public class LoggingAdornment : IAdornment
{
private readonly ILogger<ExceptionLoggingAdornment> _logger;
public LoggingAdornment(ILogger<ExceptionLoggingAdornment> logger)
{
_logger = logger;
}
public TResult MethodTemplate<TResult>(Call<TResult> call)
{
try
{
if(_logger.IsEnabled(LogLevel.Debug))
_logger.LogDebug("Executing {Type}.{Member}", GetType().Name, call.MemberName);
var result = call.Forward();
if (_logger.IsEnabled(LogLevel.Debug))
_logger.LogDebug("Successfully executed {Type}.{Member}: {Result}", GetType().Name, call.MemberName, result);
return result;
}
catch (Exception exception)
{
_logger.LogError(
exception,
"Error executing {Type}.{Member}({Arguments})",
GetType().Name,
call.MemberName,
string.Join(",", call.GetArgumentsOfType<object>()));
throw;
}
}
}
</details>
Asynchronous method templates
Asynchronous templates can be defined by implementing the AsyncMethodTemplate
method, which will be used to decorate methods that return Task
or ValueTask
.
Note that asynchronous templates are optional, and async methods will still be decorated because an AsyncMethodTemplate
will be automatically created from the MethodTemplate
by awaiting the Forward*
method invocations.
More tips for writing adornments can be found here: tips.
Decoration
Once we have an adornment, we can create our first matryoshkas.
<details> <summary>Suppose we have two interfaces that we would like to apply our HelloAdornment to.</summary>interface IFoo
{
object Foo(object foo) => foo;
}
record Foo : IFoo;
interface IBar
{
Task BarAsync() => Task.Delay(0);
}
record Bar : IFoo;
</details>
To create matryoshkas, you just need to write their specification in any appropriate location:
Matryoshka<IFoo>
.With<HelloAdornment>()
.Name<FooMatryoshka>();
Decorate<IBar> // you can use Decorate<> alias if you prefer
.With<HelloAdornment>()
.Name<BarMatryoshka>();
Done! Now we can test the generated classes:
var fooMatryoshka = new FooMatryoshka(new Foo());
var barMatryoshka = new BarMatryoshka(new Bar());
fooMatryoshka.Foo(); // "Hello, Foo!" will be written to console
barMatryoshka.Bar(); // "Hello, Bar!" will be written to console
In a production environment, you will likely prefer to use DI containers that support decoration (Grace, Autofac, etc.) or libraries like Scrutor. Here's an example of using matryoshkas together with Scrutor:
using Scrutor;
using Matryoshki.Abstractions;
public static class MatryoshkaScrutorExtensions
{
public static IServiceCollection DecorateWithMatryoshka(
this IServiceCollection services,
Expression<Func<MatryoshkaType>> expression)
{
var matryoshkaType = expression.Compile()();
services.Decorate(matryoshkaType.Target, matryoshkaType.Type);
return services;
}
public static IServiceCollection DecorateWithNestedMatryoshkas(
this IServiceCollection services,
Expression<Func<MatryoshkaTypes>> expression)
{
var matryoshkaTypes = expression.Compile()();
foreach (var type in matryoshkaTypes)
services.Decorate(matryoshkaTypes.Target, type);
return services;
}
}
internal static class Example
{
internal static IServiceCollection DecorateBar(
this IServiceCollection services)
{
return services.DecorateWithMatryoshka(
() => Matryoshka<IBar>.With<HelloAdornment>());
}
}
Chains of decorations with INesting<T1, ..., TN>
Reusable decoration chains can be described by creating a type that implements INesting<T1, ..., TN>
:
public record ObservabilityNesting : INesting<MetricsAdornment, LoggingAdornment, TracingAdornment>;
You can generate the classes using it as follows:
static IServiceCollection DecorateFoo(IServiceCollection services)
{
//assuming that you are using MatryoshkaScrutorExtensions
return services.DecorateWithNestedMatryoshkas(
() => Matryoshka<IBar>.WithNesting<ObservabilityNesting>());
}
It is not possible to assign names to the classes when using INesting
. The generated types will be located in the MatryoshkiGenerated.{NestingName}
namespace and have names in the format TargetTypeNameWithAdornmentName.
Limitations
- Do not use a variable named
value
, as this can conflict with a property setter. - The
call
parameter should not be passed to other methods. default
cannot be used without specifying a type argument.- To apply decorations, the members must be abstract or virtual. To surpass this limitation you can generate an interface with expression
From<TClass>.ExtractInterface<TInterface>()
and then decrorateTInterface
. - The decoration expression must be computable at compile time and written with a single statement
- Pattern matching will not always work
License
This project is licensed under the MIT license.