Architecture

Relevant source files

• Audit.NET.sln
• README.md
• src/Audit.NET/AuditScope.cs
• src/Audit.NET/Configuration.cs
• src/Audit.NET/ConfigurationApi/Configurator.cs
• src/Audit.NET/ConfigurationApi/FileLogProviderConfigurator.cs
• src/Audit.NET/ConfigurationApi/IConfigurator.cs
• src/Audit.NET/ConfigurationApi/IFileLogProviderConfigurator.cs
• src/pack.cmd
• src/push.cmd
• test/Audit.UnitTest/FileDataProviderTests.cs
• test/Audit.UnitTest/UnitTest.Async.cs
• test/Audit.UnitTest/UnitTest.cs

This document describes the architectural design of Audit.NET, focusing on its core components, extension mechanisms, and design patterns. For basic usage patterns, see Getting Started. For details on individual components like AuditScope and AuditEvent, see AuditScope and AuditEvent.

Overview

Audit.NET implements a hub-and-spoke architecture where the core framework (Audit.NET) acts as a central orchestrator, and extensions radiate outward as pluggable modules. The architecture separates three concerns:

1. Core Framework: Lifecycle management, event modeling, and configuration
2. Interaction Extensions: Integration with application frameworks (Entity Framework, ASP.NET, etc.)
3. Output Extensions: Storage backends for audit events (SQL, NoSQL, Cloud, etc.)

This separation enables:

• Adding new integrations without modifying the core
• Swapping storage providers without affecting application code
• Composing multiple providers using wrappers

---

Core Architecture Diagram

Sources: src/Audit.NET/Configuration.cs src/Audit.NET/AuditScope.cs src/Audit.NET/AuditEvent.cs src/Audit.NET/IAuditDataProvider.cs

---

Core Components

AuditScope

The AuditScope class is the central orchestrator that controls the lifecycle of an audit event. It is responsible for:

• Creation: Capturing initial state (start time, environment, target object)
• Modification: Tracking changes during execution
• Finalization: Recording end state and saving to storage

Key characteristics:

• Implements IDisposable and IAsyncDisposable for automatic lifecycle management
• Holds reference to the AuditEvent being tracked
• Manages interaction with IAuditDataProvider
• Executes custom actions at lifecycle hooks

Sources: src/Audit.NET/AuditScope.cs15-556

AuditEvent

AuditEvent is the data model representing audited information. It contains:

Property	Type	Description
EventType	string	User-defined event category
Environment	AuditEventEnvironment	Machine, user, calling method info
StartDate / EndDate	DateTime	Timestamps
Duration	int	Milliseconds elapsed
Target	AuditTarget	Old/New state of tracked object
CustomFields	Dictionary<string, object>	User-defined data
Comments	List<string>	Audit trail comments
TimedEvents	List<TimedEvent>	Sub-event checkpoints

The event is serialized to JSON when persisted by data providers.

Sources: src/Audit.NET/AuditEvent.cs README.md363-404

IAuditDataProvider

The storage abstraction interface with three core methods:

Implementations include:

• SQL Providers: SqlDataProvider, MySqlDataProvider, PostgreSqlDataProvider
• NoSQL Providers: MongoDataProvider, RedisDataProvider, AzureCosmosDataProvider
• Utility Providers: FileDataProvider, InMemoryDataProvider, NullDataProvider

Sources: src/Audit.NET/IAuditDataProvider.cs README.md570-628

Configuration

The Configuration static class provides global settings:

Configuration can be set via:

• Direct property assignment: Configuration.DataProvider = new FileDataProvider()
• Fluent API: Configuration.Setup().UseFileLogProvider(...).WithCreationPolicy(...)

Sources: src/Audit.NET/Configuration.cs12-450

IAuditScopeFactory

The factory abstraction for creating AuditScope instances. The default implementation is AuditScopeFactory, but users can provide custom implementations to:

• Centralize configuration across the application
• Inject dependencies (useful with DI containers)
• Customize scope creation behavior via OnConfiguring and OnScopeCreated hooks

Sources: README.md105-172 src/Audit.NET/IAuditScopeFactory.cs

---

Extension Mechanisms

Interaction Extensions

Interaction extensions intercept operations in application frameworks and automatically create AuditScope instances. Each extension follows a pattern:

Examples:

• Entity Framework: AuditDbContext overrides SaveChanges() to create scope with EntityFrameworkEvent
• ASP.NET Web API: AuditApiAttribute filter creates scope with AuditApiAction
• WCF: AuditBehavior attribute intercepts service calls

Sources: README.md15-28 Diagram 3 from system diagrams

Output Extensions (Data Providers)

Data providers implement IAuditDataProvider to store events. The framework includes:

