Open sandboxFocusImprove this doc

Offering code fixes and refactorings

Attaching code fixes to diagnostics

When an aspect or fabric reports a diagnostic, it can attach a set of code fixes to this diagnostic by invoking the IDiagnostic.WithCodeFixes method. The CodeFixFactory class can be used to create single-step code fixes.

Suggesting code refactorings without diagnostics

An aspect or fabric can also suggest a code refactoring without reporting a diagnostic by invoking the Suggest method.

Example

The example below demonstrates an aspect that implements the ToString method. By default, it includes all public properties of the class in the ToString result. However, the developer using the aspect can opt-out by adding [NotToString] to any property.

The aspect utilizes the Suggest method to add a code fix suggestion for all properties not yet annotated with [NotToString].

1using Metalama.Framework.Aspects;
2using Metalama.Framework.Code;
3using Metalama.Framework.Code.SyntaxBuilders;
4using Metalama.Framework.CodeFixes;
5using System;
6using System.Linq;
7
8namespace Doc.ToStringWithSimpleToString;
9
10[AttributeUsage( AttributeTargets.Field | AttributeTargets.Property )]
11public class NotToStringAttribute : Attribute { }
12
13[EditorExperience( SuggestAsLiveTemplate = true )]
14public class ToStringAttribute : TypeAspect
15{
16    public override void BuildAspect( IAspectBuilder<INamedType> builder )
17    {
18        base.BuildAspect( builder );
19
20        // For each field, suggest a code fix to remove from ToString.
21        foreach ( var field in builder.Target.FieldsAndProperties.Where(
22                     f => !f.IsStatic && !f.IsImplicitlyDeclared ) )
23        {
24            if ( !field.Attributes.Any( a => a.Type.Is( typeof(NotToStringAttribute) ) ) )
25            {
26                builder.Diagnostics.Suggest(
27                    CodeFixFactory.AddAttribute(
28                        field,
29                        typeof(NotToStringAttribute),
30                        "Exclude from [ToString]" ),
31                    field );
32            }
33        }
34    }
35
36    [Introduce( WhenExists = OverrideStrategy.Override, Name = "ToString" )]
37    public string IntroducedToString()
38    {
39        var stringBuilder = new InterpolatedStringBuilder();
40        stringBuilder.AddText( "{ " );
41        stringBuilder.AddText( meta.Target.Type.Name );
42        stringBuilder.AddText( " " );
43
44        var fields = meta.Target.Type.FieldsAndProperties
45            .Where( f => !f.IsImplicitlyDeclared && !f.IsStatic )
46            .ToList();
47
48        var i = meta.CompileTime( 0 );
49
50        foreach ( var field in fields )
51        {
52            if ( field.Attributes.Any( a => a.Type.Is( typeof(NotToStringAttribute) ) ) )
53            {
54                continue;
55            }
56
57            if ( i > 0 )
58            {
59                stringBuilder.AddText( ", " );
60            }
61
62            stringBuilder.AddText( field.Name );
63            stringBuilder.AddText( "=" );
64            stringBuilder.AddExpression( field );
65
66            i++;
67        }
68
69        stringBuilder.AddText( " }" );
70
71        return stringBuilder.ToValue();
72    }
73}
Source Code
1using System;
2
3namespace Doc.ToStringWithSimpleToString;
4
5[ToString]
6internal class MovingVertex
7{
8    public double X;
9
10    public double Y;
11
12    public double DX;
13
14    public double DY { get; set; }
15
16    public double Velocity => Math.Sqrt( (this.DX * this.DX) + (this.DY * this.DY) );
17}
Transformed Code
1using System;
2
3namespace Doc.ToStringWithSimpleToString;
4
5[ToString]
6internal class MovingVertex
7{
8    public double X;
9
10    public double Y;
11
12    public double DX;
13
14    public double DY { get; set; }
15
16    public double Velocity => Math.Sqrt((this.DX * this.DX) + (this.DY * this.DY));
17
18    public override string ToString()
19    {
20        return $"{{ MovingVertex X={X}, Y={Y}, DX={DX}, DY={DY}, Velocity={Velocity} }}";
21    }
22}

Building multi-step code fixes

To create a custom code fix, instantiate the CodeFix class using the constructor instead of the CodeFixFactory class.

The CodeFix constructor accepts two arguments:

  • The title of the code fix, which will be displayed to the user, and
  • A delegate of type Func<ICodeActionBuilder, Task> which will apply the code fix when the user selects it

The title must be globally unique for the target declaration. Even two different aspects cannot provide two code fixes with the same title to the same declaration.

The delegate will typically utilize one of the following methods of the ICodeActionBuilder interface:

Method Description
AddAttributeAsync Adds a custom attribute to a declaration.
RemoveAttributesAsync Removes all custom attributes of a given type from a given declaration and all contained declarations.
ApplyAspectAsync Transforms the source code using an aspect (as if it were applied as a live template).

Example

