MintPlayer.ValueComparerGenerator 12.1.0

Value-equality generator

Generates value equality for the models of your incremental source generators, so that every pipeline step caches.

Roslyn compares the output of every incremental step with EqualityComparer<T>.Default. A plain class compares by reference, so a model that the transform builds anew on every run always looks changed, and everything downstream re-runs on every keystroke. Put [GenerateEquality] on the model and the generator writes IEquatable<T>, Equals(object) and GetHashCode() on the type itself: the model is value-equal everywhere, in any step, inside a Combine tuple, as a property of another model, in a HashSet and in Assert.Equal. No comparer is passed anywhere.

Getting started

Install both MintPlayer.ValueComparerGenerator and MintPlayer.ValueComparerGenerator.Attributes in your project. The generated code calls MintPlayer.SourceGenerators.Tools.ValueEquality, so the project also references MintPlayer.SourceGenerators.Tools, which every generator built on its IncrementalGenerator already does.

Example

The type, and every type containing it, must be partial.

using MintPlayer.ValueComparerGenerator.Attributes;

namespace Demo;

[GenerateEquality]
public sealed partial class CliOption
{
    public string Name { get; set; } = "";
    public IReadOnlyList<string> Aliases { get; set; } = new List<string>();
    public ImmutableArray<Child> Children { get; set; }

    [EqualityIgnore]
    public string CachedText { get; set; } = "";
}

[GenerateEquality]
public sealed partial class Child
{
    public string Value { get; set; } = "";
}

generates (every model's members go into one file, GeneratedEquality.g.cs):

partial class CliOption : global::System.IEquatable<global::Demo.CliOption>
{
    public bool Equals(global::Demo.CliOption? other)
    {
        if (other is null) return false;
        if (global::System.Object.ReferenceEquals(this, other)) return true;
        // CachedText: [EqualityIgnore]
        return global::System.String.Equals(Name, other.Name, global::System.StringComparison.Ordinal)
            && global::MintPlayer.SourceGenerators.Tools.ValueEquality.List<string>(Aliases, other.Aliases)
            && global::MintPlayer.SourceGenerators.Tools.ValueEquality.ImmutableArray<global::Demo.Child>(Children, other.Children);
    }

    public override bool Equals(object? obj) => Equals(obj as global::Demo.CliOption);

    public override int GetHashCode()
    {
        unchecked
        {
            int h = 17;
            h = h * 31 + (Name is null ? 0 : global::System.StringComparer.Ordinal.GetHashCode(Name));
            h = h * 31 + global::MintPlayer.SourceGenerators.Tools.ValueEquality.ListHash<string>(Aliases);
            h = h * 31 + global::MintPlayer.SourceGenerators.Tools.ValueEquality.ImmutableArrayHash<global::Demo.Child>(Children);
            return h;
        }
    }
}

GetHashCode() hashes exactly the properties that Equals compares, so equal models always hash equally.

How each property is compared

The comparison is chosen from the declared property type at generation time; nothing is looked up at run time.

Nested shapes compose: an ImmutableArray<ImmutableArray<Model>>, a List<(string, List<Model>)> or a tuple holding a list all compare structurally.

Supported shapes

Sealed and non-sealed classes, abstract hierarchies, records (sealed or derived), structs, record structs, generic types, and types nested in any of these.

• Hierarchies. Every type deriving from a [GenerateEquality] type gets its own members too, whether or not it carries the attribute, so it must be partial as well. An instance is never equal to an instance of another runtime type.
• Equality you wrote yourself. A member the type already declares (Equals(T), Equals(object), GetHashCode()) is not generated (MINT002).

Attributes

• [GenerateEquality] on a class, record or struct: generate the members.
• [EqualityIgnore] on a property: leave it out of Equals and GetHashCode.
• [UseEqualityComparer(typeof(C))] on a property: compare it with C, an IEqualityComparer<TProperty> with a static Instance or a public parameterless constructor. For example [UseEqualityComparer(typeof(JObjectValueComparer))] from MintPlayer.ValueComparers.NewtonsoftJson.

Diagnostics

Using the models in a pipeline

No comparer is needed on any step. A model coming out of a transform, a Collect() of models, or a Combine tuple holding models all compare by value under the default comparer.

The one exception is a step that builds a new collection from its input, such as a Select after Collect() that filters or projects, or a transform returning an array. An array or ImmutableArray<T> compares by reference, so that step would report Modified on every run. Return an EquatableArray<T> (from MintPlayer.SourceGenerators.Tools) instead:

var registrationsProvider = classesProvider
    .Combine(assemblyLevelProvider)
    .Select(static (p, ct) => p.Left.Concat(p.Right).ToEquatableArray());

Joining providers

The MintPlayer.SourceGenerators.Tools package already contains 4 extension methods that help you join providers.

var sourceProvider = typeProvider
    .Join(typeTreeProvider)
    .Join(childrenWithoutDerived)
    .Join(settingsProvider)
    .Join(hasCodeAnalysisReference)
    .Select(static Producer (p, ct) => new TreeProducer(p.Item1, p.Item2, p.Item3, p.Item4.RootNamespace!, p.Item5));

By using this extension method, you can avoid the nested tuples that would require you to write p.Left.Left.Left.Left.Right to access a value. If you want to join more than 5 providers, apply [assembly: GenerateJoinMethods(n)]. The ValueComparerGenerator package then generates the overloads for 6 to n providers into JoinMethods.g.cs. They chain the same way: previous.Join(next). The generated class is internal, so every generator project gets its own copy and none of them is exposed to projects that reference it. Without the attribute, nothing is generated.

Running your generator in-process from a test project

A test project can reference a generator that uses [GenerateEquality] with a plain <ProjectReference>, to run it in-process. The attributes dll is added to that project's bin folder, but not to its deps.json. The generated equality code doesn't need it. Code that reflects over the models' attributes, such as GetCustomAttributes(), does. The classic VSTest testhost resolves the dll from bin anyway. Exe-hosted runners (xunit.v3, Microsoft.Testing.Platform) and ordinary apps throw FileNotFoundException. If your project reflects over the models' attributes, add:

<PackageReference Include="MintPlayer.ValueComparerGenerator.Attributes" Version="12.1.0" />

Breaking changes in 12.0.0

The full list, with a migration guide, is in the changelog.

• The attributes are renamed, because they no longer generate comparers: [AutoValueComparer] is now [GenerateEquality] (GenerateEqualityAttribute) and [ComparerIgnore] is now [EqualityIgnore] (EqualityIgnoreAttribute). There are no aliases. [UseEqualityComparer] and [GenerateJoinMethods] keep their names, and the package ids stay MintPlayer.ValueComparerGenerator and MintPlayer.ValueComparerGenerator.Attributes.
• The generator no longer emits an XValueComparer class, a [ValueComparer] tag, or the .WithComparer() / .WithNullableComparer() extension methods. The members are generated on the model itself. Delete every .WithComparer()/.WithNullableComparer() call; where a step builds a new collection, return EquatableArray<T>.
• Records, structs, record structs and generic models are now supported.
• A derived type is now covered even without its own attribute, and must be partial (MINT003).
• ComparerRegistry.Register is replaced by [UseEqualityComparer] on the property.
• MINT001 inspects model properties instead of .WithComparer() calls.
• Dictionaries compare order-insensitively.