This document describes the configuration system in Audit.NET, which controls how audit events are created, processed, and stored. The configuration system operates at multiple levels: global application-wide settings, fluent API configuration, and per-scope overrides. This system also manages data providers, custom actions, and serialization settings.
For information about data providers and their selection logic, see Data Provider Architecture. For details on event creation timing, see Event Creation Policies. For lifecycle hook implementation, see Custom Actions and Lifecycle Hooks.
The configuration system is organized around the static Configuration class, which exposes both direct property access and a fluent API. Configuration can be applied globally or overridden at the scope level.
Configuration System Structure
Sources: src/Audit.NET/Configuration.cs1-461 src/Audit.NET/ConfigurationApi/Configurator.cs1-200 src/Audit.NET/ConfigurationApi/IConfigurator.cs1-143
The Configuration static class provides direct property access for global settings that apply to all audit scopes unless overridden.
| Property | Type | Default | Description |
|---|---|---|---|
DataProvider | IAuditDataProvider | FileDataProvider | Global data provider for storing audit events |
DataProviderFactory | Func<IAuditDataProvider> | null | Lazy factory for data provider (sets LazyDataProvider) |
CreationPolicy | EventCreationPolicy | InsertOnEnd | When audit events are persisted |
AuditDisabled | bool | false | Global switch to disable all auditing |
JsonSettings | JsonSerializerOptions | Default settings | System.Text.Json serialization options |
JsonAdapter | IJsonAdapter | JsonAdapter | JSON serialization adapter |
SystemClock | ISystemClock | DefaultSystemClock | Clock implementation for timestamps |
AuditScopeFactory | IAuditScopeFactory | AuditScopeFactory | Factory for creating audit scopes |
IncludeTypeNamespaces | bool | false | Include full type names with namespaces |
IncludeStackTrace | bool | false | Include full stack trace in environment |
IncludeTimestamps | bool | false | Include timestamp values in events |
IncludeActivityTrace | bool | false | Include distributed tracing activity data |
StartActivityTrace | bool | false | Create new Activity for each scope |
ExcludeEnvironmentInfo | bool | false | Exclude environment information from events |
Configuration Reset
The Configuration.Reset() method restores all settings to their default values and clears all custom actions:
Sources: src/Audit.NET/Configuration.cs17-135 README.md3-189
The fluent API provides a chainable interface for configuration through the Configuration.Setup() method, which returns an IConfigurator instance.
Configuration API Flow
Sources: src/Audit.NET/ConfigurationApi/Configurator.cs8-200 src/Audit.NET/ConfigurationApi/IConfigurator.cs9-143
Basic Fluent Configuration Example
Sources: README.md640-679 test/Audit.UnitTest/UnitTest.cs60-95
The fluent API provides multiple methods for configuring data providers, each corresponding to different instantiation patterns.
Data Provider Configuration Methods
| Method | Description | Returns |
|---|---|---|
Use(IAuditDataProvider) | Use a pre-configured provider instance | ICreationPolicyConfigurator |
UseCustomProvider(IAuditDataProvider) | Same as Use() | ICreationPolicyConfigurator |
UseDynamicProvider(Action<IDynamicDataProviderConfigurator>) | Configure a dynamic provider with inline logic | ICreationPolicyConfigurator |
UseDynamicAsyncProvider(Action<IDynamicAsyncDataProviderConfigurator>) | Configure async dynamic provider | ICreationPolicyConfigurator |
UseFileLogProvider(Action<IFileLogProviderConfigurator>) | Configure file-based logging | ICreationPolicyConfigurator |
UseLazyFactory(Func<IAuditDataProvider>) | Lazy initialization factory (called once) | ICreationPolicyConfigurator |
UseDeferredFactory(Func<AuditEvent, IAuditDataProvider>) | Per-event provider factory | ICreationPolicyConfigurator |
UseConditional(Action<IConditionalDataProviderConfigurator>) | Conditional routing based on event | ICreationPolicyConfigurator |
UseInMemoryProvider() | Store events in memory (testing) | ICreationPolicyConfigurator |
UseInMemoryBlockingCollectionProvider() | Store events in BlockingCollection | ICreationPolicyConfigurator |
UseActivityProvider(Action<IActivityProviderConfigurator>) | Output to OpenTelemetry Activity | ICreationPolicyConfigurator |
UseNullProvider() | Disable storage (no-op provider) | ICreationPolicyConfigurator |
Dynamic Provider Configuration
File Provider Configuration
Sources: src/Audit.NET/ConfigurationApi/Configurator.cs54-199 README.md686-763
Configuration can be overridden for individual audit scopes using AuditScopeOptions, which takes precedence over global configuration.
Configuration Hierarchy
AuditScopeOptions Properties
| Property | Type | Description |
|---|---|---|
DataProvider | IAuditDataProvider | Override global data provider |
CreationPolicy | EventCreationPolicy? | Override global creation policy |
SystemClock | ISystemClock | Override global clock implementation |
IncludeTimestamps | bool? | Override timestamp inclusion flag |
IncludeActivityTrace | bool? | Override activity trace inclusion |
StartActivityTrace | bool? | Override activity creation |
IncludeStackTrace | bool? | Override stack trace inclusion |
ExcludeEnvironmentInfo | bool? | Override environment info exclusion |
AuditEvent | AuditEvent | Use existing event instance |
EventType | string | Event type identifier |
TargetGetter | Func<object> | Function to get target object |
ExtraFields | object | Additional fields to merge |
CallingMethod | MethodBase | Specific calling method |
SkipExtraFrames | int | Stack frames to skip |
IsCreateAndSave | bool | Create and immediately save |
Items | Dictionary<string, object> | Additional scope items |
Per-Scope Configuration Example
Sources: src/Audit.NET/AuditScope.cs22-79 README.md224-237 test/Audit.UnitTest/UnitTest.cs136-186
The AuditScope constructor demonstrates how configuration is resolved with the following precedence:
Configuration Resolution Logic
The resolution occurs in the AuditScope constructor at src/Audit.NET/AuditScope.cs25-79:
Sources: src/Audit.NET/AuditScope.cs25-79
Custom actions are global hooks that execute at specific points in the audit scope lifecycle. They are managed through the Configuration.AuditScopeActions concurrent dictionary.
Action Types and Timing
ActionType Enum Values
The ActionType enum defines four lifecycle hook points:
OnScopeCreated - Invoked after scope creation, before any event savingOnEventSaving - Invoked before event is persistedOnEventSaved - Invoked after event is successfully persistedOnScopeDisposed - Invoked when scope is disposedAdding Custom Actions
Custom actions can be synchronous or asynchronous, and can optionally return a boolean to control whether subsequent actions execute:
Fluent API for Actions
Sources: src/Audit.NET/Configuration.cs98-430 README.md1157-1307 test/Audit.UnitTest/UnitTest.cs56-133
Audit.NET uses System.Text.Json by default but supports custom serialization through the IJsonAdapter interface. JSON serialization is used when storing audit events and when calling ToJson() methods.
JSON Configuration Components
Default JSON Settings
The default JsonSerializerOptions configuration is:
These settings are initialized in src/Audit.NET/Configuration.cs120-125
Configuring JSON Serialization
IJsonAdapter Interface
Custom serialization can be implemented via IJsonAdapter:
Sources: src/Audit.NET/Configuration.cs95-125 README.md1308-1360 test/Audit.UnitTest/UnitTest.cs439-471 test/Audit.UnitTest/FileDataProviderTests.cs113-159
The IAuditScopeFactory interface allows customization of audit scope creation and configuration. The factory is automatically resolved from dependency injection containers by many extensions.
Factory Configuration Pattern
Custom Factory Implementation
Dependency Injection Registration
Sources: README.md105-173
Many Audit.NET extensions (Entity Framework, Web API, MVC, SignalR) automatically attempt to resolve IAuditScopeFactory and AuditDataProvider from the service provider/DI container.
Extension Resolution Flow
This automatic resolution means you can configure audit behavior through dependency injection rather than static configuration:
Sources: README.md172-173
Complete Configuration Example
Per-Scope Override Example
Sources: README.md640-679 test/Audit.UnitTest/UnitTest.cs224-295
The configuration system is implemented across the following key files:
Refresh this wiki