Observer.Auditing.Contract 1.0.1

Observer.Auditing.Contract

Drop-in change auditing for any .NET service. Captures every insert/update/delete you opt into, stores it locally in the same transaction as the business change, and ships it to the Audit service over gRPC in the background.

No message broker. No added request latency. No lost records if the audit service is down.

handler saves          →  interceptor writes an outbox row in the SAME transaction
                          (request returns here — audit cost ≈ one local INSERT)
background dispatcher  →  gRPC RecordAuditBatch  →  audit service stores it
background registrar   →  gRPC RegisterAuditableEntities  →  registry rows created for you

Two packages:

Setup — five steps

1. Mark your entity base

public abstract class Entity : IAuditableEntity
{
    public Guid ObjectKey { get; set; } = Guid.NewGuid();   // must be CLR-generated
    public bool IsDeleted { get; set; }
}

2. Map and migrate the outbox

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.AddAuditOutbox();      // creates Audit.AuditOutbox
}

dotnet ef migrations add AddAuditOutbox

If you apply a global query filter by looping over every mapped type, skip this one — it has no IsDeleted column.

3. Register, and declare what you audit — in code

services.AddAuditing<ApplicationDbContext>(configuration, audit =>
{
    audit.Audit<Area>();
    audit.Audit<DeviceOwner>().Ignoring(owner => owner.NationalId);
    audit.Audit<Device>();
});

services.AddDbContext<ApplicationDbContext>((serviceProvider, options) => options
    .UseNpgsql(connectionString)
    .AddAuditCapture(serviceProvider));      // no-op when disabled

AddAuditing must come first. A type argument can't be misspelled and survives renames — a config string can't do either.

4. Tell it who the user is

internal sealed class AuditActorProvider(IUserContext user) : IAuditActorProvider
{
    public Guid UserId => Guid.TryParse(user.UserId, out Guid id) ? id : Guid.Empty;
    public string? DisplayName => user.DisplayName;
}

services.AddScoped<IAuditActorProvider, AuditActorProvider>();   // before AddAuditing

Skip this and every change is attributed to the system actor. Optionally add IAuditCorrelationProvider to carry your request correlation id.

5. Configure

"AuditService": {
  "Enabled": true,
  "GrpcAddress": "http://127.0.0.1:5327",   // the audit service's h2c port, NOT its REST port
  "SourceService": "AMS.AVL.Core"           // must match your registry rows
}

That's it. On startup the service announces its entities and the registry rows are created automatically — no SQL.

Declaring business intent

Only when a column diff can't express it:

_auditScope.Set(AuditBusinessAction.Deactivate);
await _unitOfWork.SaveChangesAsync();

Create, Update and Delete are inferred. A soft delete (IsDeleted false → true) is detected as Delete automatically.

Redacting — two levels

A save that only touches an Ignoring property is recorded, naming it. A save that only touches a [NoAudit] property records nothing — the entry would betray the change by existing.

Configuration reference

Outbox retention

The outbox is a queue, not a second copy of the trail. Delivered rows are pruned after OutboxRetention. Pending and dead-lettered rows are never pruned — they're changes with no compliance record yet.

Scaling out

Rows drain in Id order, which preserves per-aggregate order only while one dispatcher runs. On multiple replicas set RunDispatcher: false on all but one. Two dispatchers racing is safe, just wasteful.

Monitoring

Troubleshooting

Known gaps

1. No service-account credential. The dispatcher runs with no HttpContext; it needs client-credentials or mTLS before any non-local deployment.
2. Protos are vendored, not packaged. Scripts/verify-proto-parity.ps1 fails on drift.

Build

dotnet build Observer.Auditing.Contract.slnx
dotnet pack  Observer.Auditing.Contract.slnx -c Release -o nupkg
pwsh Observer.Auditing.Contract/Scripts/verify-proto-parity.ps1