MintPlayer.SourceGenerators.Tools 11.0.0

MintPlayer.SourceGenerators.Tools

This package makes it easier to write your own source-generators. The library provides:

• An IncrementalGenerator class that implements IIncrementalGenerator and already reads several options (like the RootNamespace of the project) beforehand)
• A Producer class that hands you a ready-to-use IndentedTextWriter
• A ProduceCode(...) extension method where you can pass in your source-providers

Example

Generator:

namespace ExampleGenerators;

// Use the ready-made IncrementalGenerator

[Generator(LanguageNames.CSharp)]
public class ExampleGenerator : IncrementalGenerator
{
    public override void Initialize(IncrementalGeneratorInitializationContext context, IncrementalValueProvider<Settings> settingsProvider)
    {
        var typesToMapProvider = context.SyntaxProvider
            .ForAttributeWithMetadataName(
                "ExampleGenerators.Attributes.ExampleAttribute",
                static (node, ct) => node is not null,
                static (ctx, ct) =>
                {
                    if (ctx.SemanticModel.GetDeclaredSymbol(ctx.TargetNode, ct) is INamedTypeSymbol typeSymbol &&
                        ctx.Attributes.FirstOrDefault(a => a.AttributeClass?.ToDisplayString() == "ExampleGenerators.Attributes.ExampleAttribute") is { } attr &&
                        attr.ConstructorArguments.FirstOrDefault().Value is INamedTypeSymbol mapType)
                    {
                        return new Models.TypeToMap
                        {
                            ...
                        };
                    }
                    return null;
                }
            )
            .WithComparer();

        var typesToMapSourceProvider = typesToMapProvider
            .Select(static Producer (p, ct) => new MapperProducer(p));

        // Pass your source-providers to the ready-made ProduceCode extension method 
        context.ProduceCode(typesToMapSourceProvider);
    }

    public override void RegisterComparers()
    {
        // Use this if you're using libraries like Newtonsoft.Json
        // Make sure to use a Mutex.
        // An example is available in NewtonsoftJsonComparers.Register()
    }
}

Producer:

public sealed class MapperProducer : Producer
{
    private readonly IEnumerable<TypeToMap> typesToMap;
    public MapperProducer(IEnumerable<TypeToMap> typesToMap, string rootNamespace) : base(rootNamespace, "Mappers.g.cs")
    {
        this.typesToMap = typesToMap;
    }

    protected override void ProduceSource(IndentedTextWriter writer, CancellationToken cancellationToken)
    {
        writer.WriteLine($"namespace {RootNamespace}");
        writer.WriteLine("{");
        writer.Indent++;

        writer.WriteLine("public static class MapperExtensions");
        writer.WriteLine("{");
        writer.Indent++;

        // Generate more code based on the data in typesToMap

        writer.Indent--;
        writer.WriteLine("}");

        writer.Indent--;
        writer.WriteLine("}");
    }
}

Use the ValueComparerGenerator

If you install this package too in your project, you can have your value-comparers automatically generated for you.

TypeToMap.cs

namespace MintPlayer.Mapper.Models;

[AutoValueComparer]
public partial class TypeToMap
{
    public string DeclaredType { get; set; }
    public string DeclaredTypeName { get; set; }
    public PropertyDeclaration[] DeclaredProperties { get; set; } = [];
    public string MappingType { get; set; }
    public string MappingTypeName { get; set; }
    public PropertyDeclaration[] MappingProperties { get; set; } = [];
    public string DestinationNamespace { get; set; }
}

This generator will generate a value-comparer and a .WithComparer() and .WithNullableComparer() extension method for you.

Staying incremental

A generator that emits the same output on every keystroke is still doing the work on every keystroke. The pieces above are built so that an edit your generator does not care about stops at a comparer:

• ProduceCode(...) gives each producer its own output step and never touches the Compilation, so a file is regenerated only when its own producer's input changed. Since 11.0.0; before that every producer was combined with the Compilation and re-ran on every edit.
• [ValueComparer(typeof(...))] (which [AutoValueComparer] emits for you) is honoured by ComparerRegistry, so .WithComparer() and nested comparisons use your comparer without manual registration. Arrays, List<T> and ImmutableArray<T> compare element-wise.
• ReportDiagnostics(...) needs the Compilation to rebuild in-tree locations, which #pragma and .editorconfig severity depend on. Implement IConditionalDiagnosticReporter and a reporter with nothing to report runs no step at all.

Rules of thumb for your models: no ISymbol, SyntaxNode, SyntaxTokenList, Location or Compilation (use strings and LocationKey); put .WithComparer() on every step that produces a model, especially before Collect(); and carry a LocationKey only on a model that will actually report a diagnostic, so that typing above a declaration does not invalidate it.

To prove it, MintPlayer.SourceGenerators.Testing runs a generator twice and reports the run reason of every output step.