Headless.AuditLog.Abstractions 0.4.15

.NET 10.0

dotnet add package Headless.AuditLog.Abstractions --version 0.4.15

NuGet\Install-Package Headless.AuditLog.Abstractions -Version 0.4.15

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Headless.AuditLog.Abstractions" Version="0.4.15" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Headless.AuditLog.Abstractions" Version="0.4.15" />
                    

                            Directory.Packages.props

<PackageReference Include="Headless.AuditLog.Abstractions" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Headless.AuditLog.Abstractions --version 0.4.15

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Headless.AuditLog.Abstractions, 0.4.15"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Headless.AuditLog.Abstractions@0.4.15

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Headless.AuditLog.Abstractions&version=0.4.15
                    

                            Install as a Cake Addin

#tool nuget:?package=Headless.AuditLog.Abstractions&version=0.4.15
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Headless.AuditLog.Abstractions

Defines the property-level audit log contracts for tracking entity mutations and explicit business events.

Problem Solved

Provides a provider-agnostic audit log API for capturing field-level entity changes and explicit events (PII reveals, cross-tenant access, etc.) without binding consumers to any specific storage implementation.

Key Features

IAuditTracked - Marker interface; entities implementing it are automatically audited on SaveChanges
AuditIgnoreAttribute - Excludes a property (or entire entity) from change capture
AuditSensitiveAttribute - Marks a property as PII/secret; value is handled per configured strategy
SensitiveDataStrategy - Redact (replace with "***"), Exclude (omit entirely), or Transform (custom function)
AuditLogOptions - Master enable/disable, AuditByDefault mode, per-entity/property filters, configurable default exclusions, sensitive-value transformer
IAuditLog<TContext> - Explicit logging of non-mutation events (reads, reveals, failures); the TContext type-arg binds the logger to a specific persistence context so multi-context applications resolve a distinct logger per owning context
IAuditLogStore - Storage abstraction called by the change-tracking pipeline. Save/SaveAsync now take the saving context (the DbContext running SaveChanges) on every call and return one IAuditLogStoreEntry handle per audit row added to that context (empty list = nothing added, orchestrator skips the audit commit step)
IAuditLogStoreEntry - Provider-owned handle for an audit row added to the persistence context; the orchestrator calls DiscardPendingChanges() on failure and ReleaseAfterCommit() after success. Implementations must be idempotent, and ReleaseAfterCommit() must not undo committed audit rows
IReadAuditLog<TContext> - Query abstraction for reading audit entries back without coupling callers to EF types; the TContext type-arg binds the reader to a specific persistence context, mirroring IAuditLog<TContext>
IAuditChangeCapture - Scans ChangeTracker entries and produces AuditLogEntryData records

Installation

dotnet add package Headless.AuditLog.Abstractions

Usage

Entity opt-in

public class Patient : AggregateRoot<Guid>, IAuditTracked
{
    public string Name { get; set; } = "";

    [AuditSensitive]
    public string NationalId { get; set; } = "";

    [AuditIgnore]
    public DateTime LastComputedAt { get; set; }
}

Registration

services.AddHeadlessAuditLog(o =>
{
    o.SensitiveDataStrategy = SensitiveDataStrategy.Redact;
});

This package registers options only. Add Headless.AuditLog.EntityFramework for the EF Core implementation that wires up storage and change capture.

Configuration

Option	Default	Description
`IsEnabled`	`true`	Master switch; `false` disables all capture
`AuditByDefault`	`false`	When `true`, audits every entity unless `[AuditIgnore]` is present
`SensitiveDataStrategy`	`Redact`	Global strategy for `[AuditSensitive]` properties
`SensitiveValueTransformer`	`null`	Required whenever the effective strategy is `Transform`; must be a pure, synchronous function
`EntityFilter`	`null`	Predicate returning `true` to exclude a type; first result is cached per type for the capture service lifetime
`PropertyFilter`	`null`	Predicate returning `true` to exclude a property; first result is cached per `(Type, propertyName)` for the capture service lifetime
`DefaultExcludedProperties`	Framework-managed names	Default property names skipped during change capture; consumers can add/remove entries

Important Notes

AddHeadlessAuditLog validates the global SensitiveDataStrategy.Transform configuration and fails options resolution when no SensitiveValueTransformer is configured.
If a property explicitly uses [AuditSensitive(SensitiveDataStrategy.Transform)], the first capture attempt throws an OptionsValidationException unless SensitiveValueTransformer is configured.
EntityFilter and PropertyFilter results are cached after first evaluation, so predicates must be pure and deterministic.
AuditLogEntryData.OldValues and NewValues may contain JsonElement values after provider round-trips; use JsonElement APIs such as GetDecimal() for typed access.
EntityId stays a plain string for single-column keys; composite keys are serialized as a JSON string array.
IpAddress and UserAgent are not auto-populated by the built-in EF change-capture pipeline; set them explicitly through IAuditLog.LogAsync or a custom capture implementation.

Dependencies

Headless.Hosting
Microsoft.Extensions.DependencyInjection.Abstractions
Microsoft.Extensions.Options

Side Effects

None. This is an abstractions package.

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.