NB.EfCore.AuditLog 1.0.0

EfCore.AuditLog

Audit logging for Entity Framework Core using SaveChangesInterceptor.

It tracks INSERT, UPDATE, and DELETE operations, stores old and new value snapshots as JSON, and can attach user, tenant, source, and trace metadata through a pluggable provider.

Features

• Zero changes to your existing SaveChanges() and SaveChangesAsync() calls
• Opt-in or opt-out auditing with [Auditable] and ignore rules
• Property-level filtering with [AuditIgnore] or global ignored property names
• User-context enrichment through IAuditUserProvider
• Same-transaction persistence so audit rows are committed atomically with the business change
• Support for insert, update, and delete snapshots
• Tested against SQLite with coverage for core interceptor behavior

Installation

Install-Package EfCore.AuditLog

Or with the .NET CLI:

dotnet add package EfCore.AuditLog

Requirements

• .NET 8.0
• EF Core 7.0 or later

Quick Start

1. Configure audit options and services

var auditOptions = new AuditOptions
{
    Mode = AuditMode.OptIn,
    TableName = "audit_logs"
    // Schema = "audit"
};

auditOptions.IgnoreProperties("PasswordHash", "SecurityStamp");

builder.Services.AddAuditLogging(options =>
{
    options.Mode = auditOptions.Mode;
    options.TableName = auditOptions.TableName;
    options.Schema = auditOptions.Schema;
    options.EnableMultiTenancy = auditOptions.EnableMultiTenancy;
    options.IgnoreProperties("PasswordHash", "SecurityStamp");
});

builder.Services.AddScoped<IAuditUserProvider, MyAuditUserProvider>();

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    options.UseSqlServer(connectionString);
    options.AddAuditInterceptor(sp);
});

2. Configure your DbContext

public class AppDbContext : DbContext
{
    private readonly AuditOptions _auditOptions;

    public AppDbContext(DbContextOptions<AppDbContext> options, AuditOptions auditOptions)
        : base(options)
    {
        _auditOptions = auditOptions;
    }

    public DbSet<AuditLogEntry> AuditLogs => Set<AuditLogEntry>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyAuditLogConfiguration(_auditOptions);
    }
}

3. Mark entities for auditing

[Auditable]
public class Order
{
    public int Id { get; set; }
    public string CustomerName { get; set; } = null!;
    public decimal Total { get; set; }

    [AuditIgnore]
    public string? InternalNotes { get; set; }
}

4. Implement IAuditUserProvider

using System.Security.Claims;
using EfCore.AuditLog.Abstractions;

public sealed class MyAuditUserProvider : IAuditUserProvider
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public MyAuditUserProvider(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public string? GetUserId()
        => _httpContextAccessor.HttpContext?.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;

    public string? GetUserEmail()
        => _httpContextAccessor.HttpContext?.User?.FindFirst(ClaimTypes.Email)?.Value;

    public string? GetTenantId()
        => _httpContextAccessor.HttpContext?.Request.Headers["X-Tenant-Id"].FirstOrDefault();

    public string? GetSource() => "MyApp";

    public string? GetTraceId() => _httpContextAccessor.HttpContext?.TraceIdentifier;
}

What Gets Logged

Each audit row stores:

• Table name
• Record identifier
• Operation type
• JSON snapshots of old and new values
• User, email, tenant, source, and trace information when available
• UTC timestamp of the change

Configuration Options

services.AddAuditLogging(options =>
{
    options.TableName = "audit_logs";
    options.Schema = null;
    options.Mode = AuditMode.OptIn;
    options.EnableMultiTenancy = false;

    options.IgnoreEntities(typeof(TempLog));
    options.IgnoreProperties("PasswordHash", "SecretKey");
});

Notes

• The package persists audit rows in the same save pipeline as the business operation.
• This favors consistency and atomicity over fully decoupled background logging.
• For inserted entities with database-generated keys, the interceptor performs a follow-up save to populate the final RecordId.
• If you customize TableName or Schema, pass the same AuditOptions instance into ApplyAuditLogConfiguration(...) in your DbContext.

Release Notes

See CHANGELOG.md for version history.

License

MIT