This document provides a high-level introduction to the Audit.NET framework, explaining its purpose, architecture, and core components. It serves as the entry point for understanding how the framework operates and how its various parts fit together.
For detailed information about specific components, see:
Audit.NET is an extensible framework for auditing executing operations in .NET and .NET Core applications. It generates audit logs with evidence for reconstruction and examination of activities that have affected specific operations or procedures.
The framework captures:
System.Diagnostics.ActivitySources: README.md1-14
Audit.NET follows a three-tier architecture that separates concerns between capturing audit events, defining what to audit, and storing audit data.
Tier 1: Core Framework provides the fundamental auditing infrastructure through classes in the Audit.NET package. This tier defines the lifecycle management (AuditScope), data container (AuditEvent), global configuration (Configuration), and the extensibility contracts (IAuditScopeFactory, IAuditDataProvider).
Tier 2: Interaction Extensions are framework-specific packages that automatically create audit scopes at strategic interception points. For example, Audit.EntityFramework.Core creates scopes during SaveChanges(), while Audit.WebApi.Core creates them for HTTP requests.
Tier 3: Data Providers implement the IAuditDataProvider interface to persist audit events to various storage backends. The framework includes 30+ data providers covering SQL databases, NoSQL stores, cloud services, messaging systems, and logging frameworks.
Sources: README.md15-48 src/pack.cmd1-114
The Configuration static class in src/Audit.NET/Configuration.cs provides global settings for the entire framework. It exposes properties for the data provider, creation policy, JSON serializer, and custom action hooks. The fluent API accessible via Configuration.Setup() provides a more readable configuration syntax.
The IAuditScopeFactory interface in src/Audit.NET/IAuditScopeFactory.cs defines the contract for creating audit scopes. The default implementation AuditScopeFactory in src/Audit.NET/AuditScopeFactory.cs reads from the global Configuration and provides virtual methods OnConfiguring() and OnScopeCreated() for customization through inheritance.
The AuditScope class in src/Audit.NET/AuditScope.cs is the central object that manages the lifecycle of an audit operation. It encapsulates an AuditEvent and controls when it is persisted to the data provider. The scope is typically used with the using pattern to ensure proper disposal and automatic saving.
The AuditEvent class in src/Audit.NET/AuditEvent.cs is the data container that holds all information about the audited operation. It includes environmental context, timing information, the tracked target object, custom fields, comments, and timed sub-events.
The IAuditDataProvider interface in src/Audit.NET/IAuditDataProvider.cs defines the contract for persisting audit events. All data providers implement this interface. The abstract AuditDataProvider class in src/Audit.NET/AuditDataProvider.cs provides a base implementation with utilities for cloning values and serialization.
Sources: README.md84-104 README.md570-589
The following diagram illustrates how an audit event progresses from creation through persistence, showing the actual method calls involved.
The lifecycle follows these steps:
Creation: Application code (or an extension) calls IAuditScopeFactory.Create() with AuditScopeOptions. The factory creates an AuditScope which internally creates an AuditEvent with initial data (start time, event type, environment).
Optional Early Insert: If EventCreationPolicy.InsertOnStartReplaceOnEnd is configured, the event is immediately inserted via IAuditDataProvider.InsertEvent() and an event ID is returned.
Enrichment: During operation execution, the application can call SetCustomField(), Comment(), or modify the target object. These modifications are tracked in the AuditEvent.
Finalization: When the scope is disposed (typically via using statement), the end date and duration are set.
Persistence: Based on the EventCreationPolicy:
InsertOnEnd: Calls InsertEvent()InsertOnStartReplaceOnEnd: Calls ReplaceEvent() with the previously returned IDManual: No automatic persistence (requires explicit Save() call)Sources: README.md224-306
Audit.NET consists of 47+ NuGet packages organized into three categories:
| Package | Description |
|---|---|
Audit.NET | Core framework with AuditScope, AuditEvent, Configuration, and built-in providers (FileDataProvider, EventLogDataProvider, ActivityDataProvider) |
| Package | Purpose |
|---|---|
Audit.EntityFramework / Audit.EntityFramework.Core | Audit EF6 / EF Core database operations |
Audit.WebApi / Audit.WebApi.Core | Audit ASP.NET Web API / Core API requests |
Audit.Mvc / Audit.Mvc.Core | Audit ASP.NET MVC / Core MVC actions |
Audit.WCF / Audit.WCF.Client | Audit WCF service operations and client calls |
Audit.SignalR | Audit SignalR hub invocations |
Audit.Grpc.Client / Audit.Grpc.Server | Audit gRPC client and server calls |
Audit.MediatR | Audit MediatR CQRS commands/queries |
Audit.Hangfire | Audit Hangfire background jobs |
Audit.AzureFunctions | Audit Azure Functions executions |
Audit.HttpClient | Audit HTTP client requests |
Audit.FileSystem | Audit file system changes |
Audit.DynamicProxy | Audit any class via Castle DynamicProxy |
Audit.MongoClient | Audit MongoDB driver operations |
SQL Databases:
Audit.NET.SqlServer, Audit.NET.PostgreSql, Audit.NET.MySql
NoSQL & Document Stores:
Audit.NET.MongoDB, Audit.NET.AzureCosmos, Audit.NET.Redis, Audit.NET.Elasticsearch, Audit.NET.OpenSearch, Audit.NET.DynamoDB, Audit.NET.RavenDB, Audit.NET.ImmuDB, Audit.NET.Firestore
Azure Services:
Audit.NET.AzureStorageBlobs, Audit.NET.AzureStorageTables, Audit.NET.AzureEventHubs
Messaging & Streaming:
Audit.NET.Kafka, Audit.NET.Channels, Audit.NET.Udp
Logging Frameworks:
Audit.NET.EventLog.Core, Audit.NET.log4net, Audit.NET.NLog, Audit.NET.Serilog
Utility Providers:
Audit.NET.Polly (resilience wrapper), Audit.NET.JsonNewtonsoftAdapter (JSON serialization adapter)
Sources: src/pack.cmd1-114 src/push.cmd1-98 README.md767-793
Audit.NET maintains broad compatibility across .NET framework versions. As of version 23.0.0, the minimum supported frameworks are:
| Framework | Minimum Version | Notes |
|---|---|---|
| .NET Framework | 4.6.2 (net462) | Full framework support |
| .NET Framework | 4.7.2 (net472) | Additional target for enhanced APIs |
| .NET Standard | 2.0 (netstandard2.0) | Cross-platform compatibility |
| .NET Standard | 2.1 (netstandard2.1) | Enhanced async support |
| .NET | 6.0 (net6.0) | LTS version |
| .NET | 7.0 (net7.0) | Standard support |
| .NET | 8.0 (net8.0) | LTS version |
| .NET | 9.0 (net9.0) | Current version |
| .NET | 10.0 (net10.0) | Preview/upcoming support |
The core Audit.NET package targets all these frameworks, providing maximum compatibility. Individual extension packages target appropriate subsets based on their dependencies. For example, Audit.Grpc.Client and Audit.Grpc.Server target only modern .NET (6.0+) due to gRPC library requirements.
Framework-specific variants use conditional compilation with symbols like NET462, NETSTANDARD2_0, NET6_0_OR_GREATER to provide platform-appropriate implementations while sharing common code.
Sources: README.md174-188 CHANGELOG.md196-200 Directory.Build.props1-28
If no data provider is explicitly configured, Audit.NET defaults to FileDataProvider which writes audit events as JSON files to the current working directory. This ensures audit events are captured even in unconfigured scenarios.
As of version 18.0.0, System.Text.Json is the default JSON serializer for .NET 5.0+. For earlier framework versions or when Audit.NET.JsonNewtonsoftAdapter is referenced, Newtonsoft.Json is used. The serialization behavior is abstracted through the IJsonAdapter interface.
The default EventCreationPolicy is InsertOnEnd, which persists the audit event only when the scope is disposed. This is suitable for most scenarios but can be changed globally or per-scope.
When using dependency injection, extensions like Audit.EntityFramework.Core, Audit.WebApi.Core, Audit.Mvc.Core, and Audit.SignalR automatically resolve IAuditScopeFactory and AuditDataProvider from the service provider if registered.
Sources: README.md635-637 CHANGELOG.md391-392
In this example:
Configuration.Setup() configures the global SQL Server data providerAuditScope.Create() creates a scope tracking an Order objectSetCustomField() and Comment() enrich the audit eventusing statement ensures Dispose() is called, triggering persistenceSources: README.md189-257
Refresh this wiki