File Logger Configuration
The file logger is configured via the FileLoggerConfiguration options class. Options can be supplied from
configuration (the Logging:File section), from code, or both — values set in code override bound values.
Use this page to choose where files go, how they are named, and when they roll over.
Options reference
| Option | Type | Default | Description |
|---|---|---|---|
LogDirectory |
string |
"Logs" |
Directory for log files. Absolute, or relative to the current working directory. Created automatically. |
LogName |
string |
AppDomain.CurrentDomain.FriendlyName |
Base file name (no extension), initialized to the application's friendly name. |
PerGroupLogName |
Dictionary<string, string?> |
empty | Group suffixes appended to the base name before any level suffix. Null or empty values add nothing. |
PerLevelLogName |
Dictionary<LogLevel, string?> |
empty | Level suffixes appended after the base name and any group suffix. Null or empty values add nothing. |
FileSizeLimitBytes |
long |
104857600 (100 MiB) |
Rollover threshold for an existing active file plus the pending UTF-8 entry or batch. Equality triggers rollover. |
RolloverInterval |
FileRolloverInterval |
Day |
Time-based rollover interval: Infinite, Year, Month, Day, Hour, or Minute. |
MaxTotalSizeBytes |
long |
10737418240 (10 GiB) |
Archive retention threshold per resolved file name. At most one oldest archive is deleted when the threshold is met. |
Use a positive value for each size setting. Zero or negative values do not disable either feature:
FileSizeLimitBytes then rolls an existing file before every write, and MaxTotalSizeBytes deletes one
qualifying archive whenever retention is checked. To disable time-based rollover, use Infinite.
The size settings are thresholds, not hard quotas. A single entry or buffered batch is never split, and retention excludes active files. See File Rollover and Retention for sizing details.
Configuring via appsettings.json
The provider registers under the alias File, so it binds to the Logging:File section:
{
"Logging": {
"File": {
"LogDirectory": "C:/logs/my-app",
"LogName": "my-app",
"FileSizeLimitBytes": 52428800,
"RolloverInterval": "Hour",
"MaxTotalSizeBytes": 1073741824,
"PerGroupLogName": {
"Orders": "orders"
},
"PerLevelLogName": {
"Error": "errors",
"Critical": "errors"
}
}
}
}
Note
RolloverInterval accepts the enum names: Infinite, Year, Month, Day, Hour, Minute.
Configuring in code
using Invex.Extensions.Logging.File;
using Invex.Extensions.Logging.File.Configuration;
using Microsoft.Extensions.Logging;
builder.Logging.AddFile(options =>
{
options.LogDirectory = "Logs";
options.LogName = "my-app";
options.FileSizeLimitBytes = 50L * 1024 * 1024; // 50 MiB
options.RolloverInterval = FileRolloverInterval.Hour;
options.MaxTotalSizeBytes = 1L * 1024 * 1024 * 1024; // 1 GiB
options.PerGroupLogName["Orders"] = "orders";
options.PerLevelLogName[LogLevel.Error] = "errors";
options.PerLevelLogName[LogLevel.Critical] = "errors";
});
Keep file names and suffixes to file name components without .log or directory separators. Set the
directory through LogDirectory. Names are not trimmed or sanitized, and invalid destination paths
follow the write retry and drop policy. LogName is initialized to
AppDomain.CurrentDomain.FriendlyName when the options instance is created. An empty string is used
literally and produces .log without other suffixes.
SetLogNameSuffix helper
SetLogNameSuffix(string suffix) replaces LogName with
$"{AppDomain.CurrentDomain.FriendlyName}_{suffix}", regardless of the currently configured name.
For an application whose friendly name is MyApp:
| Call | Resulting LogName |
Active file before group/level routing |
|---|---|---|
options.SetLogNameSuffix("worker") |
"MyApp_worker" |
MyApp_worker.log |
options.SetLogNameSuffix("") |
"MyApp_" |
MyApp_.log |
To restore the unsuffixed application friendly name, assign it directly:
options.LogName = AppDomain.CurrentDomain.FriendlyName;
Routing levels to separate files
PerLevelLogName maps a LogLevel to a suffix appended to LogName, separated by an underscore.
Without a group suffix, a mapped level writes to {baseName}_{levelSuffix}.log; missing, null, or empty
level suffixes leave {baseName}.log. The base name defaults to AppDomain.CurrentDomain.FriendlyName.
Matching group suffixes are inserted before level suffixes, as described below.
builder.Logging.AddFile(options =>
{
options.LogName = "app";
// Errors and critical entries go to their own file
options.PerLevelLogName[LogLevel.Error] = "errors";
options.PerLevelLogName[LogLevel.Critical] = "errors";
// Trace entries go to a separate diagnostic file
options.PerLevelLogName[LogLevel.Trace] = "trace";
});
With those levels enabled by the framework's filters, produces:
Logs/
app.log <- Debug, Information, Warning
app_errors.log <- Error, Critical
app_trace.log <- Trace
Each file rolls over and is purged independently, using the same FileSizeLimitBytes, RolloverInterval,
and MaxTotalSizeBytes settings.
Tip
A null or empty value in either mapping dictionary omits that suffix and its separator. The base name
and any other nonempty suffix still apply.
Migrating existing level mappings
Important
PerLevelLogName values now append to LogName as suffixes instead of replacing it. Update existing
full-name mappings to suffixes; for example, use "errors" with LogName = "my-app" to write
my-app_errors.log.
PerLevelLogName now contains suffixes rather than replacement file names. This intentionally changes
the behavior of existing mappings. For example, LogName = "app" with an existing Error = "app-errors"
mapping now produces app_app-errors.log. Change the mapping to "errors" to produce app_errors.log.
Null level mappings now omit the level suffix and retain the configured LogName.
Migrating log names
LogName is now a non-nullable string initialized to AppDomain.CurrentDomain.FriendlyName.
Leave it unset to use that default, or assign the friendly name explicitly to reset it; assigning null
no longer selects the application name. The DefaultLogName constant has been removed.
SetLogNameSuffix now takes a non-nullable suffix and includes the application's friendly name. For
example, SetLogNameSuffix("worker") changes from _worker.log to MyApp_worker.log for an application
named MyApp. It replaces any custom LogName; an empty suffix produces MyApp_.log.
Routing groups to separate files
PerGroupLogName maps a scoped group to a suffix appended to the base name. Use BeginGroupScope to set
the group before logging:
using Invex.Extensions.Logging.File;
using Microsoft.Extensions.Logging;
builder.Logging.AddFile(options =>
{
options.LogName = "app";
options.PerGroupLogName["Orders"] = "orders";
options.PerLevelLogName[LogLevel.Error] = "errors";
});
// Later, using an ILogger from the application's logging infrastructure:
using (logger.BeginGroupScope("Orders"))
{
logger.LogInformation("Order submitted"); // app_orders.log
logger.LogError("Payment failed"); // app_orders_errors.log
}
| Group | Level | File |
|---|---|---|
Orders |
Error |
app_orders_errors.log |
Orders |
Information |
app_orders.log |
| Missing or unmapped | Error |
app_errors.log |
| Missing or unmapped | Information |
app.log |
File names always start with LogName, which defaults to AppDomain.CurrentDomain.FriendlyName.
Append each nonempty mapped suffix in group-then-level order, with an underscore before each suffix:
{baseName}[_{groupSuffix}][_{levelSuffix}].log. Brackets denote optional components, not literal text.
Mapped suffixes are used verbatim. A missing, null, or empty mapping adds no text and no separator.
For example, a null group suffix with an "errors" level suffix produces app_errors.log; two omitted
suffixes produce app.log. Routes that resolve to the same name share a file and its rollover and
retention limits.
Case-only destination aliases follow the actual filesystem behavior in the destination directory, including when batching entries and protecting active files during rollover and retention. See file naming for the filesystem check used for these aliases.
Groups are case-sensitive by default; a dictionary supplied in code uses its configured comparer. The
scope property key must be exactly "Group".
BeginGroupScope delegates to ILogger.BeginScope and returns its disposable (which can be null if no
provider supports scopes). Standard structured scopes also work:
using (logger.BeginScope(new Dictionary<string, object?> { ["Group"] = "Orders" }))
{
logger.LogInformation("Order submitted");
}
using (logger.BeginScope("{Group}", "Orders"))
{
logger.LogInformation("Order submitted");
}
Scope state must implement IEnumerable<KeyValuePair<string, object?>>. The innermost nonempty string
group wins, even when it has no mapping: an unmapped inner group uses normal level/default routing,
rather than an outer group's mapping. Disposing the scope restores the outer group. Null, empty, and
non-string group values, and unstructured scopes, are ignored, leaving any outer group effective.
These rules also apply to values passed through the helper; a null logger throws ArgumentNullException.
Whitespace-only group names and suffixes count as nonempty and are used literally.
Scopes flow across await and logger categories within the same logging infrastructure; concurrent
execution contexts maintain independent scopes. The helper creates ordinary scope state, which other
logging providers may also inspect. Group data is not included in the file's log-line format.
Runtime configuration changes
The provider monitors its options with IOptionsMonitor<T>. Changes to the Logging:File section in
appsettings.json (or any reloadable configuration source) are picked up automatically and applied to
subsequent log writes — no restart required.
The group string is captured when Log is called. Both writers resolve that group and the entry's level
using configuration at write time (once per batch in buffered mode), so queued entries can use updated
file mappings. Disposing a scope or changing its dictionary after logging does not change the captured
group. The formatted message and timestamp are also captured before queueing.
Code configuration delegates run again when the options are recreated, so values they set continue to
override bound values after a reload. Changing a route leaves its previous files in place; retention only
examines archives for the route currently being written. The buffered registration flag is not an
option and cannot be changed through Logging:File at runtime.
Default constants
Fixed scalar defaults are exposed as public constants on FileLoggerConfiguration for use in your own code:
FileLoggerConfiguration.DefaultLogDirectoryFileLoggerConfiguration.DefaultFileSizeLimitBytesFileLoggerConfiguration.DefaultRollingIntervalFileLoggerConfiguration.DefaultMaxTotalSizeBytes
LogName defaults to AppDomain.CurrentDomain.FriendlyName and has no default constant.
PerGroupLogName and PerLevelLogName each default to an empty dictionary and have no default constant.
See also
- File Rollover and Retention — file naming, rollover, and purging
- Buffered vs. Direct Writing — write modes and error handling
- File Log Output Format — the shape of each log line
- FileLoggerConfiguration
- FileRolloverInterval
- FileLoggerExtension