The previous example is continued here, but instead of a single-step code fix, we want to offer the user the ability to switch from an aspect-oriented implementation of ToString by applying the aspect to the source code itself.

The custom code fix performs the following actions:

  • Applies the aspect using the ApplyAspectAsync method.
  • Removes the [ToString] custom attribute.
  • Removes the [NotToString] custom attributes.

1using Metalama.Framework.Aspects;
2using Metalama.Framework.Code;
3using Metalama.Framework.Code.SyntaxBuilders;
4using Metalama.Framework.CodeFixes;
5using System;
6using System.Linq;
7using System.Threading.Tasks;
8
9namespace Doc.ToStringWithComplexCodeFix;
10
11[AttributeUsage( AttributeTargets.Field | AttributeTargets.Property )]
12[RunTimeOrCompileTime]
13public class NotToStringAttribute : Attribute { }
14
15[EditorExperience( SuggestAsLiveTemplate = true )]
16public class ToStringAttribute : TypeAspect
17{
18    public override void BuildAspect( IAspectBuilder<INamedType> builder )
19    {
20        base.BuildAspect( builder );
21
22        // Suggest to switch to manual implementation.
23        if ( builder.AspectInstance.Predecessors[0].Instance is IAttribute attribute )
24        {
25            builder.Diagnostics.Suggest(
26                new CodeFix(
27                    "Switch to manual implementation",
28                    codeFixBuilder => this.ImplementManually( codeFixBuilder, builder.Target ) ),
29                attribute );
30        }
31    }
32
33    [CompileTime]
34    private async Task ImplementManually( ICodeActionBuilder builder, INamedType targetType )
35    {
36        await builder.ApplyAspectAsync( targetType, this );
37        await builder.RemoveAttributesAsync( targetType, typeof(ToStringAttribute) );
38        await builder.RemoveAttributesAsync( targetType, typeof(NotToStringAttribute) );
39    }
40
41    [Introduce( WhenExists = OverrideStrategy.Override, Name = "ToString" )]
42    public string IntroducedToString()
43    {
44        var stringBuilder = new InterpolatedStringBuilder();
45        stringBuilder.AddText( "{ " );
46        stringBuilder.AddText( meta.Target.Type.Name );
47        stringBuilder.AddText( " " );
48
49        var fields = meta.Target.Type.FieldsAndProperties
50            .Where( f => !f.IsStatic && !f.IsImplicitlyDeclared )
51            .ToList();
52
53        var i = meta.CompileTime( 0 );
54
55        foreach ( var field in fields )
56        {
57            if ( field.Attributes.Any( a => a.Type.Is( typeof(NotToStringAttribute) ) ) )
58            {
59                continue;
60            }
61
62            if ( i > 0 )
63            {
64                stringBuilder.AddText( ", " );
65            }
66
67            stringBuilder.AddText( field.Name );
68            stringBuilder.AddText( "=" );
69            stringBuilder.AddExpression( field.Value );
70
71            i++;
72        }
73
74        stringBuilder.AddText( " }" );
75
76        return stringBuilder.ToValue();
77    }
78}
Source Code
1using System;
2
3namespace Doc.ToStringWithComplexCodeFix;
4
5[ToString]
6internal class MovingVertex
7{
8    public double X;
9
10    public double Y;
11
12    public double DX;
13
14    public double DY { get; set; }
15
16    [NotToString]
17    public double Velocity => Math.Sqrt( (this.DX * this.DX) + (this.DY * this.DY) );
18}
Transformed Code
1using System;
2
3namespace Doc.ToStringWithComplexCodeFix;
4
5[ToString]
6internal class MovingVertex
7{
8    public double X;
9
10    public double Y;
11
12    public double DX;
13
14    public double DY { get; set; }
15
16    [NotToString]
17    public double Velocity => Math.Sqrt((this.DX * this.DX) + (this.DY * this.DY));
18
19    public override string ToString()
20    {
21        return $"{{ MovingVertex X={X}, Y={Y}, DX={DX}, DY={DY} }}";
22    }
23}

Performance considerations

  • Code fixes and refactorings are only useful at design time. At compile time, all code fixes will be ignored. To avoid generating code fixes at compile time, you can make your logic conditional upon the MetalamaExecutionContext.Current.ExecutionScenario.CapturesCodeFixTitles expression.

  • The Func<ICodeActionBuilder, Task> delegate is only executed when the user selects the code fix or refactoring. However, the entire aspect will be executed again, which has two implications:

    • The logic that creates the delegate must be highly efficient because it is rarely used. Any expensive logic should be moved to the implementation of the delegate itself.
    • To avoid generating the delegate, you can make it conditional upon the MetalamaExecutionContext.Current.ExecutionScenario.CapturesCodeFixImplementations expression.
  • At design time, all code fix titles, including those added by the Suggest method, are cached for the complete solution. Therefore, you should avoid adding a large number of suggestions. The current Metalama design is not suited for this scenario.