Cangming.Logs.NLog 0.1.9.1122

Prefix Reserved
dotnet add package Cangming.Logs.NLog --version 0.1.9.1122
                    
NuGet\Install-Package Cangming.Logs.NLog -Version 0.1.9.1122
                    
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="Cangming.Logs.NLog" Version="0.1.9.1122" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Cangming.Logs.NLog" Version="0.1.9.1122" />
                    
Directory.Packages.props
<PackageReference Include="Cangming.Logs.NLog" />
                    
Project file
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 Cangming.Logs.NLog --version 0.1.9.1122
                    
#r "nuget: Cangming.Logs.NLog, 0.1.9.1122"
                    
#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 Cangming.Logs.NLog@0.1.9.1122
                    
#: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=Cangming.Logs.NLog&version=0.1.9.1122
                    
Install as a Cake Addin
#tool nuget:?package=Cangming.Logs.NLog&version=0.1.9.1122
                    
Install as a Cake Tool

Cangming.Logs.NLog

日志领域的生产环境落地层(net8.0;net10.0),把 NLog 管线与 Cangming.Logs.Contracts 契约接通,并提供契约流生产者:LogEntryTarget、LogDirector(唯一映射点)、CompressingFileTarget(归档文件 Target)、Archive/(跨月压缩归档服务,0.3 由核心迁入,唯一使用者是 CompressingFileTarget)、TruncatingLayout(列级 UTF-8 字节截断布局)、PartitionFilter(分区位过滤)、SequenceTarget(序号首 Target)、NlogConfig(配置构建器)与 DefaultLogging(零配置默认管线)。UI 投递由宿主实现,库不提供 UI 包。本工程依赖 Cangming.Logs(间接覆盖 Contracts),是 NLog 与契约之间唯一的翻译层。

包版本由仓库根 Directory.Build.props 统一控制,项目内不覆盖。

快速接线(AI 阅读)

标准管线:归档落盘与契约流并行,同一份 NLog 事件既进文件也扇出给订阅者——

flowchart LR
    A["业务 LogHub/MEL"] --> B["NLog LogEventInfo"]
    B --> C["CompressingFileTarget<br/>归档 CSV + 跨月压缩"]
    B --> D["LogEntryTarget(name, service 或 factory)"]
    D -->|"LogDirector.Transform()"| E["LogEntry"]
    E --> F["ILogService.Write"]
    F --> G["订阅者:UI 集合 / 监控"]

接线代码(宿主在初始化 NLog 时执行,ILogService 实例由宿主持有;也可传延迟工厂):

var logService = new DefaultLogService();
new NlogConfig()
    .AddTargets(new TargetDescriptor(LogLevel.Trace, LogLevel.Fatal, "ContractLog",
                                     new LogEntryTarget("ContractLog", () => logService)))
    .Launch(mergeWithExisting: true);

// 面板侧订阅:谓词过滤 Warning 及以上,集合与裁剪由宿主负责
logService.Subscribe(e => e.Level >= LogSeverity.Warning,
                     entry => myBoundCollection.Add(entry));

默认管线(DefaultLogging)

宿主不想自己拼列与 Target 时,一次调用装配零配置管线:

using Cangming.Logs.NLog;
using Microsoft.Extensions.Logging;

// 宿主自备 NLog.Extensions.Logging;工厂由宿主持有并负责释放
var factory = LoggerFactory.Create(b => b.AddNLog());

// 装配完成后 LogHub 已发布;返回值是实际使用的日志目录,可直接喂给 SupportBundle
string directory = DefaultLogging.Initialize("Mercury", factory, new LogDefaultOptions(RetainDays: 7));

Initialize 依次做五件事:解析目录(显式 Directory 优先,否则 %LocalAppData%\<application>\logs,主目录不可建时回退到临时目录下的同名路径并只写一行 Console.Error)、按 MaxTotalBytes 删除最旧的 *.csv 与 *.zip、装配序号 Target 与 CSV Target(四列 time/level/logger/message,异步写入,EnableConsole 为 true 时追加彩色控制台)、以 mergeWithExisting: false 整体替换全局 NLog 配置、最后把宿主工厂发布给 LogHub。

本工程只依赖 NLog 而不依赖桥包,因此传入的工厂必须已挂 NLog provider(宿主自备 AddNLog());目录创建与写盘失败都不向上抛,代价是目录彻底不可建时日志静默丢弃,所以调用方要把返回目录与自检快照一并记录。

