Audentity 1.0.0

Getting started

To collect traces, you want to catch the state of the Microsoft.EntityFrameworkCore.ChangeTracking.ChangeTracker before saving changes. That can be done simply by overriding the SaveChanges() & SaveChangesAsync(CancellationToken) methods in your Microsoft.EntityFrameworkCore.DbContext implementation.

public class Database : DbContext
{
    public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = new())
    {
        ImmutableList<EntityTrace> traces = ChangeTracker.Entries()
            .Select(EntityTrace.FromEntry)
            .ToImmutableList();
        
        int result = await base.SaveChangesAsync(cancellationToken);
        // Process traces...
        return result;
    }
}

Shadow Entries

If you have many-to-many relationships in your database model, Entity Framework will generate a shadow entity that represents a reference between two entities - unless you have defined such an entity yourself.

public class Project
{
    public Guid Id { get; set; }
    public IEnumerable<User> Users { get; set; }
}

public class User
{
    public Guid Id { get; set; }
    public IEnumerable<Project> Projects { get; set; }
}

// Shadow entity generated by Entity Framework:
public class ProjectUser
{
    public Guid ProjectId { get; set; }
    public Guid UserId { get; set; }
}

Those entities, even if they are not defined in the code itself, will still end up in our trace collection. To exclude them from traces, you can filter all entries by their CLR type before collecting traces.

ChangeTracker.Entries()
    .Where(e => e.Metadata.ClrType != typeof(Dictionary<string, object>))
    .Select(EntityTrace.FromEntry);

Entity Trace Structure (JSON)

Each EntityTrace consist of the following properties:

• Name - name of the entity that is being tracked.
• Properties - list of entity properties and their values.
• References - list of entity references and their links.
• State - current state of the entity.

  {
    "Name": "Audentity.Tests.User",
    "Properties": [
      {
        "CurrentValue": "Guid_5",
        "OriginalValue": "Guid_5",
        "Name": "Id"
      },
      {
        "CurrentValue": "User1",
        "OriginalValue": "User1",
        "Name": "Name"
      },
      {
        "CurrentValue": "Guid_1",
        "OriginalValue": "Guid_1",
        "Name": "TenantId"
      }
    ],
    "References": [
      {
        "Links": [
          {
            "Name": "UserId",
            "Value": "Guid_5"
          }
        ],
        "Name": "Address",
        "Target": "Audentity.Tests.Address"
      },
      {
        "Links": [
          {
            "Name": "Id",
            "Value": "Guid_2"
          }
        ],
        "Name": "Projects",
        "Target": "Audentity.Tests.Project"
      },
      {
        "Links": [
          {
            "Name": "Id",
            "Value": "Guid_3"
          }
        ],
        "Name": "Projects",
        "Target": "Audentity.Tests.Project"
      },
      {
        "Links": [
          {
            "Name": "Id",
            "Value": "Guid_4"
          }
        ],
        "Name": "Projects",
        "Target": "Audentity.Tests.Project"
      }
    ],
    "State": "Added"
  }