NLog.WPF 1.3.0

NLog.WPF

English | 中文

English

An extension to NLog that provides ready-to-use WPF controls for displaying live NLog output inside your application. Instead of opening a separate console or tailing a log file, you drop one of these controls into a window and every log your app writes shows up there in real time — colored by severity, automatically trimmed, and updated without freezing the UI. Heavily inspired by NLog.Windows.Forms and this blog post.

Controls

The package ships two controls. Both attach themselves to the configured NLog.WPF target and render every log event as it arrives — pick whichever fits your UI.

NlogListView

A structured, grid-style log viewer. Each log event becomes one row split into five columns — Time, Logger, Level, Message, Exception — so you can scan and compare fields at a glance. Rows are colored by severity (warnings in yellow, errors in red), the full message is shown as a tooltip on hover, and column widths are individually configurable (set a width to 0 to hide a column). It keeps the newest MaxRowCount rows and can auto-scroll to the latest entry.

Best when you want to inspect individual log fields — filter your eye by level, see which logger emitted what, or spot exceptions in their own column.

NlogRichTextBox

A continuous, console-style text log. Each event is appended as a single line yyyy-MM-dd HH:mm:ss.fff [Level] message, with the line colored by severity. It supports a light/dark foreground via IsLightTheme, a built-in ClearCommand you can bind straight from XAML, and it replays logs that were emitted before the control was created (see Pre-subscription caching).

Best when you want a lightweight, scrolling stream that reads like a terminal — minimal chrome, just the messages flowing by.

Both controls receive log events on NLog's worker threads, queue them, and flush to the UI on a timer (FlushIntervalMs) — so a burst of thousands of logs is coalesced into a single UI update and won't freeze the application.

Install

dotnet add package NLog.WPF

How to use

1. Add the control to your Window

Declare the namespace:

xmlns:nlog="clr-namespace:NLog.WPF;assembly=NLog.WPF"

Then add either control:

<nlog:NlogListView x:Name="logCtrl"
                   TimeWidth="auto" LoggerNameWidth="0" LevelWidth="auto"
                   ExceptionWidth="auto" MessageWidth="auto" />

or

<nlog:NlogRichTextBox x:Name="logCtrl1" />

Clear the NlogRichTextBox from XAML via its built-in command:

<Button Content="ClearLog"
        CommandTarget="{Binding ElementName=logCtrl1}"
        Command="{x:Static nlog:NlogRichTextBox.ClearCommand}" />

2. Register the target in nlog.config

<extensions>
  <add assembly="NLog.WPF" />
</extensions>
<targets>
  <target xsi:type="NLog.WPF" name="ctrl" />
</targets>
<rules>
  <logger name="*" minlevel="Trace" writeTo="ctrl" />
</rules>

The control automatically discovers every NLog.WPF target in the active configuration and subscribes to it — no extra wiring code is required.

Properties

NlogListView

Methods: Clear(), ScrollToFirst(), ScrollToLast(). Event: ItemAdded.

NlogRichTextBox

Command: NlogRichTextBox.ClearCommand. Method: ClearMsg(). Event: ItemAdded.

Hiding a message from NlogRichTextBox

NlogRichTextBox skips a log entry when its first message parameter is true. Pass true as the first argument to keep an entry out of the RichTextBox view (it still reaches other targets such as files):

logger.Debug("internal-only detail {hidden}", true);

Pre-subscription caching

If logs are emitted before any control exists, the target buffers them (bounded by NlogViewerTarget.MaxCachedLogs, default 1000; oldest dropped when exceeded). NlogRichTextBox replays this buffer once when it loads via NlogViewerTarget.DrainCachedLogs(), which also clears the buffer. NlogListView does not replay the cache.

Also available

An Avalonia port (NLog.Avalonia, control NlogTextBox) lives in the same repository for cross-platform apps.

Changelog

1.3.0

• perf: controls now queue log events and flush them on a DispatcherTimer (default 150ms) instead of dispatching one UI update per event — bursts of logs no longer freeze the UI. New FlushIntervalMs property on both controls.
• fix: NlogRichTextBox now trims the oldest lines past MaxRowCount (previously it cleared the entire view) and colors each line correctly per level.
• fix: NlogViewerTarget log buffering is now thread-safe and bounded by MaxCachedLogs (default 1000).
• breaking: the NlogViewerTarget.CachedLogs static field has been removed; use NlogViewerTarget.DrainCachedLogs() instead.

1.2.6

• fix: constructor display failed.
• fix: Parameters[0] is true ⇒ do not show log message.

1.2.5

• feat: fixed some known issues.

1.2.4

• feat: add IsLightTheme property.
• feat: add IsShowLogMessage function.

Publishing the package

dotnet nuget push <packageName> --api-key <apikey> --source https://api.nuget.org/v3/index.json

中文

NLog 的扩展,提供开箱即用的 WPF 控件,用于在应用内实时显示 NLog 日志。不用再单独开控制台或盯着日志文件,只要把控件放进窗口,应用写出的每一条日志就会实时显示在上面 —— 按级别着色、自动裁剪旧日志、并且刷新时不卡 UI。灵感来自 NLog.Windows.Forms 和 这篇博客。