DefaultLogging.Initialize、NlogConfig.BuildCsvFileTarget 与 TruncatingLayout 构造函数都标了 [RequiresUnreferencedCode]:列布局文本经 Layout.FromString 解析,裁剪后可能丢失渲染器的反射元数据,因此三者只能在装配期调用,AOT/裁剪应用按该标注自行声明。

各类型职责与边界

类型 职责 不做什么
LogEntryTarget : Target LogEventInfo → Transform → ILogService.Write;可直接注入服务,也可传 Func<ILogService>:首次成功求值后缓存,失败/返回 null 不冒泡并重试;写不抛出,异常入 NLog InternalLogger 不自建队列(异步由 TargetDescriptor.NeedAsync 套 AsyncTargetWrapper);不能经 nlog.config XML 声明(构造需注入服务或工厂)
LogDirector.Transform 唯一映射点:级别按 NLog 序归一;Exception 仅 Warning 及以上携带;读 cangming.partition / cangming.route / cangming.seq,成功消费的 partition/route 剥离,回退键与宿主键保留;Properties 无剩余键则 null 不猜测分区归属;不计数、不读 PartitionRegistry;不改写时间戳口径
CompressingFileTarget : FileTarget 归档落盘 + 跨月压缩(经 ArchiveCompressionService),Metrics 暴露压缩指标 不负责契约流
NlogConfig Target 构建器与注册(AddTargets/Launch)、显式 CsvFileTargetOptions 工厂 不预设契约流接线(宿主自行决定是否注册 LogEntryTarget)
PartitionFilter 读 cangming.partition 的 ulong 与构造位做位与;命中 Log,缺失/类型错/不命中 Ignore 并计数 不解析分区名,不替宿主决定文件
SequenceTarget 同步首 Target,写 cangming.seq;已有序号不覆盖 不写 session、不做 route.fallback、不写文件
TruncatingLayout : Layout 按 UTF-8 字节预算截断内层布局的渲染结果:构造 TruncatingLayout(string layoutText, int maxBytes, string? marker = null) 只收布局文本,内部经 Layout.FromString 建内层;标记字节数计入预算,null 标记取 [...truncated](14 字节)、空串表示硬截断;截断按码点边界回退,静态 Truncate(string? text, int maxBytes, string? marker) 供不经过布局的调用点直接用;TruncatedCount 与 RenderFailureCount 用 Interlocked 维护 不接受已构造的 Layout 实例(NLog 6.2.2 的 Layout.Initialize 经内部接口实现、外部不可调,传入带初始化状态的布局会静默丢表头);渲染异常折算空串并计数,不向写日志方抛出
CsvFileTargetOptions / CsvColumnSpec CSV 的显式选项与列定义:表头、引号、分隔符、BOM、归档参数,以及列级 MaxBytes/TruncateMarker 不内置产品列、保留期与根目录;列级预算含标记字节,非正预算或标记超预算在构建期抛异常

LogEntryTarget 暴露实例 Metrics 快照(名称与四项计数),静态汇总仍保留;两个回退键首次出现各写一条 InternalLogger.Warn。

CSV 选项与列级截断

四个新选项都是 init 属性而非位置参数,旧构造与旧二进制都能继续用;默认值刻意对齐改动前文件的实际输出,因此升级不会给文件多一行表头,也不会丢 BOM:

选项 默认 落到哪里 为什么是这个默认
WithHeader true CsvLayout.WithHeader 改动前 BuildCsvFileTarget 没碰 CsvLayout 的默认值,文件本来就有表头;去掉表头必须显式 false
Quoting CsvQuotingMode.Auto CsvLayout.Quoting 与 NLog 默认一致:只在内容含分隔符或引号时才加引号,All 恒加、Nothing 完全不转义
Delimiter CsvColumnDelimiterMode.Auto CsvLayout.Delimiter 与 NLog 默认一致;Auto 按当前区域设置选逗号或分号,跨机器部署时建议显式给 Comma/Semicolon
WriteBom true CompressingFileTarget.WriteBom 改动前这里是硬编码 true,默认保留 BOM 才能让升级前后的文件逐字节一致

Delimiter 接收 CsvColumnDelimiterMode 的全部取值,但 Custom 要靠 CsvLayout.CustomColumnDelimiter 给出分隔字符串,选项层没有暴露该值,因此本工厂能生效的只有 Auto/Comma/Semicolon/Tab/Pipe/Space 这几种固定模式。

列级截断只对配了 MaxBytes 的列生效,其余列的布局文本原样交给 CsvColumn:

