Philiprehberger.ChangeTracker 0.2.0

Philiprehberger.ChangeTracker

Track and diff property changes on objects over time for audit logging.

Installation

dotnet add package Philiprehberger.ChangeTracker

Usage

Mark your class with [TrackChanges], then create a tracker and inspect changes:

using Philiprehberger.ChangeTracker;

[TrackChanges]
public class User
{
    public string Name { get; set; } = "";
    public string Email { get; set; } = "";

    [IgnoreChanges]
    public DateTime LastLogin { get; set; }

    [SensitiveProperty]
    public string Password { get; set; } = "";
}

var user = new User { Name = "Alice", Email = "alice@example.com", Password = "secret" };
var tracker = ChangeTracker.For(user);

user.Name = "Bob";
user.Email = "bob@example.com";
user.Password = "new-secret";
user.LastLogin = DateTime.UtcNow; // ignored

IReadOnlyList<PropertyChange> changes = tracker.GetChanges();
// [
//   PropertyChange { PropertyName = "Name", OldValue = "Alice", NewValue = "Bob", ... },
//   PropertyChange { PropertyName = "Email", OldValue = "alice@example.com", NewValue = "bob@example.com", ... },
//   PropertyChange { PropertyName = "Password", OldValue = "***", NewValue = "***", ... }
// ]

Nested Object Tracking

Properties that are complex objects are tracked recursively with dot-notation paths:

public class Address
{
    public string City { get; set; } = "";
    public string Street { get; set; } = "";
}

[TrackChanges]
public class Customer
{
    public string Name { get; set; } = "";
    public Address Address { get; set; } = new();
}

var customer = new Customer
{
    Name = "Alice",
    Address = new Address { City = "Berlin", Street = "Main St" }
};
var tracker = ChangeTracker.For(customer);

customer.Address.City = "Munich";

var changes = tracker.GetChanges();
// PropertyChange { PropertyName = "Address.City", OldValue = "Berlin", NewValue = "Munich" }

Collection Diff

When a tracked list property changes, individual element additions, removals, and modifications are reported:

[TrackChanges]
public class Order
{
    public List<string> Items { get; set; } = new();
}

var order = new Order { Items = new List<string> { "Apple", "Banana" } };
var tracker = ChangeTracker.For(order);

order.Items = new List<string> { "Apple", "Cherry", "Date" };

var changes = tracker.GetChanges();
// changes[0].CollectionDiff.Changes:
//   CollectionChange { Index = 1, Kind = Modified, OldValue = "Banana", NewValue = "Cherry" }
//   CollectionChange { Index = 2, Kind = Added, OldValue = null, NewValue = "Date" }

Rollback

Revert the tracked object to its snapshot state:

var user = new User { Name = "Alice", Email = "alice@example.com" };
var tracker = ChangeTracker.For(user);

user.Name = "Bob";
user.Email = "bob@example.com";

tracker.Rollback();
// user.Name == "Alice", user.Email == "alice@example.com"

JSON Serialization

ChangeSet changeSet = tracker.GetChangeSet();
string json = changeSet.ToJson();

ChangeSet restored = ChangeSet.FromJson(json);

API

ChangeTracker

ChangeTracker<T>

PropertyChange

CollectionDiff

CollectionChange

ChangeSet

Attributes

Development

dotnet build src/Philiprehberger.ChangeTracker.csproj --configuration Release
dotnet test tests/Philiprehberger.ChangeTracker.Tests/Philiprehberger.ChangeTracker.Tests.csproj --configuration Release

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT