Carubbi.DiffAnalyzer 3.0.0

Carubbi.DiffAnalyzer

Compares two object instances by reflection and reports every added, deleted, modified and unchanged property. Built for .NET 10.

• Deep comparison: nested objects, collections and dictionaries are walked up to a configurable depth.
• Attribute-driven: [DiffAnalyzable] marks or excludes properties; [DiffKey] declares the identity of an entity.
• Two modes: compare everything (All) or only decorated properties (DecoratedOnly).
• Culture invariant: numbers and dates are rendered with CultureInfo.InvariantCulture.
• Thread safe: a single analyzer instance can be shared across concurrent comparisons.
• Blazor viewer: the companion package Carubbi.DiffAnalyzer.UI renders the results as an HTML table.

Installation

dotnet add package Carubbi.DiffAnalyzer
dotnet add package Carubbi.DiffAnalyzer.UI # optional Blazor viewer

Usage

using Carubbi.DiffAnalyzer;

var before = new User
{
    Id = 1,
    Name = "Michael",
    Nicknames = ["Mike", "MK"],
    Addresses =
    [
        new Address
        {
            Street = "1st street",
            State = new State
            {
                Name = "SP",
                Cities = [new City { Name = "Sao Paulo" }, new City { Name = "Santos" }],
            },
        },
    ],
    Phones = [new Phone { AreaCode = "11", Number = "91234-5678", Type = PhoneType.Mobile }],
};

var after = new User
{
    Id = 1,
    Name = "Michael",
    Nicknames = ["None"],
    Phones = [new Phone { AreaCode = "11", Number = "1234-5678", Type = PhoneType.Business }],
};

var analyzer = new DiffAnalyzer();
List<DiffComparison> results = analyzer.Compare(before, after);

foreach (var difference in results)
{
    Console.WriteLine($"{difference.Breadcrumb}: {difference.PreviousValue} -> {difference.CurrentValue} ({difference.State})");
}

Modes and attributes

public class User
{
    [DiffAnalyzable(DiffAnalyzableUsage.Ignore)] // excluded from every mode
    public int Id { get; set; }

    [DiffAnalyzable]                             // compared in every mode
    public string Name { get; set; }

    public List<string> Nicknames { get; set; }  // compared only in DiffModes.All

    [DiffKey]                                    // identity used to track entities across reorders
    public int Code { get; set; }
}

// Only properties marked with [DiffAnalyzable]:
var results = analyzer.Compare(before, after, DiffModes.DecoratedOnly);

Blazor viewer

@using Carubbi.DiffAnalyzer.UI

<DiffComparisonViewer Data="results"
                      Disposition="LabelDisposition.Row"
                      ShowState="true"
                      ModifiedBackColor="#fff3cd"
                      DeletedBackColor="#f8d7da"
                      AddedBackColor="#d4edda" />

Building and testing locally

Requires the .NET 10 SDK.

dotnet build -c Release
dotnet test Carubbi.DiffAnalyzer.slnx -c Release --no-build

No external infrastructure is needed: the whole suite runs as unit tests.

Releasing

Pushing a tag v* (for example v3.0.0) triggers the publish workflow, which packs both projects in Release mode and pushes them to nuget.org through trusted publishing. The workflow can also be run manually from the Actions tab via workflow_dispatch.