Metalama, a high-level meta-programming framework based on Roslyn and AOP

[gfraiteur]

We are thrilled to announce the launch of Metalama, our new Roslyn-based meta-programming framework for C#. Since its inception in August 2020, Metalama has undergone continuous development, and we are delighted to make it generally available now.

Metalama is designed for line-of-business application development teams, helping them write clean code by minimizing boilerplate and ensuring compliance with custom architecture rules. Drawing from our prior experience and telemetry data gathered from PostSharp, we estimate that this approach allows development teams to achieve savings of 10-20% in lines of code, effort, and bug occurrences.

Metalama vs. Roslyn

Metalama extends Roslyn by offering two significant features. First, it supports aspect-oriented programming, allowing developers to safely and simply enhance their code during the design and compilation stages. Second, Metalama is much more straightforward than the Roslyn API itself, enabling meta-programming code to reside within the same project as the business code. We have broadened the notion of an aspect for modern C#: an aspect can not only provide advice (i.e., code transformations) but also report diagnostics and suggest code fixes for these diagnostics, all within a single class.

Example 1: Simple Logging

The classic Hello world example of aspect-oriented programming is logging. Consider the following aspect:

using Metalama.Framework.Aspects;

public class LogAttribute : OverrideMethodAspect
{
    public override dynamic? OverrideMethod()
    {
        Console.WriteLine( $"{meta.Target.Method} started." );

        try
        {
            var result = meta.Proceed();

            Console.WriteLine( $"{meta.Target.Method} succeeded." );

            return result;
        }
        catch ( Exception e )
        {
            Console.WriteLine( $"{meta.Target.Method} failed: {e.Message}." );

            throw;
        }
    }
}

Observe the use of the meta pseudo-keyword in this code, which provides access to the meta-model.

Now, let's apply this aspect to the following code:

internal static class Calculator
{
    [Log]
    public static double Add( double a, double b ) => a + b;
}

The resulting code, which will be executed, appears as follows:

using System;

internal static class Calculator
{
    [Log]
    public static double Add( double a, double b )
{
        Console.WriteLine("Calculator.Add(double, double) started.");
        try
        {
            double result;
            result = a + b;
            Console.WriteLine("Calculator.Add(double, double) succeeded.");
            return (double)result;
        }
        catch (Exception e)
        {
            Console.WriteLine($"Calculator.Add(double, double) failed: {e.Message}.");
            throw;
        }
    }
}

Although this example is relatively straightforward, you can follow this tutorial to explore implementing a more practical logging aspect.

Example 2: IChangeTracking

Let's examine a more complex example featuring a different aspect: the automatic implementation of the IChangeTracking interface. This aspect also reports a diagnostic if the type already implements the IChangeTracking interface but does not expose any OnChange method, which the design pattern conventionally requires. This aspect showcases several remarkable features. The BuildAspect method serves as the method's entry point, providing advice (implementing the interface and overriding property setters) and reporting errors. It also possesses other capabilities beyond this brief introduction's scope.

using Metalama.Framework.Advising;
using Metalama.Framework.Aspects;
using Metalama.Framework.Code;
using Metalama.Framework.Diagnostics;

public class TrackChangesAttribute : TypeAspect
{
    private static readonly DiagnosticDefinition<INamedType> _mustHaveOnChangeMethod = new(
        "MY001",
        Severity.Error,
        $"The '{nameof(ISwitchableChangeTracking)}' interface is implemented manually on type '{{0}}', but the type does not have an '{nameof(OnChange)}()' method.");

    private static readonly DiagnosticDefinition _onChangeMethodMustBeProtected = new(
        "MY002",
        Severity.Error,
        $"The '{nameof(OnChange)}()' method must have the 'protected' accessibility.");

    public override void BuildAspect( IAspectBuilder<INamedType> builder )
    {
        // Implement the ISwitchableChangeTracking interface.
        var implementInterfaceResult = builder.Advice.ImplementInterface( builder.Target,
            typeof(ISwitchableChangeTracking), OverrideStrategy.Ignore );

        // If the type already implements IChangeTracking, it must have a protected method called OnChanged, without parameters, otherwise
        // this is a contract violation, so we report an error.
        if ( implementInterfaceResult.Outcome == AdviceOutcome.Ignored )
        {
            var onChangeMethod = builder.Target.AllMethods.OfName( nameof(this.OnChange) )
                .Where( m => m.Parameters.Count == 0 ).SingleOrDefault();

            if ( onChangeMethod == null )
            {
                builder.Diagnostics.Report( _mustHaveOnChangeMethod.WithArguments( builder.Target ) );
            }
            else if ( onChangeMethod.Accessibility != Accessibility.Protected )
            {
                builder.Diagnostics.Report( _onChangeMethodMustBeProtected );
            }
        }

        // Override all writable fields and automatic properties.
        var fieldsOrProperties = builder.Target.FieldsAndProperties
            .Where( f =>
                !f.IsImplicitlyDeclared && f.Writeability == Writeability.All && f.IsAutoPropertyOrField == true );

        foreach ( var fieldOrProperty in fieldsOrProperties )
        {
            builder.Advice.OverrideAccessors( fieldOrProperty, null, nameof(this.OverrideSetter) );
        }
    }