成员 语义
CsvColumnSpec.MaxBytes 列内容的 UTF-8 字节预算,null 不截断;预算包含截断标记自身,因此 maxBytes <= 0 与标记超预算都在 BuildCsvFileTarget 构建期抛异常,不等写第一条日志才暴露
CsvColumnSpec.TruncateMarker 截断标记,null 取 [...truncated],空串表示硬截断;与预算的关系由 TruncatingLayout 判定,标记字节数大于预算没有合法结果

两类构建期异常的消息都以 列 '<name>' 开头并保留原参数名,因为一份 options 通常同时配十几列,不点名就只能二分定位:

using Cangming.Logs.NLog;
using NLog.Layouts;

var options = new CsvFileTargetOptions(
    @"D:\Logs",
    [
        new CsvColumnSpec("time", "${date:format=yyyy-MM-dd HH\\:mm\\:ss.fff}"),
        new CsvColumnSpec("level", "${level}"),
        new CsvColumnSpec("logger", "${logger}") { MaxBytes = 128 },
        new CsvColumnSpec("message", "${message}") { MaxBytes = 8192, TruncateMarker = "…" },
    ],
    FileNamePattern: "app-${shortdate}.csv",
    NeedAsync: true)
{
    Delimiter = CsvColumnDelimiterMode.Comma,
};

var descriptor = NlogConfig.BuildCsvFileTarget("AppMain", options);

截断按 UTF-8 码点边界回退,不会切出半个汉字或半个代理对,代价是同一份配置对中文与 ASCII 的可见长度不同:MaxBytes 按字节计,需要按字符数封顶时由调用方先换算成字节预算,库不做字符维度的限制。

异步包装回调(ConfigureAsyncWrapper)

TargetDescriptor 仍是十个位置参数的记录,回调以 init 属性追加,旧构造签名与旧二进制不变;要观测异步队列的丢弃,就在回调里订阅 LogEventDropped:

using Cangming.Logs.NLog;

long dropped = 0;                                   // 实际代码放在宿主字段或统计对象里

var csv = NlogConfig.BuildCsvFileTarget("AppMain", options);   // options 见上一节,NeedAsync 为 true

new NlogConfig()
    .AddTargets(csv with
    {
        ConfigureAsyncWrapper = wrapper =>
        {
            wrapper.LogEventDropped += (_, args) => Interlocked.Increment(ref dropped);
        },
    })
    .Launch();
约束 内容
调用时刻 AddTargets 先写 QueueLimit、OverflowAction、BatchSize,再调回调,最后才 AddTarget;回调读到的是描述符给出的最终值,订阅也在包装器进入配置之前完成
线程 LogEventDropped 在写日志线程上同步触发,处理器只许做 Interlocked 一类计数,不得阻塞、不得再写日志;要落盘只能把 LogEventDroppedEventArgs.DroppedLogEventInfo 交给别的线程
触发条件 只在 OverflowAction 为 Discard 时触发;Block 与 Grow 下队列不丢事件,处理器永远收不到调用
异常 回调抛出的异常由 AddTargets 原样上抛,失败的 Target 不登记、同名描述符可重试;这是有意的配置期错误,不要吞掉
非异步 NeedAsync=false 不创建包装器,回调不执行

效率语义(AI 阅读须知)

  • 热路径零堆分配:Transform 产出 readonly record struct LogEntry(栈复制),面板集合存储即 struct 本体,无第二次转换;Properties 空时为 null,不 new 字典。
  • NLog 异步:需要异步写契约流时经 TargetDescriptor.NeedAsync 包裹,本层不自建队列。

同族项目

项目 角色
Cangming.Logs.Contracts 契约(本工程是它的生产环境落地)
Cangming.Logs 默认实现 DefaultLogService + LogHub 门面 + 路由装饰器(本工程的 ProjectReference 上游,Archive/ 已迁到本工程)
Cangming.Logs.xUnit 测试环境落地(与本工程平行,互不依赖)
Product Compatible and additional computed target framework versions.
.NET 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 is compatible.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.9.1122 0 11/22/2026
0.1.8.1117 82 11/17/2026
0.1.7.1116 85 11/16/2026
0.1.6.1109 94 11/9/2026
0.1.5.1105 102 11/5/2026
0.1.4.1105 96 11/5/2026
0.1.3.1102 106 11/2/2026
0.1.2.1029 105 10/29/2026
0.1.1.1028 106 10/28/2026

见仓库根 CHANGELOG.md