Aore.Logger
1.2.2
.NET 8.0
This package targets .NET 8.0. The package is compatible with this framework or higher.
.NET Standard 2.0
This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
.NET Framework 4.6.2
This package targets .NET Framework 4.6.2. The package is compatible with this framework or higher.
dotnet add package Aore.Logger --version 1.2.2
NuGet\Install-Package Aore.Logger -Version 1.2.2
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="Aore.Logger" Version="1.2.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Aore.Logger" Version="1.2.2" />
<PackageReference Include="Aore.Logger" />
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 Aore.Logger --version 1.2.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Aore.Logger, 1.2.2"
#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 Aore.Logger@1.2.2
#: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=Aore.Logger&version=1.2.2
#tool nuget:?package=Aore.Logger&version=1.2.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
Aore.Logger 核心包
线程安全的 .NET 日志组件核心库：一个全局单例
Logger，把日志同步分发到一个或多个ILogTarget输出目标（内置文件日志，数据库日志由扩展包提供）。
1. 作用与目的
- 统一日志入口：业务代码只面向
Logger.Instance，不关心日志落到哪里； - 文件日志开箱即用：按天命名 + 按大小轮转 + 可选按保留天数自动清理；
- 数据库日志可选扩展：通过反射工厂按需加载 SQLite / Oracle / MySQL / SQL Server / PostgreSQL 扩展包，核心包零数据库依赖；
- 可扩展：实现
ILogTarget即可接入任何自定义输出（消息队列、Elasticsearch 等）； - 跨平台：netstandard2.0 / net462 / net472 / net48 / net8.0 多目标，兼容 MVC、WebApi、Console、桌面应用与后台服务。
2. 安装
dotnet add package Aore.Logger
唯一依赖：Newtonsoft.Json 13.0.3（仅用于 JSON 配置文件读写）。
3. 快速上手
using Aore.Logger;
// 1. 初始化（进程内一次；可重复调用以热更新配置）
Logger.Instance.Configure(new LoggerConfig
{
LogDirectory = "Logs", // 日志目录（相对路径基于程序运行目录）
MaxFileSizeInBytes = 10 * 1024 * 1024,
IsClearingExecuted = true, // 启用按天保留清理
RetentionDays = 7,
MinLogLevel = LogLevel.DEBUG // null = 记录全部
});
// 2. 记日志
Logger.Instance.Info("服务启动完成");
Logger.Instance.Error("处理订单失败", ex); // 消息 + 异常
Logger.Instance.Log(LogLevel.WARNING, "磁盘剩余空间不足");
默认写入 Logs/yyyyMMdd.log（UTF-8），每行格式：
2026-09-25 10:30:00.123 [INFO] [Main:42] 服务启动完成
使用 JSON 配置文件
// 从任意路径加载（键为 camelCase）
var config = LoggerConfigLoader.LoadFromJson("logger.config.json");
Logger.Instance.Configure(config);
// 生成默认配置文件（程序运行目录下 logger.config.json）
LoggerConfigLoader.CreateDefaultConfig();
JSON 说明：枚举按声明顺序序列化为数字（见下文陷阱）；SaveToJson 先写临时文件再原子替换，且显式写出 null 键（保证数据库日志"列名 = null 表示不映射"语义在往返中不丢失）。
4. Logger API 一览
| 成员 | 说明 |
|---|---|
Logger.Instance |
全局单例（Lazy 惰性创建） |
Configure(LoggerConfig) |
重建目标列表（原子替换旧列表并释放被替换的旧目标）；返回 this 支持链式调用 |
AddTarget(ILogTarget) |
追加自定义目标（Configure 只支持"文件 + 1 个数据库"，多目标用此方法） |
Log(LogLevel, string) / (LogLevel, Exception) / (LogLevel, string, Exception) |
通用记录 |
Info / Warning / Error / Debug / Trace / Fatal |
按级别的快捷方法，各自有上述 3 种重载 |
AddLog(...) |
兼容旧版，等价于 Log(...) |
调用方信息（方法名 / 源文件 / 行号）通过 [CallerMemberName] 等特性自动捕获，无需手动传。
5. 日志级别：严重度 vs 声明顺序（重要陷阱）
严重度顺序为 TRACE < DEBUG < INFO < WARNING < ERROR < FATAL，MinLogLevel 按此过滤。
但 LogLevel 枚举的声明顺序是 INFO=0, WARNING=1, ERROR=2, DEBUG=3, TRACE=4, FATAL=5，JSON 配置中枚举是数字：
{ "minLogLevel": 0 }
minLogLevel: 0 = INFO（声明顺序第一个），不是 TRACE。建议代码里直接写 MinLogLevel = LogLevel.DEBUG，JSON 里核对声明顺序表。
6. LoggerConfig 配置项
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
LogDirectory |
string |
"Logs" |
日志目录；相对路径基于 AppDomain.BaseDirectory；含非法路径字符构造期抛 ArgumentException |
LogFileNamePattern |
string |
"{0}.log" |
{0} 会被替换为 yyyyMMdd；必须含 {0}，产物含非法文件名字符构造期抛错 |
MaxFileSizeInBytes |
int |
10MB | 单文件上限，超限轮转新文件；<= 0 构造期抛 ArgumentOutOfRangeException |
IsClearingExecuted |
bool |
false |
启用按保留天数清理过期日志文件 |
RetentionDays |
int |
7 | 保留天数，必须 > 0 |
ExecuteClearingCycle |
uint |
4 | 清理触发周期（小时），有效范围 1–24 |
EnableFileLog |
bool |
true |
是否创建文件日志目标 |
EnableDatabaseLog |
bool |
false |
是否创建数据库日志目标（需 DatabaseLogConfig 非 null 且已引用对应扩展包） |
DatabaseLogConfig |
DatabaseLogConfig? |
null |
数据库日志配置，见各扩展包 README 与 docs/数据库日志通用手册.md |
MinLogLevel |
LogLevel? |
null |
最低记录级别，null = 全部记录 |
EscapeNewLines |
bool |
false |
把消息/异常中的 \r \n \t 转义为可见字符，防日志注入伪造日志行 |
IncludeSourceFilePath |
bool |
false |
在成员名与行号之后追加调用方源文件路径 |
7. 文件日志行为细节
- 按天切换：文件名含当天日期，跨天自动切到新文件；
- 按大小轮转：单文件超限后写
{basename}_1.log、_2.log……单天上限 9999 个（超出抛LogWriteException）；序号跳过已存在文件避免覆盖； - 多进程共存：以
FileShare.ReadWrite共享写入，多进程写同一目录不会因共享冲突丢日志（行可能交错）； - 清理触发：写入时若条目小时数
% ExecuteClearingCycle == 0（如周期 4 → 0/4/8/… 点），该窗口首次写入派发后台清理，每进程每窗口最多一次；删除文件名匹配模式且日期早于RetentionDays的文件。清理依赖写入触发，进程空闲期不会执行； - 每次写入即开即关文件，无长驻句柄。
8. 线程模型与异常语义
Configure/AddTarget/ 写入全程锁串行化；锁内只做目标列表快照，磁盘 I/O 在锁外执行；- 写入是同步的（当前线程落盘）；
FileLogTarget.WriteAsync提供 fire-and-forget 异步（不保证顺序、失败被吞），核心写路径不使用它； - 单个目标写入失败被吞掉（不影响其他目标与业务线程）；直接使用目标类的
Write则抛原始异常，便于排障； Log(level, (Exception)null)抛ArgumentNullException（调用方编程错误 fail-fast）；message为 null 时统一按空串写入。
9. 注意事项
Configure可多次调用实现热更新；数据库目标创建失败时保留旧目标列表并抛出异常（带内层原因），旧配置继续工作；- 数据库日志必须引用对应扩展包，否则抛
无法创建数据库日志目标：请确保已引用 Aore.Logger.XXX 程序集； MinLogLevel对所有目标统一生效；- 日志写入失败默认静默——排查时可临时双写文件日志对照，或直接
new XxxLogTarget(...).Write(entry)暴露异常； - 日志表/文件建议与业务数据分开部署与备份。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. 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. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 is compatible. net463 was computed. net47 was computed. net471 was computed. net472 is compatible. net48 is compatible. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
.NETFramework 4.6.2
- Newtonsoft.Json (>= 13.0.3)
- System.ValueTuple (>= 4.5.0)
-
.NETFramework 4.7.2
- Newtonsoft.Json (>= 13.0.3)
-
.NETFramework 4.8
- Newtonsoft.Json (>= 13.0.3)
-
.NETStandard 2.0
- Newtonsoft.Json (>= 13.0.3)
- System.ValueTuple (>= 4.5.0)
-
net8.0
- Newtonsoft.Json (>= 13.0.3)
NuGet packages (5)
Showing the top 5 NuGet packages that depend on Aore.Logger:
| Package | Downloads |
|---|---|
|
Aore.Logger.Oracle
Oracle logging extension for Aore.Logger |
|
|
Aore.Logger.SQLite
SQLite logging extension for Aore.Logger |
|
|
Aore.Logger.Postgre
PostgreSQL logging extension for Aore.Logger |
|
|
Aore.Logger.MySql
MySql logging extension for Aore.Logger |
|
|
Aore.Logger.SqlServer
SQL Server logging extension for Aore.Logger |
GitHub repositories
This package is not used by any popular GitHub repositories.
Aore.Logger is a popular high-performance Efficient logging component for .NET