    [InterfaceMember]
    public bool IsChanged { get; private set; }

    [InterfaceMember]
    public bool IsTrackingChanges { get; set; }

    [InterfaceMember]
    public void AcceptChanges() => this.IsChanged = false;

    [Introduce( WhenExists = OverrideStrategy.Ignore )]
    protected void OnChange()
    {
        if ( this.IsTrackingChanges )
        {
            this.IsChanged = true;
        }
    }

    [Template]
    private void OverrideSetter( dynamic? value )
    {
        if ( value != meta.Target.Property.Value )
        {
            meta.Proceed();

            this.OnChange();
        }
    }
}

Now, let's apply the aspect to the following code:

[TrackChanges]
public partial class Comment
{
    public Guid Id { get; }
    public string Author { get; set; }
    public string Content { get; set; }

    public Comment( Guid id, string author, string content )
    {
        this.Id = id;
        this.Author = author;
        this.Content = content;
    }
}

The resulting code appears as follows:

using System;
using System.ComponentModel;

[TrackChanges]
public partial class Comment : ISwitchableChangeTracking, IChangeTracking
{
    public Guid Id { get; }

    private string _author = default !;
    public string Author
    {
        get
        {
            return this._author;
        }

        set
        {
            if (value != this._author)
            {
                this._author = value;
                this.OnChange();
            }
        }
    }

    private string _content = default !;
    public string Content
    {
        get
        {
            return this._content;
        }

        set
        {
            if (value != this._content)
            {
                this._content = value;
                this.OnChange();
            }
    }

    public Comment(Guid id, string author, string content)
    {
        this.Id = id;
        this.Author = author;
        this.Content = content;
    }

    public bool IsChanged { get; private set; }

    public bool IsTrackingChanges { get; set; }

    public void AcceptChanges()
    {
        this.IsChanged = false;
    }

    protected void OnChange()
    {
        if (this.IsTrackingChanges)
        {
            this.IsChanged = true;
        }
    }
}

For details about this example, see our documentation.

Example 3: architecture verification

The following example demonstrates a fabric class. Similar to aspect classes, fabrics execute at compile time. However, unlike aspects, fabrics do not need to be applied to anything. Their AmendProject method is executed automatically. In this example, we register a rule that verifies that the Invoicing namespace cannot use float or double. This verification is performed at design time. Notice how much simpler it is for application developers than authoring an analyzer for the same purpose. Additionally, a fabric is a class of the same project as the one containing the business code.

internal class Fabric : ProjectFabric
{
    public override void AmendProject( IProjectAmender amender )
    {
        amender.Verify()
            .SelectTypes( typeof( float ), typeof( double ) )
            .CannotBeUsedFrom( r => r.Namespace( "**.Invoicing" ), "Use decimal numbers instead." );
    }
}

For more information about fabrics and validation, refer to this documentation article.

How it works

Metalama integrates with various Roslyn extension points, including analyzers, suppressors, code generators, code fix providers, and refactoring providers. However, these were insufficient to implement aspect-oriented programming, necessitating the development and maintenance of a shallow fork of the Roslyn repository to include a new extension point: transformers. Transformers enable arbitrary syntax tree transformations during compile time. We do not encourage users to utilize this API, as our target audience consists of line-of-business developers who likely lack the skills and time necessary to develop compiler plugins.

Summary

Metalama aims to be a modern, comprehensive, integrated, user-friendly, and sound meta-programming framework for C# line-of-business application developers. It empowers them to improve code quality and productivity by eliminating the need to write boilerplate code and enforcing architectural rules in real-time.

Metalama comes with a free edition and several affordable commercial options. Open-source projects can use and distribute Metalama free of change.

To learn more about Metalama, visit our website and explore our documentation.

[XtroTheArctic]

I've been using Metalama (beta) for few months in my personal library projects and I love it. I'm happy that it's finally released. 🥳

[WhitWaldo]

I just started using Metalama this week and have been floored by how quickly I can produce large swathes of consistent code throughout my solutions. Its biggest draw to me is that the aspects you write can have both runtime and compile-time code leaving you with runtime configurability with compile-time flexibility (e.g. automatically introduce dependency injected fields that utilize your runtime DI registration).

Congratulations on your 1.0 release!

[John0King]

this is some aop lanauge that I imagine , it's really cool to see it became reallity !

[PeterHevesi]

I would love, if you join Metalama communities:
The main one is on Slack
But it's also on Reddit