Category	Providers	Key Classes
SQL	SQL Server, MySQL, PostgreSQL	SqlDataProvider, MySqlDataProvider, PostgreSqlDataProvider
NoSQL	MongoDB, Redis, Cosmos DB, Elasticsearch	MongoDataProvider, RedisDataProvider, AzureCosmosDataProvider
Cloud	Azure Blobs, Azure Tables, Event Hubs	AzureStorageBlobDataProvider, AzureEventHubsDataProvider
Utility	File, InMemory, Null, Activity	FileDataProvider, InMemoryDataProvider, ActivityDataProvider

Each provider has a fluent configuration API accessible via Configuration.Setup():

Configuration.Setup()
    .UseSqlServer(config => config
        .ConnectionString("...")
        .TableName("AuditEvents")
        .IdColumnName("EventId")
        .JsonColumnName("JsonData"));

Sources: README.md767-795 src/Audit.NET/ConfigurationApi/Configurator.cs9-200

Wrapper Providers

Wrappers enhance data providers with cross-cutting concerns:

Examples:

• PollyDataProvider: Adds retry, circuit breaker, timeout policies
• LazyDataProvider: Delays provider creation until first use (useful for DI scenarios)
• DeferredDataProvider: Creates a new provider per event based on event properties
• ConditionalDataProvider: Routes to different providers based on conditions

Sources: README.md681-763 src/Audit.NET/ConfigurationApi/Configurator.cs63-77

---

Event Creation Policies

The EventCreationPolicy enum controls when events are inserted/updated:

Configured globally or per-scope:

Sources: src/Audit.NET/EventCreationPolicy.cs README.md306-307 src/Audit.NET/AuditScope.cs254-293

---

Custom Actions and Lifecycle Hooks

Custom actions execute at four lifecycle points:

Actions can be:

• Synchronous: Action<AuditScope>
• Asynchronous: Func<AuditScope, Task>
• Conditional: Return bool to halt subsequent actions

Example:

Sources: src/Audit.NET/Configuration.cs147-350 README.md56-95

---

Configuration API Architecture

The configuration system uses a fluent interface pattern:

Key interfaces:

• IConfigurator: Entry point for provider selection
• ICreationPolicyConfigurator: Policy and action configuration
• ICustomActionConfigurator: Custom action registration

Sources: src/Audit.NET/ConfigurationApi/IConfigurator.cs9-142 src/Audit.NET/ConfigurationApi/Configurator.cs9-200

---

Multi-Framework Targeting

Audit.NET and its extensions support multiple .NET versions using conditional compilation:

Target Framework	Support
.NET Framework	4.6.2, 4.7.2
.NET Standard	2.0, 2.1
Modern .NET	6.0, 7.0, 8.0, 9.0, 10.0

Framework-specific features:

• EventLog provider available only on net462 and net472
• Full async/await support on all targets
• EF Core extensions target multiple EF versions (5.0-10.0)

Sources: README.md174-188 Directory.Build.props Audit.NET.sln1-204

---

Dependency Flow

The core has no compile-time dependencies on extensions or providers. All integration is through abstractions (IAuditDataProvider, IAuditScopeFactory), allowing runtime composition.

Sources: Audit.NET.sln1-204 Diagram 1 from system diagrams

---

Key Design Patterns

Factory Pattern

• IAuditScopeFactory / AuditScopeFactory for scope creation
• Allows dependency injection and centralized configuration

Provider Pattern

• IAuditDataProvider abstracts storage
• Multiple implementations without core changes

Template Method Pattern

• AuditScope defines lifecycle template
• EventCreationPolicy customizes save behavior
• Custom actions inject behavior at specific points

Decorator Pattern

• Wrapper providers (PollyDataProvider, LazyDataProvider) enhance base providers
• Chain multiple wrappers for composed behavior

Fluent Interface Pattern

• Configuration.Setup() chain for readable configuration
• Provider-specific fluent APIs (UseSqlServer(), UseRedis())

Sources: src/Audit.NET/AuditScope.cs15-556 src/Audit.NET/ConfigurationApi/

---

Summary

The Audit.NET architecture achieves extensibility through:

1. Abstraction: Core interfaces (IAuditDataProvider, IAuditScopeFactory) separate concerns
2. Lifecycle Management: AuditScope orchestrates event tracking with well-defined hooks
3. Composition: Wrapper providers and custom actions enable behavior composition
4. Framework Integration: Extension pattern allows framework-specific audit capture
5. Configuration Flexibility: Multiple configuration methods (direct, fluent, factory) support various scenarios

This design enables adding storage backends, framework integrations, and cross-cutting concerns without modifying the core framework.

Sources: All files referenced above, system architecture diagrams