控件

包内提供两个控件。它们都会自动挂接到配置好的 NLog.WPF target,并实时渲染每一条到达的日志事件 —— 按你的界面需要任选其一。

NlogListView

结构化的表格式日志查看器。每条日志是一行,拆成五列 —— 时间、Logger、级别、消息、异常 —— 方便一眼扫读和对比各字段。行按级别着色(警告黄色、错误红色),鼠标悬停时以 Tooltip 显示完整消息,各列宽度可单独配置(宽度设为 0 即隐藏该列)。它只保留最新的 MaxRowCount 行,并可自动滚动到最新一条。

适合需要按字段查看日志的场景 —— 按级别筛选视线、看清是哪个 logger 输出的、或在独立的一列里发现异常。

NlogRichTextBox

连续的、类控制台的文本日志。每条事件以 yyyy-MM-dd HH:mm:ss.fff [级别] 消息 的格式追加为一行,并按级别给整行着色。它支持通过 IsLightTheme 切换浅/深色前景、内置可直接在 XAML 中绑定的 ClearCommand,还会回放控件创建之前就产生的日志(见 订阅前的日志缓存)。

适合需要一条轻量滚动日志流的场景 —— 像终端一样,没有多余装饰,消息一条条流过。

两个控件都在 NLog 的工作线程上接收日志事件并入队,再由定时器(FlushIntervalMs)统一刷新到 UI —— 因此突发的成千上万条日志会被合并为一次 UI 更新,不会卡死界面。

安装

dotnet add package NLog.WPF

使用方法

1. 在窗口中添加控件

声明命名空间:

xmlns:nlog="clr-namespace:NLog.WPF;assembly=NLog.WPF"

然后添加任一控件:

<nlog:NlogListView x:Name="logCtrl"
                   TimeWidth="auto" LoggerNameWidth="0" LevelWidth="auto"
                   ExceptionWidth="auto" MessageWidth="auto" />

或

<nlog:NlogRichTextBox x:Name="logCtrl1" />

通过内置命令在 XAML 中清空 NlogRichTextBox:

<Button Content="ClearLog"
        CommandTarget="{Binding ElementName=logCtrl1}"
        Command="{x:Static nlog:NlogRichTextBox.ClearCommand}" />

2. 在 nlog.config 中注册 target

<extensions>
  <add assembly="NLog.WPF" />
</extensions>
<targets>
  <target xsi:type="NLog.WPF" name="ctrl" />
</targets>
<rules>
  <logger name="*" minlevel="Trace" writeTo="ctrl" />
</rules>

控件会自动发现当前配置中所有 NLog.WPF target 并订阅,无需额外的连接代码。

属性

NlogListView

方法:Clear()、ScrollToFirst()、ScrollToLast()。事件:ItemAdded。

NlogRichTextBox

命令:NlogRichTextBox.ClearCommand。方法:ClearMsg()。事件:ItemAdded。

让某条日志不显示在 NlogRichTextBox

当一条日志的第一个消息参数为 true 时,NlogRichTextBox 会跳过该条。把 true 作为第一个参数传入,即可让这条日志不出现在 RichTextBox 视图里(它仍会写入文件等其他 target):

logger.Debug("仅内部使用的明细 {hidden}", true);

订阅前的日志缓存

如果在任何控件创建之前就产生了日志,target 会先缓存它们(由 NlogViewerTarget.MaxCachedLogs 限制,默认 1000,超出丢弃最旧)。NlogRichTextBox 在加载时通过 NlogViewerTarget.DrainCachedLogs() 一次性回放这些缓存并清空缓冲区。NlogListView 不会回放缓存。

同时提供

仓库内还有一个 Avalonia 版本(NLog.Avalonia,控件 NlogTextBox),用于跨平台应用。

更新日志

1.3.0

• perf: 控件改为将日志事件入队、由 DispatcherTimer(默认 150ms)统一刷新,不再每条事件触发一次 UI 更新 —— 高频日志不再卡死界面。两个控件新增 FlushIntervalMs 属性。
• fix: NlogRichTextBox 现在在超过 MaxRowCount 时裁剪最旧的行(此前是清空整个视图),并按级别正确地逐行着色。
• fix: NlogViewerTarget 的日志缓存现在线程安全,并由 MaxCachedLogs(默认 1000)限制大小。
• breaking: 移除了 NlogViewerTarget.CachedLogs 静态字段;请改用 NlogViewerTarget.DrainCachedLogs()。

1.2.6

• fix:构造函数显示失败。
• fix:Parameters[0] is true ⇒ 不显示该条日志消息。

1.2.5

• feat:修复了一些已知问题。

1.2.4

• feat:新增 IsLightTheme 属性。
• feat:新增 IsShowLogMessage 功能。

发布 NuGet 包

dotnet nuget push <packageName> --api-key <apikey> --source https://api.nuget.org/v3/index.json