林德熙

博客导航

Tue, 07 Apr 2026 23:02:12 +0000

本文记录我写的博客和我收集的博客

技术交流群

这是我创建技术交流群，都不是开发新手友好，都是某项技术领域的群

dotnet 职业技术学院

Skype 群： https://join.skype.com/TiYcws3RHXOO

电报群： https://t.me/dotnet_campus

这是公开可加入的群

CPF xamarin MAUI UNO 国产 UOS 开发

群: 810052083

交流国产系统开发相关，以及 MAUI 和 Avalonia 和 UNO 和 xamarin 和 Mono 在这些神奇的系统上运行的问题，以及这些神奇的系统的系统环境问题

也可以聊聊 GTK 和 X11 系列的问题

Microsoft.Maui.Graphics

群：623209342

交流使用 MAUI 的 Graphics 进行渲染的技术，包括自绘平台以及图形绘制相关技术

WPF SharpDx Vortice

群：622808968

交流使用 SharpDx 或 Vortice 调用 DirectX 底层的技术群，包括 D2D 和图形绘制相关技术

dotnet UNO

群：724181515

专门用来交流 UnoPlatform/Uno 开发技术的群

SkiaSharp

群: 788018852

交流 SkiaSharp 相关技术

OpenTK

群：789025426

交流使用 OpenTK 调用渲染层的群

OpenXML Office 开发

群：688921958

交流 Office 开发和 OpenXML 相关技术的群，此群非新手群

Windows 定制

群：729474199

聊 OEM 定制开发，以及各种奇奇怪怪的 Win32 API 的使用方法。非 Windows 使用方法群，非编程新手友好群

也可以吐槽微软的系统的各种问题

Roslyn

群：629370288

聊聊 Roslyn 和编译定制，预编译，定制构建过程的群

SemanticKernel

群: 623349574

聊聊 AI 应用

UWP WPF 开发交流群

群：XXXXXXXXXX

本群非新手群，仅提供邀请加入。纯技术群

其他博客发布平台

以下平台都是我的博客发布平台

主站：/
- 使用 GitHub Page 搭建的博客
博客园： https://www.cnblogs.com/lindexi
- 作为主站的备份
- 靠自动同步更新
- 图片有些是 http 的，可能会看不到图片
皮卡帮忙搭建的博客（国内）：https://lindexi-blog.jgrass.cc/
- 作为主站的同步
- 速度嘎嘎快
- 不定时同步
皮卡帮忙搭建的博客（国外）：https://lindexi-blog.vercel.app/
- 作为主站的同步
- 不定时同步
GitBook ： https://uwp.gitbook.io/
- 作为主站的备份
- 靠自动同步更新
- 国内访问速度较差
腾讯云：https://cloud.tencent.com/developer/column/71201
- 靠自动同步更新
- 同步过来的图片自动转 https 链接，有些图片会丢
CSDN ：https://blog.csdn.net/lindexi_gd/
- 不推荐，大量博客都需要 vip 才能看，博客也很久同步不上去了
51CTO：https://blog.51cto.com/u_11283245
- 靠自动同步更新
- 作为备份的备份
- 基本没维护
medium：https://medium.com/@lindexi_gd
- 基本只发英文博客

语言

C# 高级面试题

C# 很少人知道的科技

dotnet C# 布尔可以是 true 或 false 外的值

dotnet C# 基础为什么 GetHashCode 推荐只取只读属性或字段做哈希值

dotnet C# 分享基础 for 循环的写法

dotnet C# 如何在顶级语句定义属性

C# 使用 using 关键字间接实现只读局部变量的方法

C# 里面很少人知道但很好用的 Tuple 转换

C＃ await 高级用法

C＃字符串首字符大写

dotnet C# 多次对一个对象调用构造函数会发生什么

dotnet C# 只创建对象不调用构造函数方法

dotnet C# 主构造函数带来的虚属性优势

dotnet C# 如果在构造函数抛出异常析构函数是否会执行

dotnet C# 在 finally 抛异常会发生什么

dotnet C# 如果在构造函数抛出异常是否可以拿到对象赋值的变量

为何 C# 的指针不是可空类型

C# dotnet 在内存中的 double 的 NAN 和正负无穷二进制是如何存

dotnet C# 警惕结构体加等事件

C＃ await 高级用法

C＃局部函数与事件

C＃ 6.0 字符串 String Interpolation

C# 7.0

C# 7.0 使用下划线忽略使用的变量

dotnet 修复 C# 8.0 语法编译失败

C# 在 8.0 对比 string 和 string? 的类型

C# const 和 readonly 有什么区别

C# 强转空会不会出现异常

dotnet C# 警惕可空结构体的方法内部赋值无效

dotnet C# 使用 using 关键字释放 IDisposable 的结构体是否会装箱

dotnet C# 给结构体字段赋值非线程安全

dotnet C# 结构体出方法弹栈之后的行为

使用 LatestCSharpFeatures 库让旧版本 dotnet 框架项目使用新 C# 语法

dotnet

考古 dotnet 的不同版本

dotnet 运行时获取某类型的对象占用内存大小

C# 8.0 文件长度 Bytes 字节转 KB 等单位字符串

dotnet 如何更改应用在任务管理器显示的进程名 AssemblyTitle 的值

dotnet 将控制台 Console.WriteLine 内容输出到文件

dotnet 使用 FileAccess 与 OpenOrCreate 对文件访问权限的影响

dotnet 控制台读写 Sqlite 提示 no such table 找不到文件

C# dotnet 编写 curl 的用户名和密码逻辑

dotnet C# 代码获取系统日志

dotnet 使用 TypeNameFormatter 库格式化输出反射泛型类型

dotnet 忽略输出文件夹的正则表达式

dotnet C# 调用委托的 GetInvocationList 的对象分配

dotnet 使用 FormatterServices 的 GetUninitializedObject 方法在丢失 DLL 情况下能否执行

dotnet C# 全局 Windows 鼠标钩子

dotnet C# 反射扫描程序集所有类型会不会触发类型静态构造函数

dotnet C# 图片等比限制最大和最小大小缩放算法

dotnet 使用 ConfigureAwait.Fody 库设置默认的 await 同步上下文切换配置

Windows Community Toolkit 3.0 新功能

dotnet 为大型应用接入 ApplicationStartupManager 启动流程框架

C# 获取 PC 序列号

C# 大端小端转换

dotnet C# 如何使用 MemoryFailPoint 检查是否有足够的内存资源来执行操作

dotnet C# 获取当前设备可移动磁盘

dotnet 写一个支持层层继承属性的对象

让 dotnet 命令行输出作为英文的方法

.NET 官方图标

MSIL 静态类在 IL 定义上和非静态类的差别

dotnet 简单写一个 pdb 符号文件下载器

代码优化

教你如何编写好的代码，如何对代码进行优化，这是入门级的博客

dotnet 代码优化聊聊逻辑圈复杂度

团队协作下，要求代码质量，离不开代码审查，以下是一些代码审查套路

dotnet 一些代码审查套路

WPF

记录 WPF 开发的杂烩： WPF 开发

入门的教程：什么是WPF - The complete WPF tutorial

WPF Application Compatibility switches list

WPF 通过 Switch.MS.Internal.EnableWeakEventMemoryImprovements 开关开启弱事件内存优化

WPF 使用 MAUI 的自绘制逻辑博客园

WPF 切换主题使用 luna 复古版本

WPF 关于将 ManipulationDeltaEventArgs 的 Manipulators 属性返回值修改为 ReadOnlyCollection 类型的提议

dotnetCampus.UITest.WPF 一个支持中文用例的界面单元测试框架

wpf 单例

WPF 旋转太极

WPF 引用第三方库的控件在设计器加上设计时数据和属性

WPF 制作一个占用文件的测试工具

WPF 使用 Microsoft.Toolkit.Wpf.UI.Controls 的 InkCanvas 做高性能笔迹应用

WPF 在后台代码定义 ResourceDictionary 资源字典

WPF 启动屏幕键盘

WPF 附加属性提供某个元素拥有拖拽窗口的功能

WPF 绑定密码

wpf 绑定 TextLength

WPF 修复 ContextMenu 在开启 PerMonitorV2 后所用 DPI 错误

WPF 使用RPC调用其他进程

WPF 从零开始开发 dotnet Remoting 程序

记从 dotnet framework 4.8 升级到 4.8.1 时运行的 dotnet remoting 程序出现空异常

WPF 绑定继承的样式提示只能根据带有基类型 IFrameworkInputElement 的目标类型的 Style 样式

为何 WPF 对 vcruntime140 有引用

WPF 画布工具栏的可扩展设计

WPF 给任意控件通过按下移动抬起封装点击事件

WPF 使用 Microsoft.Toolkit.Wpf.UI.Controls 的 InkCanvas 时加上背景色和按钮方法

WPF 鼠标光标大全

WPF 如何找到资源文件路径包含 # 号的文件

dotnet C# 获取一个可用的端口的方法

WPF 的 DefaultEventAttribute 有什么作用

dotnet 通过 Elmish.WPF 使用 F# 编写 WPF 应用

WPF 列表控件数据源绑定多个数据集合方法

WPF 使用 ManipulationProcessor2D 纯数学计算方式提供多点漫游元素功能

WPF 使用 XmlDataProvider 提供数据

WPF 按钮 Button 的 IsEnabled 属性对 WindowChrome 的 IsHitTestVisibleInChrome 的影响

WPF 如何在静态资源定义字体大小

WPF 给应用程序添加水印

dotnet 使用 WpfAnalyzers 辅助分析 WPF 应用代码缺陷

WPF 列表右键菜单比较符合 MVVM 的命令绑定方法

WPF 下拉框选项做鼠标 Hover 预览效果

WPF 给 Grid 的辅助方法添加行列名称绑定

WPF 给类库设置设计时使用的资源字典

WPF 形状的 StrokeThickness 属性对边框的影响

WPF 获取进程启动到当前现在的时间

WPF 将 docx 的 Word 文件转换为 FlowDocument 显示

WPF 为何不要重写默认 string 字符串的 DataTemplate 数据模版

WPF 设置元素为 Collapsed 是否会创建此元素

WPF 从键盘事件 KeyEventArgs 里获取 Scan Code 的方法

wpf 绑定 DataGridTextColumn

wpf DoEvents

WPF 运行时迁移 EF Core 数据库

WPF 轻量级 MVVM 框架入门 2.1.2

WPF 绑定命令在 MVVM 的 CanExecute 和 Execute 在按钮点击都没触发可能的原因

WPF 如何在绑定失败异常

WPF 元素裁剪 Clip 属性

WPF 托盘显示

WPF 如何判断一个控件在滚动条的里面是用户可见

WPF 绑定的默认模式

WPF 封装 dotnet remoting 调用其他进程

WPF 列表自动换行

WPF 如何建立自己的 3d gis 程序

WPF 在绑定表达式添加计算

WPF 修改 ItemContainerStyle 鼠标移动到未选中项效果和选中项背景

WPF 获取下载内容长度

WPF 拖动滚动

WPF 自定义 TextBoxView 的 Margin 大小

WPF 使用 WNetUseConnection 连接 SMB 网络资源

WPF 资源冻结

WPF 异常 NativeWPFDLLLoader.LoadNativeWPFDLL

WPF 只允许打开一个实例

WPF 使用 Pandoc 把 Markdown 转 Docx

WPF 使用 Edge 浏览器

dotnet 简单方法在一个进程内同时跑起 WPF 和 ASP.NET Core 框架

WPF 引用 ASP.NET Core 的 AOT 版本

WPF 从 RGB 字符串转纯色颜色画刷的方法

WPF 性能测试

WPF 启动性能优化在 EnsureHandle 之前设置 WindowStyle 提升性能

WPF 应用开发

这是记录我用 WPF 开发的一些应用

WPF 制作一个加密文件夹应用

WPF 简单实现一个支持删除自身的应用

WPF 尝试使用 WinML 做一个简单的手写数字识别应用

WPF 做一个超级简单的 1024 数字接龙游戏

WPF 使用快捷键方式制作简易的 Word 上的 Latex 输入法

dotnet C# 做一个压缩包和解压缩出来的文件夹内容对比工具

WPF 触摸相关

我写了很多 WPF 触摸相关的博客，请参阅：

WPF 触摸相关

WPF dotnet core 如何开启 Pointer 消息的支持

WPF 如何确定应用程序开启了 Pointer 触摸消息的支持

dotnet 读 WPF 源代码笔记从 WM_POINTER 消息到 Touch 事件

WPF 开启 ScrollViewer 的触摸滚动

WPF 通过 WindowsAppSDK 使用 WinRT 的手写识别功能

WPF 触摸下如何给 StylusPointCollection 添加点

WPF 通过 GetMessageExtraInfo 方法获取当前收到的鼠标消息是否由触摸转换过来

WPF 记一个特别简单的点集滤波平滑方法

WPF 从裸 Win 32 的 WM_Pointer 消息获取触摸点绘制笔迹

WPF 通过 GetRawPointerDeviceData 从 WM_POINTER 消息触摸裸数据

WPF 已知问题监听 WMI 事件导致触摸失效

WPF Main thread gets a deadlock when stylus input thread is waiting for the window to close

WPF shows that some windows in multithreading will be locked in the PenThreadWorker constructor when the application starts

WPF will break when an exception be throw in the StylusPlugIn

控件

WPF checkbox文字下掉

WPF popup置顶

WPF 如何给 Grid 的某一行添加背景色

WPF 让 TextBox 支持水平滚动

WPF 控件 Content 的内容不显示下划线字符串

WPF 在image控件用鼠标拖拽出矩形

WPF 使用 ItemsPanel 修改方向

WPF ListBox 的选择

WPF 解决 ListView 的滚动条不显示

自定义控件

WPF 控件继承树

WPF 自定义控件入门可重写的各个方法或属性的意义

WPF 自定义控件入门 Focusable 与焦点

WPF 手绘对称图形控件

WPF 滑动修改音量控件

【收藏】 WPF教学 WPF做出这样丝滑的动画尽然如此简单？ Magic Navigation Bar 导航栏哔哩哔哩_bilibili

控件库

WPF 使用 HandyControl 给 ListView 添加漂亮的表头效果

WPF HandyControl 已支持给任意控件通过按下移动抬起封装点击事件

WPF 用 AvalonEdit 开发简单的代码编辑器支持高亮自动提示

WPF 漂亮的现代化控件新 ModernWPF 界面库

WPF 使用基于 Chromium 内核的 Microsoft Edge 封装的 WebView2 控件

WPF 使用 MyScript 的 IInk 做手写识别

布局

WPF 布局在有限空间内让两个元素尽可能撑开的例子

WPF 测试固定尺寸且水平和垂直对齐设置 Stretch 的元素在容器内的布局行为

WPF 等距布局

WPF 什么时候 VisualTreeHelper.GetDescendantBounds 将返回无穷大

WrapPanel改进 - 老板娘的神秘商店 - 博客园

WPF 使用 TranslatePoint 换算元素之间相对坐标

XAML

XAML 给资源起个好名字用 StaticResource 起一个别名

WPF 在 XAML 写 C# 代码

WPF 通过辅助方法在 csharp 代码写出 XAML 界面效果

WPF 使用 Behavior 库辅助获取动态资源变更事件

dotnet 使用 ShowMeTheXAML 显示 WPF 的 XAML 控件内容

WPF dotnet core 的 Blend SDK Behaviors 库

xaml 添加 region

WPF 点击按钮时更改按钮样式界面效果的 XAML 实现方法

图片

WPF 从文件创建图片的方法

WPF 从 DrawingVisual 转 BitmapImage 图片

wpf 如何使用 Magick.NET 播放 gif 图片

wpf GifBitmapDecoder 解析 gif 格式

WPF 播放 gif

WPF 通过 GifBitmapDecoder 调用 WIC 解析 Gif 和进行动画播放的简单方法

WPF 创建空白图片

WPF 使用不安全代码快速从数组转 WriteableBitmap

WPF 通过 EXIF 设置和读取图片的旋转信息

WPF 通过 WriteableBitmap 实现 TAGC 低光增强效果算法

文本

WPF 文字描边

WPF 弹出 popup 里面的 TextBox 无法输入汉字

dotnet OpenXML WPF 解析实现 PPT 文本描边效果

dotnet 解析 TTF 字体文件格式

WPF 从文件加载字体

WPF 简单聊聊如何使用 DrawGlyphRun 绘制文本

WPF 测试 GlyphTypeface 的 Baseline 行为

WPF 获取本机所有字体拿到每个字符的宽度和高度

dotnet C# 使用 FreeType 读取和绘制字体

WPF 自定义文本框输入法 IME 跟随光标

文本库聊聊行首光标的行为

dotnet C# 如何正确获取藏文的字数

WPF 字体 FontStyle 的 Italic 和 Oblique 的区别

WPF 解决 SelectionTextBrush 设置无效问题

WPF How to get plain text from RichTextBox

wpf PreviewTextInput 在鼠标输入获得 \u0003

WPF 探索 Skia 的竖排文本渲染的字符高度

线程

WPF 如何跨线程重新抛出异常

WPF 设置资源字典多线程安全读写方法

WPF 简单判断主线程界面是否卡顿的方法

WPF 多线程下跨线程处理 ObservableCollection 数据

WPF 跨线程 UI 的方法

wpf 使用 Dispatcher.Invoke 冻结窗口

WPF 使用 Dispatcher 的 InvokeAsync 和 BeginInvoke 的异常处理差别

窗口

WPF 一个空的 WPF 程序有多少个窗口

WPF 内部的5个窗口之 MediaContextNotificationWindow

WPF 获取应用的所有窗口

WPF 解决弹出模态窗口关闭后，主窗口不在最前

WPF 让窗口激活作为前台最上层窗口的方法

WPF 两个 Topmost 的窗口如何设置谁在最上方

WPF 获取某个窗口的所有子窗口

WPF 设置 ShowInTaskbar 对窗口最小化的影响

WPF 制作支持点击穿透的高性能的透明背景异形窗口

Win32 使用 SetCurrentProcessExplicitAppUserModelID 关联多个进程在任务栏合并 WPF 多进程窗口

WPF 稳定的全屏化窗口方法

用 SetWindowPos 方法设置一个停止响应的窗口将卡调用方

WPF 全屏透明窗口

WPF 添加窗口消息钩子方法

WPF 在 Alt+Tab 隐藏窗口

WPF 获取全局所有窗口的创建显示事件监控窗口打开

WPF 通过 SetWindowDisplayAffinity 配置禁止对窗口进行截图或录屏

[WPF 自定义控件] 使用WindowChrome自定义Window Style - dino.c - 博客园

WPF 使用 WindowChrome，在自定义窗口标题栏的同时最大程度保留原生窗口样式（类似 UWP/Chrome） - walterlv

将 WPF 嵌入到 MFC 中，无法响应键盘输入 - J.晒太阳的猫 - 博客园

渲染

更多请看 WPF 渲染相关

WPF 如何画出1像素的线

WPF 解决 ViewBox 不显示线的问题

WPF 通过 DrawingContext DrawImage 绘制图片

WPF 基础绘图创建和加工图片

WPF 如何在 WriteableBitmap 写文字

WPF 如何给定两个点画出一条波浪线

WPF DrawingVisual

WPF 如何判断两个 LinearGradientBrush 相等

WPF 在 DrawingContext 的 push 如何使用

WPF 设置纯软件渲染

WPF 笔刷绑定不上可能的原因

WPF 调用 InvalidateVisual 不触发 OnRender 的原因

WPF 解决 Skia 因为找不到字体而绘制不出中文字符

WPF 使用 Skia 绘制 WriteableBitmap 图片

WPF 如何获取有哪些 VisualBrush 用了某个控件

dotnet 在 WPF 里显示数学 π 的颜色

WPF 更改 DrawingVisual 的 RenderOpen 用到的对象的内容将持续影响渲染效果

WPF 简单聊聊如何使用 DrawGlyphRun 绘制文本

WPF 模拟 WPFMediaKit 的 D3D 配置用来测试4k性能

WPF 使用 Direct Manipulation 的方法

WPF 使用 Composition API 做高性能渲染

WPF 渲染级别

WPF 使用 Win2d 渲染

WPF 动画性能测试应用一千个半透明矩形做动画

WPF 获取 MediaContext 的方法

WPF 设置 Aliased 的 EdgeMode 会让圆形渲染出棱角

dotnet C# Windows 桌面应用程序简单使用 DwmFlush 对齐刷新率

视频

WPF 使用 VideoDrawing 播放视频

[WPF] MediaElement播放HDR视频泛黄、颜色显示不正确应该如何解决？ - 王_先_生 - 博客园

动画

WPF 后台代码做 TranslateTransform 的动画

WPF 动画实战点击时显示圆圈淡出效果

平台调用

Win32

WPF 打开资源管理器且选中某个文件

WPF 获取屏幕某个点的颜色

WPF 修改屏幕亮度

WPF 使用 RawInput 接收裸数据

WPF 探索任务管理器的进程分组逻辑

WPF 使用 DisplayConfigGetDeviceInfo 获取显示器名的方法

WinRT

WPF 不安装 WindowsAppSDK 使用 WinRT 功能的方法

修复 WPF 安装 WindowsAppSDK 库构建失败 NETSDK1082 和 NETSDK1112 找不到 win10-arm 失败

WPF 使用 Win10 的 WinRT 自带 Windows.Media.Ocr 实现图片转文本

WPF 通过 WindowsAppSDK 使用 WinRT 的手写识别功能

UWP WinRT 使用系统自带的分词库对字符串文本进行分词

WPF 不带 TargetPlatformVersion 显示 Win10 的 Toast 通知的方法

WPF 基础 2D 图形学知识

WPF 基础 2D 图形学知识判断点是否在线段上

WPF 基础 2D 图形学知识判断点是否在任意几何内部方法

WPF 基础 2D 图形学知识求向量旋转角度

C# 判断两条直线距离

C# 已知点和向量，求距离的点

WPF 如何计算矩形内一个坐标相对另一个矩形的坐标

WPF 已知问题

WPF 已知问题窗口在屏幕外创建将不会刷新渲染

WPF 已知问题全屏透明窗口弹出子窗口会闪烁

WPF 已知问题 BitmapDecoder.Create 不支持传入 Asynchronous 的文件流

wpf VisualBrush 已知问题

WPF 已知问题 Popup 吃掉 PreviewMouseDown 事件

WPF 已知问题 Popup 失焦后导致 ListBox 无法用 MouseWheel 滚动问题和解决方法

WPF 已知问题资源字典树引用与资源寻找的坑

WPF 将 StaticResource 和 ResourceDictionary 放在一起的魔幻行为

WPF 加载诡异的字体无法布局

WPF 给 Pen 的 DashStyle 设置 0 0 的虚线数组将会让渲染线程消耗大量 CPU 资源

WPF 已知问题包含 NaN 的 Geometry 几何可能导致渲染层抛出 UCEERR_RENDERTHREADFAILURE 异常

WPF 已知问题某些设备上的应用在 WindowChromeWorker 抛出 System.OverflowException 异常

WPF 应用启动过程同时启动多个 UI 线程且访问 ContentPresenter 可能让多个 UI 线程互等

WPF 类型的构造函数执行符合指定的绑定约束的调用时引发了异常

win7 无法启动 WPF 程序 D3Dcompiler_47.dll 丢失

WPF 使用 RenderTargetBitmap 快速截图出现 COMException 提示

WPF 新建用户控件提示 Error MC3000 首个 xaml 字符不合法

WPF 在窗口的 Deactivated 使用 Mouse 的 Capture 将会让进程失去交互

WPF 将控件放入到 UserControl 里获取 HwndSource 为空的情况

WPF 解决 PathTooLongException 路径太长

WPF 设置 WS_EX_TRANSPARENT 触摸失效

WPF 解决 StylusPlugIn 点击穿透问题

WPF 已知问题开启 WM_Pointer 消息之后获取副屏触摸数据坐标偏移

WPF 警惕 StylusPlugIn 的多线程安全问题

WPF 网络 request 的 read 方法不会返回

WPF 光标初始化的时候 temp 文件夹满了无法创建

WPF 拖动时出现 Invalid FORMATETC structure

WPF Process.Start 出现 Win32Exception 异常

WPF 已知问题 InputEventArgs 的 Timestamp 属性是静态的导致事件之间相互影响

WPF Frame 的 DataContext 不能被 Page 继承

WPF DelegateCommand 出现Specified cast is not valid

WPF 使用 VisualBrush 在 4k 加 200 DPI 设备上某些文本不渲染看不见问题

记 Win8.1 某应用渲染抛出 OutOfMemoryException 异常及修复方法

WPF 界面打不开提示 System.ArithmeticException Overflow or underflow in the arithmetic operation 异常

WPF 警惕使用 Dispatcher.InvokeShutdown 方法退出应用将不触发 Application.Exit 事件

WPF 已知问题传入错误数据给到 WriteableBitmap 可能导致渲染线程锁住

WPF 已知问题 Separator 无法应用 ContextMenu 定义的默认样式

WPF 已知问题清空 CollectionView 的 SortDescriptions 可能抛出空异常

WPF 已知问题在 ObservableCollection 的 CollectionChanged 修改集合内容将让 UI 显示错误

WPF 已知问题开启 IsManipulationEnabled 之后触摸长按 RepeatButton 不会触发连续的 Click 事件

WPF 已知问题在 WIC 层处理异常图片时可能由于出现未处理异常导致进程退出

记 QEMU 虚拟磁盘设备移动文件抛异常但实际移动成功

WPF 已知问题使用 WindowChrome 在切换系统主题色时导致窗口界面偏移

其他软件导致的问题

WPF 被输入法带崩进程

WPF 全屏窗口将让 Chrome 97 视频停止播放

记微信截图导致 WPF 应用卡住窗口无法激活问题

记腾讯微信输入法导致 WPF 应用卡住窗口无法激活和显示

WPF 被灵格斯翻译官取词带崩

记 YKQQClean 导致应用程序界面窗口弹出失败

Office 已知问题 GROOVEEX.DLL 带崩进程

已知驱动问题

记因为 NVIDIA 显驱错误而让 WPF 应用启动闪退问题

WPF 的 WriteableBitmap 在 Intel 11 代 Iris Xe Graphics 核显设备上停止渲染腾讯云

WPF 的 Viewport3D 等 3D 模块在带 Intel UHD 770 设备上抛出渲染异常腾讯云

记 Intel 的 31.0.101.5186 版本驱动带崩 WPF 程序

各版本已知问题和新功能

以下的版本记录的是新功能加入的版本，以及发现问题的版本。有些问题会延续多个版本，不代表新版本就没有对应的问题，具体问题修复版本请参阅具体的博客

dotnet core 3.1

WPF 升级 .NET Core 的理由

WPF 双向绑定到非公开 set 方法属性在 NET 45 和 NET Core 行为的不同

从 dotnet core 3.0 的特性让 WPF 布局失效讨论 API 兼容

WPF 在 .NET Core 3.1.19 版本触摸笔迹偏移问题

WPF 在 .NET Core 3.1.19 版本没有跟随 DPI 缩放文本过小问题

dotnet core 3.1 将 UWP 控件嵌入到 WPF 应用收到 UIA 消息主线程卡住

dotnet 5

WPF 从 dotnet core 3 到 dotnet 5 的变更

dotnet 5 让 WPF 调用 WindowsRuntime 方法

dotnet 6

WPF 已知问题 dotnet 6 设置 InvariantGlobalization 之后将丢失默认绑定转换导致 XAML 抛出异常

WPF dotnet 6 开启 PM v2 的 DPI 感知导致触摸线程访问 UI 属性抛异常

WPF 修复引用库报错所使用的 PresentationFramework 6.0.2 高于所引用的标识为 6.0.0 程序集

dotnet 7

dotnet 7 WPF 破坏性改动按下 F3 让 DataGrid 自动排序

dotnet 7 已知问题 WPF 的 TreeView 开启虚拟化之后只显示首项

dotnet 8

dotnet 8 WPF 支持在 RDP 远程桌面状态下启用渲染硬件加速博客园

记 dotnet 8.0.4 修复的 WPF 的触摸模块安全问题

dotnet 9

dotnet 9 WPF 连字符渲染支持

dotnet 9 WPF 支持 Style 的 Setter 填充内容时可忽略 Value 标签

WPF在.NET9中的重大更新：Windows 11 主题 - mingupupup - 博客园

dotnet 9 WPF 项目禁用 IncludePackageReferencesDuringMarkupCompilation 导致源代码包 XAML 构建失败

dotnet 10

dotnet 10 已知问题构建 WPF 时提示 System.Private.Windows.GdiPlus 程序集未找到错误

dotnet 10 已知问题 WinForms 的 TargetFramework 与 System.Drawing.Common 不匹配将抛出找不到类型异常

构建发布

WPF 通过 Windows Template Studio 快速搭建项目框架和上手项目

WPF 编译为 AnyCPU 和 x86 有什么区别

WPF 通过 ReadyToRun 提升性能

WPF 基于 .NET 5 框架和 .NET 6 的 SDK 进行完全单文件发布

WPF 修复 dotnet 6 与源代码包冲突

WPF 设置 IncludePackageReferencesDuringMarkupCompilation 属性导致分析器不工作

WPF 通过 dotnet core 发布单文件时 log4net 无法使用

WPF 程序生成类库错误

WPF 项目文件不加 -windows 的引用 WPF 框架方式

使用 SatelliteResourceLanguages 减少 WPF 发布的多语言文件夹数量

SignTool 使用 SafeNet eToken 硬证书进行代码签名

打包 UWP 应用

WPF 判断当前应用被打包为 UWP 而运行

WPF 引用 UWP 控件不打包为 MSIX 分发的方法

WPF 调试

WPF 依赖属性绑定不上调试方法

WPF 如何调试 binding

WPF 调试因为对象不同而绑定失效问题

WPF 基于 WER 注册应用崩溃无响应回调和重启方法

WPF 调试获得追踪输出

WPF 判断调用方法堆栈

WPF 某个界面或控件在界面找不到看不到可能的原因

WPF 获取是哪个进程占用了文件

WPF 如何知道当前有多少个 DispatcherTimer 在运行

Windows 下的 WPF 开发调试应用程序在什么时机加载了 Dll 模块

WPF 如何在应用程序调试启动

如何保留 wpftmp.csproj 文件用于调试

读 WPF 源代码

WPF 源代码从零开始写一个 UI 框架

dotnet 读 WPF 源代码笔记布局时 Arrange 如何影响元素渲染坐标

dotnet 读 WPF 源代码笔记为什么自定义的 UserControl 用户控件不能跨程序集继承

dotnet 读 WPF 源代码笔记 WPF 是如何做到一套代码兼容多个 .NET Framework 版本

dotnet 读 WPF 源代码笔记为什么加上 BooleanBoxes 类

WPF 从最底层源代码了解 AllowsTransparency 性能差的原因

dotnet 读 WPF 源代码笔记渲染收集是如何触发

dotnet 读 WPF 源代码笔记了解 WPF 已知问题后台线程创建 WriteableBitmap 锁住主线程

dotnet 读 WPF 源代码笔记 WriteableBitmap 的渲染和更新是如何实现

WPF 从 WriteableBitmap 里获取到渲染线程使用的 IWICBitmap 对象

dotnet 读 WPF 源代码笔记提升调试效率的 NamedObject 类型

dotnet 读 WPF 源代码笔记插入触摸设备的初始化获取设备信息

dotnet 读 WPF 源代码笔记了解 WPF 已知问题用户设备上不存在 Arial 字体将导致应用闪退

dotnet 读 WPF 源代码笔记创建 SolidColorBrush 性能没有想象那么差

dotnet 读 WPF 源代码笔记默认的 Main 函数是在哪创建的

dotnet 读 WPF 源代码笔记为什么设置了SplashScreen会让Application.Current.Activated事件不触发

dotnet 读 WPF 源代码笔记 SafeMILHandleMemoryPressure 的作用

dotnet 读 WPF 源代码笔记为什么默认的笔迹触摸点的压感是 0.5 的值

dotnet 读 WPF 源代码笔记 Stroke 类可能存在的内存泄露

dotnet 读 WPF 源代码笔记 XAML 创建对象的方法

dotnet 读 WPF 源代码笔记使用 Win32 方法修改窗口的坐标和大小对窗口依赖属性的影响

dotnet 读 WPF 源代码笔记 AppDomainShutdownMonitor 的设计

dotnet 读 WPF 源代码笔记启动欢迎界面 SplashScreen 的原理

dotnet 读 WPF 源代码笔记 wpfgfx_cor3.dll 是什么文件

dotnet 读 WPF 源代码笔记 WIC 多媒体图片处理通过 WindowsCodecs.dll 实现功能

dotnet Framework 源代码 · Ink

dotnet Framework 源代码 · ScrollViewer

dotnet 读 WPF 源代码 Popup 的 StaysOpen 为 false 将会吃掉其他窗口的首次激活

dotnet 读 WPF 源代码聊聊 DispatcherTimer 的实现

dotnet 读 WPF 源代码学习使用 Microsoft.DotNet.Arcade.Sdk 处理代码里的多语言

WPF 源代码资源字典 ResourceDictionary 设置 Source 属性的逻辑

dotnet 读 WPF 源代码笔记聊聊 HwndWrapper.GetGCMemMessage 调试消息

WPF 冷知识定义依赖属性的最大数量是 65534 个

WPF UncommonField 类型是什么

WPF 框架开发 ColumnDefinition 和 RowDefinition 的代码在哪

WPF 讲讲 Microsoft.NET.Sdk.WindowsDesktop 的原理

dotnet 读 WPF 源代码笔记 ShowInTaskbar 的实现原理

文本

dotnet 读 WPF 源代码笔记简单聊聊文本布局换行逻辑

dotnet 读 WPF 源代码笔记 GlyphRun 的 DeviceFontName 的功能是什么

dotnet 读 WPF 源代码笔记渲染层是如何将字符 GlyphRun 画出来的

读 WPF 源代码了解获取 GlyphTypeface 的 CharacterToGlyphMap 的数量耗时原因

dotnet 读 WPF 源代码笔记聊聊 OpenType 定义的字体特性

WPF 框架开发

手把手教你如何构建 WPF 官方开源框架源代码

手把手教你构建 WPF 框架的私有版本

WPF 框架全构建环境虚拟机硬盘分享

WPF 最简方法使用自己定制的 WPF 框架

WPF 框架开发 WPF 的构建在哪使用到 Perl 工具

WPF 框架开发更改 API 之后让 CI 重新创建 API 兼容检查基准

WPF 框架开发加入 InternalsVisibleToAttribute 特性让其他程序集可以访问 internal 权限成员

WPF 框架开发调试和开发 System.Xaml 的独立项目方法

WPF 框架开发调试和开发 XAML 构建过程的 PresentationBuildTasks 方法

UWP

从零开始学习入门 Windows 10 应用程序 UWP 开发

win10 uwp 入门

win10 uwp 如何开始写 uwp 程序

UWP WinUI 制作一个路径矢量图标按钮样式入门

UWP 开发中，需要知道的1000个问题

UWP 和 WPF 对比

win10 uwp 选择文本转语音的机器人

win10 uwp 颜色转换

win10 uwp 手把手教你使用 asp dotnet core 做 cs 程序

win10 uwp 如何判断一个控件在滚动条的里面是用户可见

win10 uwp 列表模板选择器 win10 UWP Controls by function

win10 uwp 提示 Cannot find a Resource with the Name Key 找不到资源

win10 uwp 通过命令行脚本开启旁加载

UWP how to get the touch width

win10 uwp listView 绑定前一项

win10 uwp 字符文本转语音声音文件方法

win10 uwp 捕获后台线程异常

如何在 UWP 使用 wpf 的 Trigger

win10 uwp 从 Unity 创建

win32 嵌入第三方 UWP 应用做开放平台

win10 uwp 如何给 DropDownButton 一个很小的宽度

win10 uwp 使用 OCR 光学字符识别

win10 uwp 相机的分辨率设置方法

win10 uwp 如何修改 Flyout 的宽度或高度

win10 uwp 使用 XamlTreeDump 获取 XAML 树元素内容

UWP 写入图片 Exif 信息

win10 uwp 不显示 SplashScreen 欢迎界面的方法

win10 UWP 等级控件

win10 uwp 通知列表

win10 uwp 使用 asp dotnet core 做图床服务器客户端

win10 uwp 显示SVG

win10 uwp 求两个矩形相连的几何

win10 uwp 获取窗口的坐标和宽度高度

UWP 分享用那个图标

win10 uwp 如何使用DataTemplate

win10 uwp 打包第三方字体到应用

win10 uwp 右击浮出窗在点击位置

win10 uwp 读取保存WriteableBitmap 、BitmapImage

win10 uwp 资源字典

win10 UWP 序列化

win10 uwp 如何打包Nuget给其他人

win10 UWP 动画

win10 uwp 依赖属性

win10 uwp x:Bind 无法获得资源

win10 uwp 好看的时间选择控件

win10 uwp 读取文本GBK错误

win10 UWP 使用 MD5算法

win10 uwp 在笔迹开始书写拿到书写移动事件

win10 uwp 处理用户点击关闭按钮

win10 uwp 解决 SerialDevice.FromIdAsync 返回空

win10 uwp 未给任务 GenerateAppxPackageRecipe 的必需参数 AppxManifestXml 赋值

win10 uwp 开发 CSDN 访问量统计源代码

win10 uwp 应用放到桌面

win10 uwp 自定义标记扩展

win10 uwp 如何将像素数组转 png 文件

win10 uwp 如何自定义 RichTextBlock 右键菜单

win10 uwp 鼠标移动到图片上切换图片

win10 uwp 渲染原理 DirectComposition 渲染

win10 uwp 客户端如何发送类到 asp dotnet core 作为参数

win10 uwp 禁用 ScrollViewer 交互

win10 uwp 在 xaml 让 TextBlock 换行

win10 uwp 异步转同步

win10 uwp 自定义控件入门

win10 UWP 剪贴板 Clipboard

win10 UWP 标题栏后退

win10 uwp 验证输入自定义用户控件

win10 uwp 重启软件

win10 uwp 退出程序

win10 uwp 进度条 WaveProgressControl

win10 uwp 进度条 Marquez

win10 uwp 绘图 Line 控件使用

win10 uwp 绑定 OneWay 无法使用

win10 uwp 横向 AppBarButton

win10 uwp 按下等待按钮

win10 uwp 拖动控件

win10 uwp 打开文件管理器选择文件

win10 uwp 如何让一个集合按照需要的顺序进行排序

win10 uwp 如何在DataTemplate绑定方法

win10 uwp 如何判断一个对象被移除

win10 uwp 如何创建修改保存位图

win10 uwp dataGrid

win10 uwp Window.Current.Dispatcher中Current为null

win10 uwp App-to-app communication 应用通信

win10 uwp 调用 Microsoft.Windows.Photos_8wekyb3d8bbwe 应用

win10 UWP 全屏

win10 uwp 使用油墨输入

win10 uwp 设置 HttpClient 浏览器标识

win10 uwp 音频

win10 uwp 读写csv

win10 uwp 设置启动窗口大小获取窗口大小

win10 uwp 让焦点在点击在页面空白处时回到textbox中

win10 uwp 获得Slider拖动结束的值

win10 uwp 获取按钮鼠标左键按下

win10 uwp 获取指定的文件 AQS

win10 uwp 自定义控件 SplitViewItem

win10 uwp 网络编程

win10 uwp 绑定静态属性

win10 uwp 绑定密码

win10 uwp 简单MasterDetail

win10 uwp 活动磁贴

win10 uwp 模拟网页输入

win10 uwp 改变鼠标

win10 uwp 手动锁Bitlocker

win10 uwp 异步进度条

win10 uwp 如何让WebView标识win10手机

win10 uwp 如何让 Page 继承泛型类

win10 uwp 如何拖动一个TextBlock的文字到另一个TextBlock

win10 uwp 从StorageFile获取文件大小

win10 uwp 上传Nuget 让别人用我们的库

win10 uwp iot

win10 uwp InkCanvas控件数据绑定

win10 uwp HttpClient post错误

win10 uwp ContentDialog 点确定不关闭

win10 uwp BadgeLogo 颜色

win10 UWP 应用设置

win10 UWP 单元测试

win10 UWP MessageDialog 和 ContentDialog

win10 UWP Hmac

win 10 UWP 标签

Win10 UWP Intro to controls and events

win10 uwp 参考

win10 uwp 修改CalendarDatePicker图标颜色

win10 uwp 关联文件

win10 uwp 发布旁加载自动更新

win10 uwp 在 Grid 接收键盘消息

win10 uwp 切换主题

win10 uwp 使用 Microsoft.Graph 发送邮件

win10 uwp 动画移动滑动条的滑块

UWP 从文件 StorageFile 转 SoftwareBitmap 图片方法

win10 uwp 修改图片质量压缩图片

win10 uwp 在 ItemsPanelTemplate 里面通过样式绑定 Orientation 显示方向

uwp ScrollViewer content out of panel when set the long width

win10 uwp 使用 ScaleTransform 放大某个元素

win10 uwp 一张图说明水平对齐和垂直对齐

win10 uwp 使用 LayoutTransformer

win10 uwp 去掉 Flyout 边框

win10 uwp release 因为 Entry Point Not Found 无法启动

win10 uwp 使用 Matrix3DProjection 进行 3d 投影

控件

三种方式设置特定设备UWP XAML view

win10 uwp 在 Canvas 放一个超过大小的元素会不会被裁剪

win10 uwp 后台获取资源

win10 uwp 反射

win10 uwp 修改Pivot Header 颜色

win10 uwp 使用资源在后台创建控件

win10 uwp 使用动画修改 Grid column 的宽度

win10 uwp 使用 Geometry resources 在 xaml

win10 uwp slider 隐藏显示数值

win10 uwp ping

win10 uwp json

win10 uwp httpClient 登陆CSDN

win10 uwp MetroLog 入门

win10 uwp MVVM 语义耦合

win10 uwp DataContext

win10 uwp ApplicationView

win10 uwp xaml 兼容多个版本条件编译

win10 uwp url encode

win10 uwp 使用 Border 布局

win10 uwp xaml 绑定接口

win10 uwp 动态修改ListView元素布局

win10 uwp 图标制作器

win10 uwp 右击选择 GridViewItem

win10 uwp 判断设备类型

win10 uwp unix timestamp 时间戳转 DateTime

win10 UWP Markdown 含源代码

win10 UWP ListView 模仿开始菜单

win10 UWP 蜘蛛网效果

Win10 使用 GHO 安装出现 UWP 软件打开闪退应用商店无法安装软件

UWP WPF 解决 xaml 设计显示异常

win10 uwp 截图获取屏幕显示界面保存图片

UWP 转换 IBuffer 和其他类型

How to use code to exit the application in UWP

UWP How to custom RichTextBlock right click menu

UWP IRandomAccessStream 与 Stream 互转

win10 uwp 弹起键盘不隐藏界面元素

win10 uwp Fluent Design System 实践

win10 uwp smms图床

UWP WinUI3 传入 AddHandler 的 RoutedEventHandler 类型与事件所需不匹配将抛出参数异常

MVVM

win10 UWP MvvmLight入门

win10 uwp MVVM入门

win10 uwp MVVM 轻量框架

win10 uwp 轻量级 MVVM 框架入门 2.1.5.3199

构建部署

win10 uwp 发布的时候 ILC 编译不通过

UWP 部署失败 DEP0700 0x80073CF0 错误 0x800701C0 从位置 AppxManifest.xml 中打开文件失败

win10 uwp 使用 AppCenter 自动构建

win10 uwp 使用 Azure DevOps 自动构建

win10 uwp 在 VisualStudio 部署失败，找不到 Windows Phone 可能的原因

UWP 打包 win32 应用添加防火墙例外

WPF 打包为 UWP 应用构建失败 MSB3270 不匹配 AMD64 架构

win10 uwp 使用 msbuild 命令行编译 UWP 程序

修复 WPF 安装 WindowsAppSDK 库构建失败 NETSDK1082 和 NETSDK1112 找不到 win10-arm 失败

发布

如何在国内发布 UWP 应用

加强版在国内分发 UWP 应用正确方式通过win32安装UWP应用

UWP 上架失败因为没有添加隐私策略

win10 uwp 在 VisualStudio 打包测试完成自动上传到应用商店

win10 uwp 应用包上传失败无效的软件包系列名称

win10 uwp 安装文件 appinstaller 格式

调试

win10 uwp 调试软件启动

win10 uwp 隐藏实时可视化

win10 uwp 无法附加到CoreCLR

win10 uwp 使用 WinDbg 调试

应用开发

Win2D

win10 uwp win2d 入门看这一篇就够了

win10 uwp win2d 离屏渲染

win2d CanvasRenderTarget vs CanvasBitmap

win10 uwp win2d 使用 Path 绘制界面

win10 uwp win2d CanvasVirtualControl 与 CanvasAnimatedControl

win10 uwp 通过 win2d 画出笔迹

win10 uwp 通过 Win2d 完全控制笔迹绘制逻辑

win10 uwp win2d 特效

win2d 通过 CanvasActiveLayer 画出透明度和裁剪

win2d 图片水印

win2d CanvasCommandList 使用方法

win2d 画出好看的图形

win2d 渐变颜色

dotnet WinUI3 Win2D 翻转图片

dotnet C# 从控制台开始关联 Win2D 和 WinUI 3 应用

WinUI 3

C# 从控制台创建 WinUI 3 应用

WinUI 3 修复非打包应用运行提示缺少 Windows App Runtime 环境

dotnet WinUI 3 修复非打包应用运行提示 Microsoft.ui.xaml.dll 找不到

简单在 WinUI 仿造 WPF 的 ColumnDefinition SharedSizeGroup 共享列宽功能

dotnet WinUI3 Win2D 翻转图片

dotnet C# 从控制台开始关联 Win2D 和 WinUI 3 应用

WinForms

WinForms 使用 Image 的 FromFile 方法加载文件和使用 Bitmap 有什么不同

WinForms 下的高性能笔迹方法

Winforms 可能遇到的 1000 个问题

C# winforms 输入颜色转换颜色名

MAUI

dotnet Multi-platform App UI 多平台应用 UI 框架简介

MAUI 自定义绘图入门

WPF 使用 MAUI 的自绘制逻辑博客园

dotnet 控制台使用 Microsoft.Maui.Graphics 配合 Skia 进行绘图入门博客园

Microsoft.Maui.Graphics.Skia 使用 DrawString 绘制文本的坐标问题

MAUI中使用Maui.Graphics.Controls绘制控件 - 痕迹g - 博客园

dotnet OpenXML 使用 MAUI 渲染 PPT 的面积图图表博客园

MAUI 已知问题 PathFigureCollectionConverter 非线程安全

MAUI 框架开发

MAUI 框架开发将 MAUI 嵌入到 WPF 控件里

读 MAUI 源代码理解可绑定对象和可绑定属性的存储机制

Xamarin

Xamarin.Forms 选取文件让用户选择本地文件

Xamarin iOS 部署应用提示 iOS code signing key 失败

Xamarin 和 WPF 的控件和属性的替换

Xamarin 构建安卓失败因为路径太长

Xamarin 构建提示 error APT2260 resource 找不到资源

Xamarin iOS 切换开发者账号之后的签名标识和预配配置文件更新方法

Xamarin.Forms 按钮样式圆角按钮

Xamarin 解决创建空白项目编译提示 linking references 找不到资源

Xamarin Forms WPF 干掉默认的窗口导航条

Xamarin iOS 部署版本大于手机的系统版本

Xamarin iOS 部署项目提示 Failed to register bundle identifier 失败

Xamarin XamlCTask 任务不支持 ValidateOnly 参数

Xamarin 使用 GTK 提示找不到 libglib-2.0-0.dll 找不到

Xamarin 从零开始部署 iOS 上的 Walterlv.CloudKeyboard 应用

Xamarin Forms 进度条控件

Xamarin Forms 4.7 支持更简化的 Grid 行列布局写法

Xamarin Forms 构建 WPF 版项目失败提示 XamlC error XFC0000 错误

WPF 从零手动创建承载 Xamarin Forms 项目

Mac 升级到 dotnet 5 构建 Xamarin 应用失败 error MSB4186 静态方法调用语法无效

Unity3D

Unity3d 入门控制相机移动

Unity3D 用对象创建对象

Unity3D 判断点击命中物体对象和命中环境

Unity3d 修改编辑界面控制图标大小修改相机图标显示大小

Unity3d 连续按键处理和单次按键处理

Unity3d 制作一个立体旋转相册

Unity3D 2019 设置的 Playmode tint 有何作用

Unity3d 2019.3 通过 Ctrl 键让移动是固定步距

Unity 2019.3 将 RenderTexture 绑定到相机和物体作出镜子效果

VR

Unity3D OpenVR SteamVR 在头盔视觉前面常驻文本

Unity3D OpenVR SteamVR 点击菜单切换场景

Unity3D OpenVR SteamVR 获取输入动作按键交互设备数据方法

Unity3D OpenVR SteamVR Input Action 动作

Unity3D OpenVR 虚拟现实保龄球打砖块游戏开发

AI

Microsoft Agent Framework

Microsoft Agent Framework 与 DeepSeek 对接

C# Microsoft Agent Framework 与豆包对接

Microsoft Agent Framework 取出 DeepSeek 思考内容

Microsoft Agent Framework 测试豆包的根据图片生成矢量图的能力

dotnet 对接豆包模型时如何控制是否进入思考模式

dotnet Microsoft Agent Framework 配置调用工具后退出对话

用 Microsoft Agent Framework 对接豆包大模型实现AI自动玩「谁是卧底」游戏

SemanticKernel

dotnet SemanticKernel 入门开篇

dotnet SemanticKernel 入门调用原生本机技能

dotnet SemanticKernel 入门将技能导入框架

dotnet SemanticKernel 入门注入日志

dotnet SemanticKernel 入门自定义变量和技能

dotnet 简单控制台使用 KernelMemory 向量化文本嵌入生成和查询

dotnet 将本地的 Phi-3 模型与 SemanticKernel 进行对接

应用

SemanticKernel 将 LLM 自然语言函数和传统编程融合到一起

原理

dotnet 探究 SemanticKernel 的 planner 的原理博客园

DirectML

dotnet 基于 DirectML 控制台运行 Phi-3 模型

MCP

dotnet MCP 无魔法本地进程内服务端客户端调用和通讯示例

ASP.NET Core

asp dotnet core 从零开始创建一个 WebApi 服务

dotnet 三句命令行创建运行一个 web 服务程序

asp dotnet core 限制接口只能本机访问的方法

asp dotnet core 基于 TestServer 做集成测试

ASP.NET Core 引用其他程序集项目里面的 Controller 控制器

ASP.NET Core 将文件夹内容输出为压缩包文件方法

ASP.NET Core 因为 Nginx 配置 Connection 为 Upgrade 导致 Kestrel 返回 400 错误

ASP.NET Core 警惕可空类型开启之后模型校验失败

asp dotnet core 3.0 接口返回 json 使用 PascalCase 格式

asp dotnet core 不正经的提升效率的单元测试方法

asp dotnet core 记一次应用拒绝响应调试开启线程等待同步用光线程池

asp dotnet core 提供大文件下载的测试

[ASP.NET Core 解决控制台输出日志内容前面40m等乱码字符

asp dotnet core 提示 Cannot access a disposed object 解决方法

WPF 和 ASP.NET Core 通过 elastic APM 上报信息

当 ASP.NET Core 链接找不到时可能的原因

asp dotnet core 从 Frp 获取用户真实 IP 地址

asp dotnet core 实现服务器发送事件 Server-Sent Events 简单方式

asp dotnet core 通过图片统计 csdn 用户访问

asp dotnet core 简单开发P2P中央服务器

asp dotnet core 支持客户端上传文件

ASP.NET Core 6 浅析环境变量与配置的优先级

asp dotnet core 图片在浏览器没访问可能原因

ASP.NET Core 开启后台任务

ASP.NET Core 写一个能够接收所有请求路径的测试服务

dotnet 给MatterMost订阅RSS博客

ASP.NET Core 简单给 Phi 模型封装一个服务

ASP.NET Core 制作一个低资源占用的支持超大文件表单上传的服务

Blazor

.NET Core 用 Blazor 做 jmeter 系列视频

dotnet Blazor 用 C# 控制界面行为

Blazor 获取当前的 Url 链接

Blazor 的 NavLink 的 NavLinkMatch.Prefix 有啥作用

Blazor 的 NavLink 提示 RZ9986 不支持复杂内容

Blazor 如何使用代码跳转链接

dotnet 将C#编译为wasm让前端html使用

渲染

SharpDx

渲染部分，关于 SharpDx 使用，包括入门级教程，请参阅：

现在 SharpDx 已经不维护了，如果还需要在 C# 使用 Dx 相关技术，可以使用 SharpDx 的代替项目列出的替代项目

Vortice

由于 SharpDx 已经不维护了，可使用 Vortice 替换，以下是 Vortice 的博客

更多关于 DirectX 相关，请参阅 DirectX 官方博客： DirectX Landing Page - DirectX Developer Blog

Skia

dotnet 修复在 Linux 上使用 SkiaSharp 提示找不到 liblibSkiaSharp 库

WPF 解决 Skia 因为找不到字体而绘制不出中文字符

WPF 探索 Skia 的竖排文本渲染的字符高度

WPF 使用 Skia 绘制 WriteableBitmap 图片

WPF 自己封装 Skia 差量绘制控件

WPF 使用 Skia 解析绘制 SVG 图片

dotnet 控制台使用 Microsoft.Maui.Graphics 配合 Skia 进行绘图入门

Microsoft.Maui.Graphics.Skia 使用 DrawString 绘制文本的坐标问题

SkiaSharp 渲染输出 SVG 文件

SkiaSharp跨平台绘图研究1-WPF桌面应用 - SunnyTrudeau - 博客园

SkiaSharp跨平台绘图研究2-Xamarin.Forms移动应用 - SunnyTrudeau - 博客园

SkiaSharp跨平台绘图研究3-Asp.Net Core网站 - SunnyTrudeau - 博客园

SkiaSharp跨平台绘图研究4-在PDF上绘图 - SunnyTrudeau - 博客园

SkiaSharp跨平台绘图研究5-Blazor WebAssembly网页绘图 - SunnyTrudeau - 博客园

Docker环境下使用SkiaSharp的2种方式 - 从零开始-DotNET技术 - 博客园

dotnet 简单聊聊 Skia 里的 SKFontMetrics 的各项属性作用

SkiaSharp 使用 HarfBuzz 修复找不到 Symbol 字形

Skia 在龙芯搭景嘉微显卡设备某些字体会渲染相互覆盖

WPF 渲染相关

我写了一些关于 WPF 底层渲染和渲染定制以及 WPF 与其他渲染库对接的博客，请参阅： WPF 底层渲染_lindexi_gd的博客-CSDN博客

WPF 渲染原理

WPF 使用 SharpDx 渲染博客导航

从 DX 层面讲 WPF 渲染卡顿

Windows 核心编程笔记 Direct2D 比 GDI 快的一部分

WPF 使用 SharpDX 在 D3DImage 显示

Silk.NET

WPF 使用 Silk.NET 进行 DirectX 渲染入门

WPF 使用 Silk.NET 进行 Direct2D 渲染入门

使用 Silk.NET 创建 OpenGL 空窗口项目例子

使用 Silk.NET 调用 DirectWrite 获取字体 Font Metrics 信息

OpenTK

OpenTK 入门初始化窗口

OpenTK 入门 Vsync 垂直同步对刷新率的影响

DirectWrite

使用 Silk.NET 调用 DirectWrite 获取字体 Font Metrics 信息

DirectWrite 通过 GetUnicodeRanges 获取字体能支持的字符范围

OpenXML

使用 OpenXML 可以对 Office 文档进行底层的处理，相关博客比较多，请参阅：

Office 使用 OpenXML SDK 解析文档博客目录

调试

代码的调试方法，常用的套路和经验

入门的大博客： dotnet 代码调试方法

Windows 调试工具课程

dotnet 调试应用启动闪退的方法

记因为 NVIDIA 显驱错误而让 WPF 应用启动闪退问题

记一次调试资源管理器未响应经验

记调试 RX-Explorer-WAS 文件管理器 UI 未响应问题

VisualStudio 调试内存泄漏方法

VisualStudio 开启仅我代码调试

WinDbg 加载 dotnet core 的 sos.dll 辅助调试方法

dotnet 使用 windbg 运行脚本方式自动批量调试处理 dump 文件

WinDbg 设置在加载到某个 DLL 进入断点

优雅调试 REST API 的工具

调试时限制程序使用 CPU 核心数模拟低端设备

断点调试 Windows 源代码

在 Windows 下那些好用的调试软件

调试 ms 源代码

dotnet 如何调试某个文件是哪个代码创建

dotnet core 输出调试信息到 DebugView 软件

VisualStudio 使用 FastTunnel 辅助搭建远程调试环境

记内存条硬件损坏蓝屏的 dump 文件分析

Windows

Windows 通过编辑注册表设置左右手使用习惯更改 Popup 弹出位置

win10 安装Mpi

影子系统让 C++ 程序无法运行

安装 Sureface Hub 系统 Windows 10 team PPIPro 系统

如何在 Windows 10 中移除 Internet Explorer 浏览器

恢复 U 盘隐藏文件夹

国内好用的 DNS 列表

windows 10预览版升级win10 7月29 10240.16384

windows-10「设置」应用完整ms-settings快捷方式汇总.md

win10 本地适配器不支持重要的低能耗控制器状态

win10 使用 SMB v1

windows 应用程序在关机时的退出代号

win7 升级到 win10 补丁

Windows 10 16251 添加的 api

解决 Win10 UWP 无法使用 ss 连接

微软各版本系统不再维护时间

如何让 USB 设备不显示安全删除硬件弹出选项

手机1520 win8.1升级win10

Windows 对全屏应用的优化

使用 DISM 安全清理 C 盘 WinSxS 文件夹空间

Win10 Win11 如何真正获取 Trustedinstaller 权限（非修改所有者及权限） - IT之家

文件系统功能比较 NTFS、exFAT、UDF 和 FAT32 的功能和功能支持比较 - Win32 apps - Microsoft Learn

PowerShell 设置 Windows 安全中心白名单排除项

Windows 编程

win10 17025 触摸bug

d3dcompiler_47.dll 无法定位程序输入点__CxxFrameHandler4于动态链接库

Windows 窗口样式什么是 WS_EX_NOREDIRECTIONBITMAP 样式

用 SetWindowPos 方法设置一个停止响应的窗口将卡调用方

Windows 的 Pen 协议

XP 源代码如何在清空回收站时修改回收站图标

Windows 核心编程笔记 Direct2D 比 GDI 快的一部分

如何让软件以 System 权限运行

dotnet 删除自身程序的方法

dotnet 判断程序当前使用管理员运行降低权使用普通权限运行

C# 通过编程的方法在桌面创建回收站快捷方式

dotnet core 导出 COM 组件

C# 判断系统版本

Win32 使用 CreateProcess 方法让任务管理器里的命令行不显示应用文件路径

如何替换一个 exe 的图标

win 消息

剪贴板被占用导致应用使用剪贴板拷贝内容失败抛出 COMException 0x800401D0 错误

C# 息屏操作出现闪屏 - 唐宋元明清2188 - 博客园

dotnet C# 使用 Win32 函数获取用户下载文件夹的路径的方法

win32 低内存通知事件

Windows 设置应用禁用卸载 - 唐宋元明清2188 - 博客园

.NET 窗口/屏幕录制 - 唐宋元明清2188 - 博客园

dotnet C# 使用 SHFileOperation 调用 Win32 的文件复制对话框

.NET中如何实现高精度定时器 - czwy - 博客园

高精度定时器实现 - GKarch

Windows 客户端软件自动更新服务的开发有哪些需求

记 QEMU 虚拟磁盘设备移动文件抛异常但实际移动成功

Windows 行为测试删除 FileStream 正在读写文件可以继续读写

dotnet 简单通过 EnumDisplayDevices 获取显示设备信息

dotnet 利用 Windows 注册表实现开机自动启动

使用 IShellLinkW 创建 URL 网址超链接快捷方式

Win32 使用 MoveFileEx 延迟到重启后删除文件

WIC

dotnet 在 Windows 系统上使用 stakx 的 WIC 库

dotnet win32 使用 WIC 获取系统编解码器

WPF 通过 GifBitmapDecoder 调用 WIC 解析 Gif 和进行动画播放的简单方法

WPF 对接 Vortice 调用 WIC 加载图片

UIA

UI自动化 — 微软UI Automation - NiueryDiary - 博客园

UI自动化 — UI Automation 基础详解 - NiueryDiary - 博客园

测试

dotnet 单元测试注入文件读写

dotnet 如何在 dotnet test 单元测试控制台里输出日志内容

dotnet 单元测试 Mock 让一个对象继承多个接口

win10 UWP 单元测试

dotnet 集成测试 SmartSql 存在静态量导致多个主机启动提示 Alias 已存在

asp dotnet core 提供大文件下载的测试

asp dotnet core 不正经的提升效率的单元测试方法

asp dotnet core 基于 TestServer 做集成测试

dotnet 使用 MSTestRunner 将单元测试制作为独立可执行文件

定制 MSTest 单元测试框架让一个 TestMethod 包含多个测试用例

性能测试

C# 标准性能测试

C# 标准性能测试高级用法

dotnet 6 数组拷贝性能对比

dotnet C# 字典 Dictionary 和 Hashtable 的性能对比

dotnet 5 静态字段和属性的反射获取没有想象中那么伤性能

dotnet C# 链表和字典的性能对比

C# 程序集数量对软件启动性能的影响

C# 直接创建多个类和使用反射创建类的性能

C# 性能分析反射 VS 配置文件 VS 预编译

C# 程序内的类数量对程序启动的影响

C# 配置文件存储各种序列化算法性能比较

C# 字典 Dictionary 的 TryGetValue 与先判断 ContainsKey 然后 Get 的性能对比

dotnet ConcurrentDictionary 的 GetOrAdd 性能比 TryGetValue 加 TryAdd 低

WPF 动画性能测试应用一千个半透明矩形做动画

dotnet C# 在不同的机器 CPU 型号上的基准性能测试

dotnet 对一些 Win32 方法进行 Benchmark 基准性能测试

测试工具

C# 自动翻页 PPT 测试脚本

WPF 制作一个占用文件的测试工具

GitHub 的 Action 接入 Stryker.NET 进行自动化测试单元测试鲁棒性

测试框架

dotnetCampus.UITest.WPF 一个支持中文用例的界面单元测试框架

dotnet 如何在 Mock 模拟 Func 判断调用次数

Moq基础判断方法被执行

Autofac 集成测试

Autofac 通过 PreserveExistingDefaults 解决单元测试 Fake 对象被覆盖

Autofac 集成测试在 ConfigureContainer 之后进行 Mock 注入

打包构建

编译器

我写了很多关于 Roslyn 相关的博客，请参阅：

手把手教你写 Roslyn 修改编译博客导航

前置知识

理解 C# 项目 csproj 文件格式的本质和编译流程 - walterlv

重新认识 MSBuild - 1 - hez2010 - 博客园

构建的基础知识

Roslyn 如何了解某个项目在 msbuild 中所有用到的属性以及构建过程

Roslyn 使用 Directory.Build.props 文件定义编译

Roslyn 使用 Directory.Build.props 管理多个项目配置

项目文件中的已知属性（知道了这些，就不会随便在 csproj 中写死常量啦） - walterlv

Roslyn 通过 nuget 统一管理信息

msbuild 项目文件常用判断条件

Roslyn 在项目文件使用条件判断

Roslyn 判断当前使用 dotnet core 编译器进行编译

分析器入门知识

dotnet 源代码生成器分析器入门

Roslyn 入门：使用 Visual Studio 的语法可视化（Syntax Visualizer）窗格查看和了解代码的语法树 - walterlv

Roslyn 入门：使用 .NET Core 版本的 Roslyn 编译并执行跨平台的静态的源码 - walterlv

Roslyn 入门：使用 Roslyn 静态分析现有项目中的代码（语法分析） - walterlv

Roslyn 基础知识

Roslyn NameSyntax 的 ToString 和 ToFullString 的区别

Roslyn 节点的 Span 和 FullSpan 有什么区别

Roslyn 分析器 EnforceExtendedAnalyzerRules 属性的作用

dotnet Roslyn 通过读取 suo 文件获取解决方案的启动项目

Roslyn 静态分析

Roslyn 如何获得一个类的引用

Roslyn 简单实现代码智能提示补全功能

Roslyn 源代码生成器 SourceGenerator 获取代码文件的本地绝对路径

Roslyn 分析器 INamedTypeSymbol 的 AllInterfaces 包含类型全部继承接口

构建编排

如何编写基于 Microsoft.NET.Sdk 的跨平台的 MSBuild Target（附各种自带的 Task） - walterlv

Roslyn 通过 Target 修改编译的文件

Roslyn 让编译时候 Message 内容默认输出

Roslyn 理解 msbuild 的清理过程

Roslyn 获得 sln 文件所在的文件夹

Roslyn 如何使用 MSBuild Copy 复制文件

Roslyn 如何使用 MSBuild MakeDir 创建文件夹

Roslyn 使用 Target 替换占位符方式生成 nuget 打包

Roslyn 在多开发框架让 msbuild 的 Target 仅运行一次

Roslyn 如何在 Target 引用 xaml 防止文件没有编译

Roslyn 禁止 sdk style csproj 默认引用 Compile 代码文件

Roslyn 使用 WriteLinesToFile 解决参数过长无法传入

定制构建

dotnet 通过引用 msbuild 程序集实现自己定制编译器

dotnet core 通过修改文件头的方式隐藏控制台窗口

WPF 框架开发调试和开发 XAML 构建过程的 PresentationBuildTasks 方法

Roslyn 应用

Roslyn MSBuild 在构建完成之后将构建时间写入到输出文件

Roslyn 将这个文件放在你的项目文件夹，无论哪个控制台项目都会输出林德熙是逗比

已知问题

Roslyn 通过 Nuget 引用源代码在 VS 智能提示正常但是无法编译

Roslyn 分析器已知问题传递项目属性时将忽略分号之后的内容

生成代码

dotnet 源代码生成器分析器入门

大佬收藏的 Source Generators 列表： amis92/csharp-source-generators: A list of C# Source Generators (not necessarily awesome) and associated resources: articles, talks, demos.

尝试 IIncrementalGenerator 进行增量 Source Generator 生成代码

为 IIncrementalGenerator 增量 Source Generator 源代码生成项目添加单元测试

IIncrementalGenerator 如何在源代码生成器单元测试提供 AnalyzerConfigOptionsProvider 选项

dotnet 在 VisualStudio 一键 F5 启动调试 Roslyn 分析器项目

dotnet 使用 IndentedTextWriter 辅助生成代码时生成带缩进的内容

IIncrementalGenerator 增量 Source Generator 生成代码入门读取 csproj 项目文件的属性配置

Roslyn 分析器读取 csproj 项目文件的 AdditionalFiles Item 的 Metadata 配置

IIncrementalGenerator 增量 Source Generator 生成代码入门获取引用程序集的所有类型

IIncrementalGenerator 增量 Source Generator 生成代码入门判断程序集之间的 InternalsVisibleTo 关系

IIncrementalGenerator 增量 Source Generator 生成代码入门判断程序集的引用关系

IIncrementalGenerator 增量 Source Generator 生成代码入门获取项目默认命名空间

IIncrementalGenerator 增量 Source Generator 生成代码入门读取解析 ValueTuple 的定义

使用 ForAttributeWithMetadataName 提高 IIncrementalGenerator 增量 Source Generator 源代码生成开发效率和性能

将 Source Generator 生成的源代码保存到本地文件

IIncrementalGenerator 增量 Source Generator 生成代码应用将构建时间写入源代码

dotnet 用 SourceGenerator 源代码生成技术实现中文编程语言博客园

生成代码例子

使用 Source Generator 在编译你的 .NET 项目时自动生成代码 - walterlv

VisualStudio

VisualStudio 各版本 msbuild 路径

visual studio 2015 warning MSB3246

Visual studio 创建项目失败vstemplate

Visual Studio 自定义项目模板

Visual studio C# 代码使用 NotNull

从以前的项目格式迁移到 VS2017 新项目格式

msbuild Roslyn 行为详解

VisualStudio can not get the correct struct object value in Locals windows

VisualStudio 自定义外部命令

VisualStudio 外部工具配合 dotnet tool 制作复制文件名工具

VisualStudio 如何快速添加一个 Git Tag 推送

TotalCommander 设置 VisualStudio 开发者命令行

VisualStudio 命令行编译 build 通过 rebuild 不通过

msbuild 修改 VisualStudio 文件复制到输出目录的路径

dotnet 通过 DockerfileContext 解决项目放在里层文件夹导致 VisualStudio 构建失败

在 VisualStudio 给文件起一个带分号的文件名会怎样

VisualStudio 开发文件自定义工具单文件生成工具

VisualStudio 2019 新特性

VisualStudio 2019 尝试使用 C# 8.0 新的方式

VisualStudio 2017 项目格式自动生成版本号

在 Windows Defender 设置文件夹白名单提升 VisualStudio 编译速度

使用 IncrediBuild 提升 VisualStudio 编译速度

安装visualStudio 出现 cant install Microsoft.TeamFoundation.OfficeIntegration.Resources

一段能让 VisualStudio 炸掉的代码

visualStudio 无法登陆

VisualStudio 禁用移动文件到文件夹自动修改命名空间功能

VisualStudio 解决方案筛选器 slnf 文件

VisualStudio 使用三个方法启动最新 C# 功能

VisualStudio 2019 如何离线下载

VisualStudio 配置多进程调试快捷键启动项目

VisualStudio 2019 新创建项目添加 git 仓库

VisualStudio 2022 如何显示 dotnet 6 及以上版本的框架的代码注释为中文

VisualStudio 快速设置启动项目

VisualStudio 合并代码文件

VisualStudio 修改配色

Visual Studio 查看项目的能力

git 使用 VisualStudio 比较分支更改

WPF 使用 VisualStudio 2017 项目文件

VisualStudio 安装 Python 开发

VisualStudio 通过 EditorBrowsable 隐藏不开放的属性或方法

VisualStudio 过滤输出窗口文本

VisualStudio 通过配置 DefaultXamlRuntime 属性让控制台项目里的 XAML 应用上智能提示

VisualStudio csproj 添加 ItemGroup 的 Service

VisualStudio 调试

VisualStudio 断点调试详解

VisualStudio 调试内存泄漏方法

Roslyn 让 VisualStudio 急速调试底层库方法

警惕 Visual Studio 属性求值副作用导致逻辑不符合预期

UOS 开启 VisualStudio 远程调试 .NET 应用之旅

VisualStudio 如何 SSH 远程调试 Linux 的 dotnet 应用的启动

VisualStudio 使用多个环境进行调试

VisualStudio 开启仅我代码调试

VisualStudio 通过外部调试方法快速调试库代码

VisualStudio 打断点调试和不打断点调试有什么区别

VisualStudio 在 DebuggerDisplay 的属性更改业务逻辑将会让调试和非调试下逻辑不同

VisualStudio 2019 调试项目使用 Portable PDB 提示不支持 PDB 格式

VisualStudio 解决首次调试 docker 的 vs2017u5 exists, deleting 太慢问题

VisualStudio 调试时会不断刷新 WPF 应用渲染

visual Studio 无法调试，提示程序跟踪已退出

VisualStudio 2022 找不到内存反汇编寄存器调试工具腾讯云

VisualStudio 插件收藏

VisualStudio 好用插件集合

VisualStudio 编码规范工具 2.6 修改当前文件编码

VisualStudio 插件翻译注释

VisualStudio 扩展插件开发

VisualStudio 扩展开发

VisualStudio 扩展开发获得输出窗口内容

VisualStudio 扩展开发添加输出窗口

VisualStudio 扩展开发添加菜单

CICD

如何给 CI CD 服务器搭建上 .NET 5 构建和运行环境

GitHub Action

dotnet 部署 github 的 Action 进行持续集成

dotnet 配置 github 自动打包上传 nuget 文件

dotnet 配合 GitHub 的 Action 做自动推 Tag 时打包 NuGet 包

Github 给仓库上传 NuGet 库

dotnet 在 GitHub 的 Action 上部署自动代码编码规范机器人

在 GitHub 仓库添加 NuGet 版本图标和构建图标

GitHub Action 新上线 WPF .NET Core 自动构建模板

dotnet 基于 dotnet format 的 GitHub Action 自动代码格式化机器人

github 设置自动删除合并的分支

dotnet 部署 GitHub 的 Action Runner 制作自托管运行器

GitHub 如何过滤某个作者的 MR 内容

Github 添加 Action 编译图标

GitHub 的 Action 接入 Stryker.NET 进行自动化测试单元测试鲁棒性

dotnet 通过 GitHub 的 Action 辅助下载国外资源文件的离线下载方法

GitHub 的 Action 如何禁用

GitHub 的 Action 判断仅在主仓库才执行脚本

dotnet 修复 GitHub Action 构建过程提示 NETSDK1127 错误腾讯云

支持较低 GLibC 版本的 dotnet AOT GitHub Action 构建方法

Gitlab

dotnet 配置 Gitlab 的 Runner 做 CI 自动构建

dotnet 配合 Gitlab 做自动推 Tag 时打包 NuGet 包

dotnet 将自动代码格式化机器人带入团队 GitLab 平台

如何让 Gitlab 的 Runner 在构建时拉取 Git Submodules 仓库

修复 GitLab 的 CI Runner 提示找不到 pwsh 执行文件

ASP.NET Core 连接 GitLab 与 MatterMost 打造 devops 工具

制作一个能构建 dotnet AOT 的 gitlab ruuner 的 Debian docker 镜像

dotnet 配置 Gitlab 的 CI 找不到 Runner 或找错的可能原因

在 Gitlab 开启 MatterMost 机器人

dotnet tool 创建 GitLab 合并请求 Merge Requests 工具

从 gitlab 配置管理聊聊团队项目管理

Windows 11 在 GitLab Runner 服务内找不到 SMB 挂载的 NAS 文件夹

杂项

开源项目使用 appveyor 自动构建

Fiddler 插件开发将插件放在独立子文件夹防止 DLL 冲突

NuGet

dotnet 打包 NuGet 的配置属性大全整理

msbuild 项目文件常用判断条件

How to generate NuGet package with Git Tag version using GitHub Action

dotnet 用 ASP.NET Core 制作一个可以上传库文件的 NuGet 服务器

dotnet 用 NuGet 将自己的工具作为 dotnet tool 分发

Roslyn 打包 NuGet 包添加改动日志

dotnet 为什么每个项目都会输出一个 NuGet 包而不是一个包带所有项目

Roslyn 在 NuGet 包中放注释 xml 文件的方法

NuGet 更新库新版本的缓存问题

dotnet 在 NuGet 上搜寻好用的 dotnet tool 工具

NuGet 如何设置图标

dotnet 使用 SourceLink 将 NuGet 链接源代码到 GitHub 等仓库

NuGet 命令行上传找不到 snupkg 文件

Roslyn 使用 Target 替换占位符方式生成 nuget 打包

Roslyn 通过 NuGet 库修改应用程序入口函数

Roslyn 通过 Nuget 引用源代码在 VS 智能提示正常但是无法编译

Roslyn 通过 Nuget 管理公司配置

VisualStudio 使用新项目格式快速打出 Nuget 包

获取 Nuget 版本号

如何移动 nuget 缓存文件夹

Github 给仓库上传 NuGet 库

How to fix nuget Unrecognized license type MIT when pack

Roslyn 开发 NuGet 包的 Task 编译可能遇到的问题

NuGet 符号服务器

VisualStudio 如何在 NuGet 包里面同时包含 DEBUG 和 RELEASE 的库

VisualStudio 给项目添加特殊的 Nuget 的链接

Nuget 通过 dotnet 命令行发布

Roslyn 通过 nuget 统一管理信息

修复 VisualStudio 构建时没有将 NuGet 的 PDB 符号文件拷贝到输出文件夹

Roslyn 如何基于 Microsoft.NET.Sdk 制作源代码包

Roslyn 打包自定义的文件到 NuGet 包

Roslyn 通过 EmbedAllSources 将源代码嵌入到 PDB 符号文件中方便开发者调试

Roslyn 打包 NuGet 包 BuildTransitive 文件夹用于穿透依赖传递拷贝文件

软件安装包

WiX Toolset 安装包制作入门教程（目录篇） - walterlv

怎么做一个专业的软件安装包？ - 码坊

怎么制作炫酷软件安装包 - 码界工坊

利用Inno Setup在VS编译时自动构建安装包 - 码界工坊

Inno Setup 安装包脚本 Run 的 Flags 标记

设计和经验

记将一个大型客户端应用项目迁移到 dotnet 6 的经验和决策

浅谈 Windows 桌面端触摸架构演进

创建CBB心得

框架设计的想法

使用 IOC 控制反转和 DI 依赖注入的意义

聊聊 2020 的 dotnet 各大开源项目仓库的情况

dotnet 双缓存数据结构设计下载库的文件写入缓存框架

通过公开的自动构建发布开源项目的库的安全意义

使用 C# 写脚本的优势和方法

dotnet 开发的单代码仓库和多代码仓库的优劣

dotnet 日志上报的 TracerId 和 SessionId 的意义

程序猿修养

程序猿修养从安装 dotnet 开始

程序猿修养使用 NuGet 发射卫星只需要三步

程序猿修养日志应该如何写

算法

dotnet 从零开始写一个人工智能从一个神经元开始

图论 Warshall 和Floyd 矩阵传递闭包

C# dotnet 一个还看的过去的 B 树实现

为何 987654321/123456789 的值是 8.0000000729

开源项目

我收藏的一些开源项目，请看开源项目

开源工具

支持 dotnet 6 的 dnSpy 神器版本

WPF 推荐一个剪贴板内容查看工具

开源库介绍

dotnet 为大型应用接入 ApplicationStartupManager 启动流程框架

dotnet 使用 ConfigureAwait.Fody 库设置默认的 await 同步上下文切换配置

SourceYard 制作源代码包

dotnet 用 MVC 的方式打开 IPC 命名管道

WPF 开源二维绘画小工具 GeometryToolDemo 项目

dotnetCampus.UITest.WPF 一个支持中文用例的界面单元测试框架

WPF 将 SVG 转 XAML 的工具

用于辅助做二分调试的构建每个 commit 的工具

推荐一个使用 HardLink 硬链接减少重复文件占用磁盘空间的工具

dotnet C# 高性能配置文件读写库 dotnetCampus.Configurations 简介

使用 FastTunnel 做内网穿透远程计算机桌面服务器

FastTunnel 搭配 nginx 将本地内网电脑 HTTP 服务公开到子域名公网访问

苏州开源自主的 dotnet 生态

WPF 适合入门阅读的开源项目 SeeGit 图形化 Git 历史记录

dotnet 让 C# 可以通过动态生成 HLSL 使用 DX12 的 GPU 并行计算库 ComputeSharp 的简介

dotnet 用 MVC 的方式打开 IPC 命名管道

WPF 开源二维绘画小工具 GeometryToolDemo 项目

dotnet tool 文件编码规范命令行工具

dotnet 使用 Refasmer 从现有的 DLL 里面导出公开的成员组装出新的仅作为引用用途的程序集

dotnet 用 Microsoft.Diagnostics.Runtime 库写代码解析 DUMP 文件

dotnet 使用 AsyncQueue 创建高性能内存生产者消费者队列

dotnet Microsoft.Recognizers.Text 超强大的自然语言关键词提取库

dotnet 给任意对象附加任意属性的库

C＃命令行解析工具

使用 .NET Core 在 MAC 下提供 Excel 的 Power Query 功能

dotnet 使用 ClearScript 执行 VBScript 和 JS 代码无需浏览器

使用 Pandoc 把 Markdown 转 Docx

dotnet 使用 System.CommandLine 写命令行程序

dotnet 控制台 Hangfire 后台定时任务

Pipelines.Sockets.Unofficial 一个纯托管实现对接 System.IO.Pipelines 的 Sockets 库

dotnet C# 使用 FreeType 读取和绘制字体

SixLabors.ImageSharp 如何读取 IDAT 校验失败的 png 图片

使用 LatestCSharpFeatures 库让旧版本 dotnet 框架项目使用新 C# 语法

dotnet 简单使用 ICU 库进行分词和分行

dotnet 使用 ColorCode 做代码着色器

dotnet LibGit2Sharp 使用笔记

工具

高效率工具

dotnet tool

制作 dotnet 工具

dotnet 手工打一个 dotnet tool 包

制作的 dotnet tool 运行失败提示依赖缺失

dotnet tool 安装失败因为对应的库不仅包含工具

dotnet tool 工具安装提示 Could not find a part of the path 安装失败

开发调试工具

一些好用的开发者工具

MSBuild 输出日志可视化工具 MSBuild Structured Log Viewer 简介

让 snoop 支持 .NET Core WPF 调试

dotnet 使用 Infer# 自动分析代码缺陷

修复 SmartAssembly 混淆 .NET 6 时提示 Unable to load runtime config file 失败

dotnet format 忽略生成代码的格式化

支持 dotnet 6 的 dnSpy 神器版本

用于辅助做二分调试的构建每个 commit 的工具

dotnet OpenXML 解压缩文档为文件夹工具

docfx 做一个和微软一样的文档平台

WPF 将 SVG 转 XAML 的工具

使用 SizeBench 分析 Exe 文件体积

Resharper

WPF 使用 Resharper 更改命名空间后生成文件引用找不到的命名空间

resharper 跳转到源代码

解决 VS 跳转定义和 Resharper 重复

Resharper 如何把类里的类移动到其他文件

ReSharper 显示使用的颜色

ReSharper 已知问题在 Directory.Build.props 属性求值结果不能应用到项目里

Sublime Text

Sublime Text 安装中文、英文字体

Sublime Text 好用的插件

sublime Text 正则替换

添加右键使用 SublimeText 打开

dotnet core 添加 SublimeText 编译插件

在 SublimeText 使用 dotnet 编译 C# 项目

SublimeText 快速打开当前文件的文件夹

SublimeText 粘贴图片保存到本地

SublimeText 配置跳转回上个光标坐标

关闭 SublimeText 3.2.2 Build 3211 的拼写检查

GIT

git 需要知道的1000个问题

git 通过 SublimeMerge 处理冲突

git 上传当前分支

git 统计两个 commit 之间相差的次数

dotnet 更新本地所有 Git 仓库的工具

自动更新所有 Git 仓库

如何删除错误提交的 git 大文件

git 合并两个仓库

git无法pull仓库refusing to merge unrelated histories

git push 错误 hook declined

git rebase 合并多个提交

git cannot lock ref

git 已知问题命令行调用 git 时可能存在环境变量投毒问题

3分钟教你搭建 gitea 在 Centos 服务器

Azure

Azure 无服务器 Function 函数计算服务 dotnet core 3.1 创建和部署入门

Azure 函数服务部署失败因为函数应用设置 v3 但主机是 v2 版本

WPF 基于 Azure 的认知服务情绪分析语言检测关键短语提取

Docker

dotnet 执行 docker 容器 error MSB4018 CreateAppHost 任务意外失败可能原因

dotnet 基于 debian 创建一个 docker 的 sdk 镜像

dotnet 制作 docker 提示 Insufficient space in download directory 磁盘空间不足

在 windows 上运行的 podman 默认的挂载相对路径是什么

制作一个能构建 dotnet AOT 的 gitlab ruuner 的 Debian docker 镜像

Total Commander

Total Commander 显示文件包含文件名扩展

Total Commander 使用 mklink 建立文件夹链接将 C 盘文件迁移到其他盘

PowerShell

PowerShell 通过 WMI 获取系统服务

PowerShell 通过 WMI 获取系统安装软件

PowerShell 通过 WMI 获取系统信息

PowerShell 使用 WMI 获取信息

PowerShell 通过 WMI 获取系统安装的驱动

PowerShell 通过 WMI 获取设备厂商

PowerShell 通过 WMI 获取补丁

PowerShell 拿到显卡信息

PowerShell 实现 curl 的用户名和密码逻辑

dotnet core 使用 PowerShell 脚本

PowerShell 拿到最近的10个系统日志

BAT

BAT 脚本判断当前系统是 x86 还是 x64 系统

通过 cmd 批处理文件将 16 进制转 10 进制数字

如何在 CMD 启动的软件传入带空格的路径

cmd 如何跨驱动器移动文件夹

Latex

Latex 论文elsevier，手把手如何用Latex写论文

Latex 公式速查

Latex 去掉行号

希沃白板

希沃白板如何在公式里面输入绝对值符号

拼音输入法快速输入带音调的字符

希沃白板如何解决手机端播放课件内视频出现黑屏闪退

希沃白板断网环境免登陆编辑课件

jekyll

其他工具

让 AE 输出 MPEG

MobaXterm 使用代理

matlab 画图

使用 ahk 让普通键盘变为Dvorak键盘

通过 frp 开启服务器打开本地的 ZeroNet 服务器外网访问

贡献自己的服务器搭建tor中转

通过命令行使用微信

解决 BT 工具连接数过多导致无网速问题

杂项

非技术基于 VR 虚拟世界开展虚拟资产的玩法

微软最具价值专家 MVP 如何获得 Resharper 的免费功能

用 sim 卡加密保护资金

安装 wordpress 出现抱歉，我不能写入wp-config.php文件

上海展盟网络科技有限公司的 gamebox 组件注入进程导致软件崩溃

记联软 UniAccess 导致 NSIS 安装包启动进程失效

中国最新手机号段划分情况

用自动机的思想说明时间断片是无法感知的

dotnet 世界猜测随机数的小测试

P2P 下载

微软的 P2P 下载方式

完整的 P2P 应用需要包含哪些功能

在 P2P 文件分享应用以文件或文件段为单位的优缺

考古

英特尔 x86 微架构图考古贴 The Intel x86 Microarchitectures Map - Micromysteries

考古 ISO 639 标准 1988 和 1989 版的变更

手算神经网络 BP 传播算法

Tue, 07 Apr 2026 22:02:15 +0000

虽然说是手算，但是我还是会写一点 C# 代码，避免敲坏了计算器。我和大家保证，整个手算过程中，最终的计算结果只需要用到初高中知识。推导过程会用到部分高数的知识。我尽量将用到的知识点全列举出来，本文对学渣友好，期望能够拿出纸笔和 VisualStudio 的伙伴阅读完本文能够真的理解神经网络 BP 传播算法是如何计算的

看了一下时间，今年确实 2025 年，而不是 2015 年。在 2025 时还在聊 BP 算法实在有点一言难尽。我在 10 多年前尝试写过贴近的程序，当时写的时候有一些概念没有理解，但代码是写了也能跑，甚至于在当时世界上最快的超级计算机跑了我的代码。但不能理解的部分就是不能理解。最近在散步的时候，我的伙伴 https://github.com/SeWZC 和我说明白了求偏导的数学意义。我当初高数学了3年，别人都是只学一年（因为我不断挂科），那会以为偏导没有什么，于是缺了一个知识点，导致我对 BP 的部分理解错误。尽管代码能跑，也能符合预期进行训练，但里面关于传播算法中，如何计算各个权重参数的过程我是不能全说明白的。我最近理解了偏导的数学意义之后，再到知乎上阅读了《通俗理解神经网络BP传播算法》(https://zhuanlan.zhihu.com/p/24801814 ) 文章，尝试按照知乎文章的给定的内容和方法，自己手算了一遍，我就完全理解了之前我所写的代码了。担心本金鱼会忘了之前的想法，或者担心下次和伙伴聊天的时候又说错了，我就编写了本文。可以认为本文没有给出比《通俗理解神经网络BP传播算法》(https://zhuanlan.zhihu.com/p/24801814 ) 文章更多的内容，只是按照我自己的方式一步步推导和计算。阅读完本文，预期大家能够对神经网络有了更明了的理解。如果大家还是在迷迷糊糊地训练人工智能做玄学的活，那阅读本文可以让大家能够稍微有点落地的感觉，至少大概知道简单的 BP 神经网络是如何工作起来的

我努力让大家尽量少知识地开局

开始之前，期望大家已经听说过一些神经网络的概念。这里只要求听说过，不解其中的内容也没关系，有部分概念我没提到的，也许大家看完了自然就能明白，或阅读完本文之后再继续在网上搜关键词继续了解。期望听说过的概念有：神经网络、图论、矩阵、激活函数、损失函数、权重

神经网络可以理解图论上的一张图，尽管在几乎所有的科普文章中，都会使用到矩阵，但从原理上说都是图论的一张图。经费有限，有了节省矩阵的出场费，本文就不带入矩阵的内容了，直接平铺进行计算。本文也不会用到多少图论的知识，只是用了一点图论上的概念。本文介绍的手算的神经网络是一个简单的有向图，只有5个点。即使没有了解过图论的伙伴，也许通过示意图也能够看懂

本文的手算内容是假定咱就是一个无情的计算机，正在被训练的人工智能。咱的需要计算出图上（图论的图）的各个点的权重。为了让人类更方便理解，以下图中，我给定了明确的数值。假定输入是两个数字，期望经过咱训练出来的神经网络之后，能够获取符合预期的输出数字。这样的模拟情况，就能够覆盖非常多的情况了。也许有伙伴此时还会有一些疑惑，没关系，先带着疑惑看下去吧，我也不能一口气全交代清楚情况

以下是咱的神经网络图（图论的图）的示意图

其中 a 和 b 两个点负责输入，e点负责输出。各个点之间的连接存在权重，其示意图如下，下图的 wxx 表示的就是各个边的权重。写成 wxx 的形式其实就是在隐含矩阵的概念了，只是咱本文这里不需要请出矩阵而已，如果真套上矩阵的话，这里的权重就是 w行列的表示法，即 w21 就是表示第2行第1列的值。这也是一个习惯表示方法

假定有输入源 x0=0.35 x1=0.9 , 期望的输出是 $y_{out}=0.5$。这就是一组训练值，当然了，在实际的神经网络训练里面，肯定会给许多组训练值的。只是现在换成人类手算，需要降低难度，就只要求训练这一组数据。假定没有神经网络，就是一个正常人类在拿到 x0=0.35 x1=0.9的输入，要求写出一个函数，让这个函数能够根据此输入计算出 $y_{out}=0.5$ 的值，估计也没那么简单（禁止直接写 $f(x0,x1)=0.5$ 这样的拖出去打靶的函数）

为了更加方便大家理解，这里先给各个权重添加随机的初始值。初始值很多时候真的是随机给的，依靠的是训练过程中不断算法修改参数，从而训练出一个可用的神经网络。咱现在这个神经网络只是期望训练出当拿到 x0=0.35 x1=0.9 的输入时，能够返回 $y_{out}=0.5$ 的输出。标记了添加了随机权重初始值的示意图如下

好的，勤奋的伙伴可以开始拿出纸笔，在纸上画出以上示意图内容了。云程序猿们没有纸笔那就进入幻想模式，我不会让大家不至于说没纸笔就看不下去的对于一个正常的神经网络来说，每个点就是一个神经元，神经元里面包含了激活函数。在本文这里选定的 $f(x)$ 激活函数的定义如下

世界上的激活函数有许许多多，没有说一定要用哪个激活函数，大家也可以在阅读完本文之后，自己尝试其他的激活函数

在本文的 BP 神经网络里面，是取所有的输入乘以各自的权重之和，进入激活函数计算，从而得到输出。我将取所有的输入乘以各自的权重之和记为 $z_n$，将经过激活函数之后的输出记为 $y_n$ ，其示意图如下

也许大家看到这里开始有疑惑了，凭什么神经网络是这样子的。没为什么，最简单的神经网络只需要一个神经元即可，但一个神经元能做的事情就太弱了。虽然本文的图（图论的图）有5个点，但实际上 a 和 b 点都是在接收输入，实际参与计算只有三个点，相对来说已经足够简化了。在阅读完本文之后，大家也可以试试玩玩更多点和更多层的神经网络，只不过这时候就需要多写写代码啦，全靠手算可有点难哦似乎现在这个示意图看起来就有些复杂了，但相信如果是一步步看下来的伙伴，自然能够很快理解示意图的内容了

写到这里，咱距离整个简单 BP 神经网络就只剩下损失函数（Loss Function）的定义了。简单说明损失函数就是用来度量神经网络输出的值与预期期望值的差异程度的函数

损失函数要能反馈结果和预期的距离，且还要能够求导有意义。一听到反馈结果和预期的距离，大家可能想到的就是直接减就可以了，如这样的一个函数$C=y_2-y_{out}$，但在后续步骤里一求导就约分没了，算出来的$C^{‘}=1$，自然就无法继续进行下去了。那求差的平方呢，如$C=(y_2-y_{out})^2$呢？这个就好多了，加上平方也不用去烦恼绝对值的问题了，那自然就求结果和预期的差的平方好了。试试看求导的结果 $C^{‘}=2y_2-2y_{out}$，这一求导发现约分出了2的值，那索性继续乘以二分之一好了，这样求导返回结果刚好就是简单的减法，计算机看了非常开森。于是决定出来的损失函数定义如下

看到这里相信大家也感受到了照现在的人类的数学能力还不能让大家随意写一个函数，就能获取预期的结果。在本文的手算过程中，也许大家也就能够理解神经网络的能力边界。所使用的各个函数都有一些原因，不一定是期望获取咋样的结果就能用对应的函数，还需要所使用的函数刚好从数学上能够帮助后续的计算

如此咱的所有内容就都定义完成了。为了防止大家忘记现在的状态，我再次放入当前的示意图，咱接下来就按照这个意义图开始将自己当成一个神经网络，进行手算过程

拿出纸笔的伙伴可以将上述的示意图抄在草稿纸上，咱现在就来开始第一轮的计算过程。打开了 VisualStudio 的伙伴，还请创建好控制台项目，开始记录一些代码，先是一些初始化的变量或常量的值。为了确保让大家能够校验自己的计算结果内容，我这里的代码就写固定值，而不是使用随机数，这样也好方便纸笔手算的伙伴对比计算差异

const double x0 = 0.35;
const double x1 = 0.9;

const double y_out = 0.5;

var a = x0;
var b = x1;

var w11 = 0.1;
var w12 = 0.8;

var w21 = 0.4;
var w22 = 0.6;

var w31 = 0.3;
var w32 = 0.9;

var count = 0;

看到以上的代码，也许有伙伴有疑惑，以上代码中的 y_out 是不是不符合 C# 代码规范？我这里是借用 Latex 的表示，表示 y_out 常量，按照 Latex 写法就是 y_out 啦。因此就不要将其改成 yOut 或 YOut 哦

来进行一步步的计算过程，求 $z_0$ 的值

对应的代码实现如下

var z0 = w11 * a + w12 * b;

这个过程看起来十分简单，就是将所有进入 c 点的输入乘以对应的权重返回的和。同理继续计算d点的$z_1$的值

对应的代码如下

var z1 = w21 * a + w22 * b;

分别让 $z_0$ 和 $z_1$ 经过 $f(x)$ 激活函数，可分别得到 $y_0$ 和 $y_1$ 的值

也许大家用计算器算出来的小数点精度有些差异，但只要前面几位差不多就可以，对于神经网络来说不用太精确对应的代码如下，封装了 F 函数

double F(double x)
{
    return 1.0 / (1 + Math.Pow(Math.E, -x));
}
var y0 = F(z0);
var y1 = F(z1);

继续计算 $z_2$ 的值

对应的代码如下

var z2 = w31 * y0 + w32 * y1;

让 $z_2$ 经过激活函数，可得到$y_2$的值

对应的代码如下

var y2 = F(z2);

此时可见这一轮的输出$y_2$距离预期的$y_{out}$还有点距离。具体度量的距离有多大，那就要经过损失函数计算看

对应的代码如下

var c = C(y2);
static double C(double y2)
{
    return 1.0 / 2 * Math.Pow((y2 - y_out), 2);
}

完成了第一轮计算，接下来就是进行第一轮训练，进行 BP 的传播算法。此时在推导计算过程，就需要用到偏导的知识了。其中包括了偏导的链式计算和对函数求导的知识。借用从 https://www.cnblogs.com/awei040519/articles/18529084 博客的一张图来说明偏导在这里的意义。在这里的意义就是假定输入到输出中间经过的神经网络的某些权重变量计算之后，能够获取预期的输出内容，求解神经网络中的权重变量的值。这个求解过程有解，即是求让损失函数快速到达一个极小点。在偏导意义里面，极大和极小这些极值是相同的，从极大到极小的转换只需乘以负一即可

没有经过损失函数可不可以？可以的，但是存在的问题是，如果不用随机数随便乱碰，那怎么能够知道各个权重应该如何调，应该是朝着加号方向调还是减号方向调好呢。假定咱有无穷的计算时间，那就不停各个参数加0.00001或0或-0.00001给他全遍历即可，这样自然能够获取很（不敢说最哈）优解。但大家肯定也看出来问题，这样的做法需要大量的时间，且随着图（图论的图）上的点越多，这个计算时间就会越长，且是排列组合的快速加长，也许此时只有量子计算机才能计算了。聪明的数学家想到了利用数学上的偏导工具，协助更快速求较优解的权重数值解。如上图所示，利用偏导数协助求某一个切面上的函数导数的极值方向从而让权重的修改能够更快到达较优解，如从 https://zhuanlan.zhihu.com/p/1945144971243000845 拷贝的动图所示

读过高数的伙伴也许有疑惑，由于偏导只是求一个切面方向上的，而整个网络是依靠多个权重一起工作的，那是否会导致画出来的函数图实际上有多个极值呢？没错，这就是局部最优解陷阱。好在本文这里足够简单，还不会踩到这个坑。进入局部最优解陷阱时，也许经过了很多轮的训练，其输出也不能达到预期，这时候就是大佬们常说的炼丹结果是废丹了，需要重新修改权重为随机数重新炼丹

求出来各个权重对应偏导数值之后，就可以更新各个权重的值，进行下一轮计算。下一轮计算结果输出之后，再经过损失函数判断是否结果已经接近了。如果不接近，则再次求各个权重对应偏导数值，用各个权重对应偏导数值更新各个权重的值，再进行下一轮计算。这样的过程就是简化后的 BP 神经网络训练的过程。其计算方式如下，以下列举的公式中带“’”的部分表示更新之后的权重的值

通过以上公式不难看出，其中的核心点就是在于如何求偏导。只要求出偏导了，那自然就有了更新权重的数值的方法了

开始求偏导准备来修改权重参数。开始之前先简单介绍链式法则的计算方式。在本文用到的偏导知识部分非常少，本文也只介绍本文需要用到的部分知识。假定有一个参数 x 计算出了 y 的过程中，经过了两个步骤，先经过了 g 函数，求出了 t 结果。再将 t 结果传入 f 函数，从而计算出 y 结果。此时求x的偏导则可用以下的公式

可以看到，此时将计算拆分为两步，先求t的偏导，再求x的偏导。如此过程恰好就可以用在神经网络上，逐层逐个求偏导，且刚好可以实现累加的过程。当然，本文为了简单起见，不会减少计算过程，没有将计算过的值缓存起来省略重新计算的过程，但相信大家看到后面一眼就看出来重复部分很简单就可以省略重复计算

如求w31的偏导，就可以从y2到z2再到w31这样一步步求偏导做乘法，如以下示意图所示

如此即可得出以下公式

这个过程里面，各个步骤都是一个简单的确定的函数，求偏导过程也就很简单了。不需要说整个一路将 w31带入到最终计算式里面。大家如果好奇真的一路将w31带入表达式里面，最终损失函数C有多长，且求导稍微困难。通过链式的方式可以进行一级级的计算，整体复杂度也能够降低

接下来咱来开始一步步求这个偏导的内容

相信大家的求导知识还没忘记，求导数学意义上就是求速率。如对于常量函数，如 y=5 的函数，其速率就是平的，如下图所示，自然求出来的导数就是 0 的值

求偏导的话，只要对求偏导的变量当成变量，其他当成常量计算。这也就是为什么求出来的式子里面 $1/2 y_{out}^2$ 会是0的值的原因。那对于一次函数呢，如y=2x 函数呢，其导数反映的速率就刚好是变量前面的系数了。如下图所示

于是就有

那平方呢？平方的话，可以认为速率需要乘以变量自身，几倍方就是几倍速率

于是就有

回顾一下，整条式子算起来就是

是不是看到这里感觉损失函数确实不是随便选的，刚好这个函数能够非常好的适应求导的结果。求导结果里面非常方便进行计算，计算机看了非常开森，因为求导结果是两个已经计算出结果的值，而且只做减法。在第一轮训练结果里面，相信大家能够直接口算结果

看吧，没骗大家，只有过程推导用到了一点高数的知识，最终计算都是小学到高中的知识，且大部分都是小学知识

希望看到这里的大家会有很多信心，接下来开始解下一个偏导内容，这是最难的一个部分了

激活函数求导过程如下，咱选用的激活函数都是现成的，有很多大佬帮忙求导过了的函数的。如果大家感觉这个过程有点难，那也可以跳过，直接看求导结果就可以了

可以看到激活函数求导结果也是非常开森的计算，直接就是 fx·(1-fx) 的值，计算非常简单。试试代入公式

看起来这也是非常简单的小学数学就能完成计算结果，虽然本次计算过程有点难，但结果却是简单的。也依然是计算机非常开森的计算表达式，都是已知的变量的基础加减乘除计算

最后一步的求导就特别简单啦

因为只对w31求偏导，于是 w32 就可以视为常量。本身y0和y1就是被视为常量，直接 w32 乘以 y1就算出0的值。而y0作为w31的系数，求导结果就是y0了。这个过程看起来很解压。好了，各个式子就在这里求完了，将其组合起来

换成代码的话，其实现如下

var dc_dw31 = (y2 - y_out) * (y2 * (1 - y2)) * y0;

不知道大家这一步求出来的结果是否和我的接近呢

第一步的求偏导计算咱算了很久，后续的步骤咱就能快非常多了。如对w32求偏导，可以看到只有最后一条式子有所不同

代码实现如下

var dc_dw32 = (y2 - y_out) * (y2 * (1 - y2)) * y1;

从这里也可以看到对 w31 和 w32 求偏导，也只有最后一个乘数不相同而已。对于程序猿来说，看到有很多相同的代码，本能地自然就会去想优化，这是非常正确的，那就作为课后作业给到大家去优化啦

下一步尝试求w11的偏导，这一次链式过程就稍微长了一些了，如以下示意图

有示意图，相信大家很容易就知道了上面这条表达式是如何写出来的。核心关键点就是倒推，看看w11在哪一级表达式中，然后再继续往上找，直到能到达C损失函数里去。这个过程就类似于已知树（图论的树）进行求到根的路径的过程。求导数的前面两项咱已经在w32求偏导中计算过了，其结果如下

接下来的各项的求导过程如下

将几个表达式合起来，即可计算结果

表达式虽然长，但拆开看却非常清晰，如下图所示

以上的各个变量参数都是已经计算出结果的，其整个表达式最终结果也是非常简单的小学计算题。计算结果是 0.000929 的值

写成代码如下

var dc_dw11 = (y2 - y_out) * (y2 * (1 - y2)) * w31 * (y0 * (1 - y0)) * a;

同理来求 w12 的偏导，接近和 w11 相同，其差别只有最后的一步计算。如下示意图所示

可见计算公式为

对应的代码实现如下

var dc_dw12 = (y2 - y_out) * (y2 * (1 - y2)) * w31 * (y0 * (1 - y0)) * b;

同理也可以继续求w21的偏导

通过以上示意图可知

各自代入可得

对应的代码如下

var dc_dw21 = (y2 - y_out) * (y2 * (1 - y2)) * w32 * (y1 * (1 - y1)) * a;

按照以上求偏导方式，可得

对应的代码如下

var dc_dw22 = (y2 - y_out) * (y2 * (1 - y2)) * w32 * (y1 * (1 - y1)) * b;

最后将各个权重减去对应的偏导，更新之后的权重我给它上面多标了一瞥

对应的代码如下

w31 = w31 - dc_dw31;
w32 = w32 - dc_dw32;

w11 = w11 - dc_dw11;
w12 = w12 - dc_dw12;

w21 = w21 - dc_dw21;
w22 = w22 - dc_dw22;

按照更新的值再跑一遍计算，可得到y2输出为 0.6820 的值，求损失函数为 0.0165 的值，可以看出比原来的第一遍计算得到的 0.0181 更小，证明更加贴近。好在我过程中顺带编写了代码，可以愉快地让计算机帮我跑个100次，跑了100次之后的各个值如下

w11=0.099497286575324431
w12=0.79870730833654868
w21=0.35650028026826369
w22=0.48814357783267731
w31=-0.30047225429264057
w32=0.32533602822418006
y2=0.50076396515258481
c=2.9182137718196697E-07

可见看到此时输出的 y2 已经非常贴近预期的输出了。于是大家可以开森地认为咱手算训练出一个能够当输入为 x0=0.35 x1=0.9时，获得0.5输出值的简单BP神经网络啦

相信看了整个过程的大家也能感受出来，本文选用的例子中所涉及的计算是非常简单的。再回头看看总的代码，可见实现代码量是非常少的

const double x0 = 0.35;
const double x1 = 0.9;

const double y_out = 0.5;

var a = x0;
var b = x1;

var w11 = 0.1;
var w12 = 0.8;

var w21 = 0.4;
var w22 = 0.6;

var w31 = 0.3;
var w32 = 0.9;

var count = 0;

while (true)
{
    var z0 = w11 * a + w12 * b;
    var z1 = w21 * a + w22 * b;

    var y0 = F(z0);
    var y1 = F(z1);

    var z2 = w31 * y0 + w32 * y1;

    var y2 = F(z2);

    var c = C(y2);

    if (c < 0.0000001)
    {
        break;
    }

    var dc_dw31 = (y2 - y_out) * (y2 * (1 - y2)) * y0;
    var dc_dw32 = (y2 - y_out) * (y2 * (1 - y2)) * y1;

    var dc_dw11 = (y2 - y_out) * (y2 * (1 - y2)) * w31 * (y0 * (1 - y0)) * a;
    var dc_dw12 = (y2 - y_out) * (y2 * (1 - y2)) * w31 * (y0 * (1 - y0)) * b;

    var dc_dw21 = (y2 - y_out) * (y2 * (1 - y2)) * w32 * (y1 * (1 - y1)) * a;
    var dc_dw22 = (y2 - y_out) * (y2 * (1 - y2)) * w32 * (y1 * (1 - y1)) * b;

    w31 = w31 - dc_dw31;
    w32 = w32 - dc_dw32;

    w11 = w11 - dc_dw11;
    w12 = w12 - dc_dw12;

    w21 = w21 - dc_dw21;
    w22 = w22 - dc_dw22;

    count++;
}

Console.WriteLine("Hello, World!");

double F(double x)
{
    return 1.0 / (1 + Math.Pow(Math.E, -x));
}

static double C(double y2)
{
    return 1.0 / 2 * Math.Pow((y2 - y_out), 2);
}

也许此时有人会说，明明我看到的py代码量更少，为什么换成C#的代码量就这么多了？别急，大家试试看回忆一下上文布置的课后作业。之所以网上看到的很多py实现的版本的代码量少，是因为使用了本文没有付出场费的矩阵来帮忙计算，许多重复的计算逻辑被封装起来了。试试看给以上的代码进行优化，将重复的计算进行合并，将重复的结构进行抽象，很好，此时相信大家一和py代码进行对比就会发现接近相同啦

本文代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 3621fbea66658c99f11ed4faa28aa60bb5ac4466

以上使用的是国内的 gitee 的源，如果 gitee 不能访问，请替换为 github 的源。请在命令行继续输入以下代码，将 gitee 源换成 github 源进行拉取代码。如果依然拉取不到代码，可以发邮件向我要代码

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 3621fbea66658c99f11ed4faa28aa60bb5ac4466

获取代码之后，进入 Bp/DewhigarjejelDaykogiqem 文件夹，即可获取到源代码

更多技术博客，请参阅博客导航

Windows 调试工具课程

Tue, 07 Apr 2026 22:01:52 +0000

Windows 调试工具课程——在软件万种死法中调试出原因

本文是我在集团内部上的课程记录而成的博客内容。在本次课程里面将和大家介绍一些在 Windows 上常用的调试工具，以及调查问题的常见套路。适合于伙伴们入门 Windows 调试

本文内容的组织方式是按照原本课程课件里面的一页页的内容组装而来的方式组织的，在过程中补充一些讲课时的内容

注：如果你看不到图片，请确保了允许 http 图片内容（Make sure enable Insecure origins treated as secure for my blog）

本次课程里面核心的内容是调试工具，调试工具是我们在调试软件的时候的利器，通过调试工具我们可以找到软件的问题，解决软件的问题

本次的课程的开始我来和大家讲一个调试故事，这个故事是从用户反馈软件用不了的问题开始的

用户说软件用不了，那可能会是什么问题呢？用户不是专业的开发人员，他们不知道如何准确的表述问题

学过软件工程的同学应该有不少，软件工程里面应该会有提到，开发的第一步也是非常关键的一步就是需求分析。当收到用户反馈说软件用不了时，用户在说什么呢？是不是可能是软件崩溃了？还是软件无法启动？还是其他的问题

遇到用户说软件用不了的时候，咱可以有哪些入手点呢？我的调查思路是分为两个大的方向。第一个方向是从当下的情况入手。如果当下已经没有了现场了，则可以考虑第二个方向，复现（重现）问题

从第一个方向入手时，可以先考虑从用户的设备上寻找痕迹。接下来我将和大家聊聊如何开始从用户的设备上寻找痕迹。当然了，如果这个用户是咱的测试人员或者是咱的同事，那寻找痕迹这一步就更有价值了

在用户设备上寻找痕迹时，别忘了 Windows 是咱的好朋友。Windows 提供了很多工具，可以帮助我们找到问题的原因。接下来我将和大家介绍一些 Windows 上自带的常用的调试工具

第一站就是事件查看器。可以先假设咱可能遇到的是软件启动即崩溃的问题。在不远程用户的情况下，可以先请用户发送系统事件日志或截图过来看看。事件查看器作为第一站的原因是可不发起远程，直接请用户截图或发送日志过来。相对来说对开发者的工作成本较低

通过事件查看器可以进行快速的分析，如看到软件崩的日志，那就可以证明确实是软件崩溃了。后续咱的调查方向就可以向着软件崩掉的方向进行

也有可能通过事件查看器直接看到非常有效的信息，直接就结束战斗，定位到了问题

举个栗子

有一次我在调试一个软件的时候，用户反馈说软件无法启动。我让用户发送了事件查看器的日志过来，通过日志可以看到如下内容

错误应用程序名称: lindexi.exe，版本: 5.1.12.63002，时间戳: 0xedd2d687
错误模块名称: MSVCR100.dll，版本: 10.0.40219.325，时间戳: 0x4df2be1e
异常代码: 0x40000015
错误偏移量: 0x0008d6fd
错误进程 ID: 0x994
错误应用程序启动时间: 0x01d50ac3bd970061
错误应用程序路径: C:\Program Files\lindexi\lindexi.exe
错误模块路径: C:\Program Files\PowerShadow\App\MSVCR100.dll
报告 ID: a0c5c0b1-76b7-11e9-9d20-94c69123de40

细心的伙伴也许一眼就看出来问题了，出现问题的是 MSVCR100.dll 模块，然而这个模块路径居然是在一个不认识的，名为 PowerShadow 的软件的目录下。这时候就可以大概确定问题了，这是被投毒了

试试用谷歌好帮手，搜搜这个软件是什么软件。刚好搜到了这篇博客：影子系统让 C++ 程序无法运行

于是这就结束战斗了，调查到了问题的原因，软件无法启动是因为被投毒了，被影子系统投毒了。解决方法就是请用户卸载影子系统，因为影子系统也不维护了，咱软件层没啥好挣扎的

可惜的是在很多用户的设备上，事件查看器日常不工作。没关系，能从事件查看器找到额外信息，就是赚到了

如果事件查看器找不到或不能用？咱还有其他很多工具可以用

寻找痕迹的时候，另一个常用的好工具就是任务管理器。任务管理器是 Windows 自带的一个工具，可以帮助我们了解到非常多的信息

通过任务管理器寻找痕迹时，可以按照如上图所示的决策树了解一下情况。如果不能在任务管理器里面看到进程，那很可能就是进程已经崩掉了。如果能够看到进程，那可能就是进程卡了。此时关注点可以是 CPU 使用率。如果 CPU 使用率不动，那可以猜猜可能是死锁问题，如果 CPU 使用率爆高，那可能是死循环等问题。同步也看一下内存使用率，虽然在任务管理器里面看内存使用率不能真实反映内存使用情况，但是可以作为一个参考。详细关于如何正确查看程序的内存使用情况，后面会有专门的内容介绍

无论是何种情况，都可以试试捞一个 DUMP 回来调试看看。当然了，对于软件崩掉的情况，先尝试一下是不是能启动起来，拼手的速度快速捞一个 DUMP 回来，如果不能，那后文还会和大家介绍其他工具来辅助捞 DUMP 文件

先回顾一下，咱的调查思路一开始就是尝试寻找痕迹。寻找痕迹的时候借助 Windows 里面提供的好用的工具，这里重点介绍的是事件查看器和任务管理器。通过事件查看器可以快速的了解到软件崩溃的原因，通过任务管理器可以了解到软件的运行情况

在通过自带的工具没有明确收获的情况下，则尝试捞一个 DUMP 回来开发机器上进行进一步分析

本课程这里提到的 DUMP 文件是指 Windows 下的内存转储文件，是一个二进制文件，简单用人话说就是将进程的内存内容保存到文件里面。通过 DUMP 文件可以有效还原出此时的进程的内存状态和内存里面的内容，可以用于进一步的分析。当用户环境里面没有带开发工具时，捞一个 DUMP 文件回来，可以帮助我们在开发机器上进行进一步的分析。捞 DUMP 分析的过程，相当于给进程做了一个快照，然后将其放在开发机器上进行进一步的分析

假设进程还在的话，那最简单的捞 DUMP 方式就是通过任务管理器右键选择创建内存转储文件了。对应的英文系统是 Create memory dump file 菜单项

这里需要额外说明的是，如果当前系统是 x64 系统，但是自己的进程是 32 位进程，那此时不建议使用默认打开的任务管理器捞 DUMP 文件。因为默认打开的任务管理器是 x64 的，打出来的是 x64 转储文件，包含 WoW64 子系统的信息。详细请看你生成的转储文件有问题吗？ - 知乎

正确的做法应该是使用 C:\Windows\SysWOW64\Taskmgr.exe 的任务管理器去捞 DUMP 文件

现在假定捞到了 DUMP 文件了，那接下来的步骤就是如何分析 DUMP 文件了。当然了，前置步骤就是如何将 DUMP 文件传回到自己的开发机器上，这里有一个小妙招就是将这个 DUMP 压缩一下。由于 DUMP 文件是内存转储文件，大部分都是全零的内容，压缩率非常高。如果需要通过网络等方式传输，那压缩一下再传输会快很多

分析 DUMP 的工具有很多，我着重要和大家介绍的是太阳系最强 IDE —— VisualStudio。VisualStudio 已经是一个成熟的 IDE 了，只需将 DUMP 拖进去就可以了，聪明的 VisualStudio 可以自动帮咱进行分析

一般而言，将 DUMP 拖入到 Visual Studio 里面，接着点击混合调试按钮即可。混合调试是使用托管调试和本机调试的组合。托管调试是指调试 .NET 程序，本机调试是指调试其他非 .NET 系的程序。混合调试是指同时调试托管和本机代码，因为一般而言 .NET 系的应用要在托管层崩溃是有点难度的，除非开发者自己比较缺乏处理。然而本机代码，如某些使用 C 、汇编、C++ 编写的程序，那就容易崩溃了。混合调试可以同时调试这两种代码。即使进程完全不是 .NET 程序，也可以使用混合调试来调试

进入混合调试之后，需要等待 Visual Studio 自动分析。如果是第一次调试 DUMP 文件的，可能会在下载符号这一步卡住一会。大家可以出去喝个茶，等待一下，再回来看看。实在等不急了，那就点击取消符号加载再继续吧

好的，现在咱的进度就是在用户侧发现了问题，且不能通过事件查看器等结束战斗。将用户的 DUMP 文件捞回来，通过 Visual Studio 进行分析。分析的方法就是将 DUMP 文件拖入 Visual Studio 里面，然后点击混合调试按钮。等待 Visual Studio 自动分析，即可看到分析结果

那聪明的 Visual Studio 会帮咱分析出什么内容呢？如何看 Visual Studio 的分析结果呢？常见的套路就是关注 Visual Studio 以下三个方面内容

调用堆栈
后文会介绍的 “三板斧” 内容
局部变量

先来和大家介绍一下调用堆栈。调用堆栈是个好东西，调用堆栈是一个非常重要的内容，可以帮助我们了解到程序是如何运行的。通过调用堆栈可以看到程序是如何运行的，是从哪个函数开始的，是如何调用的，是如何返回的。默认的 Visual Studio 调试布局里面，可以快速看到调用堆栈窗格

调用堆栈可以如何看？调用堆栈可以和着之前在用户端任务管理器所见内容进行一起分析。如在任务管理器看不见进程，即对应进程崩了的问题，可以通过调用堆栈尝试看到是谁带崩的，崩之前调用的是哪个函数。如果是在任务管理器能看到进程，但是 CPU 使用率不动，那可能是死锁问题，可以通过调用堆栈看到是哪个函数卡住了主线程或进入锁。如果是 CPU 使用率爆高，那可能是死循环问题，可以通过调用堆栈看到是哪个函数跑满了线程

举个真实的例子，以下就是我从用户端捞回来的一个 DUMP 文件。通过 Visual Studio 分析，崩溃之前的调用堆栈如下

>	00000000()	Unknown
 	[Frames below may be incorrect and/or missing]	Unknown
 	nvumdshim.dll!710d0745()	Unknown
 	nvd3dum.dll!5989f2e1()	Unknown
 	nvd3dum.dll!595f1716()	Unknown
 	nvd3dum.dll!596b7827()	Unknown
 	nvd3dum.dll!598a6233()	Unknown
 	nvd3dum.dll!5989b95c()	Unknown
 	nvd3dum.dll!5989c33b()	Unknown
 	nvd3dum.dll!598816bc()	Unknown
 	nvumdshim.dll!710ca40e()	Unknown
 	nvumdshim.dll!710cbb78()	Unknown
 	nvumdshim.dll!710ca17f()	Unknown
 	nvumdshim.dll!710ca0d3()	Unknown
 	d3d9.dll!5ab86f81()	Unknown
 	ntdll.dll!_NtWaitForMultipleObjects@20 ()	Unknown
 	KERNELBASE.dll!76f69723()	Unknown

通过调用堆栈可以看到是 nvumdshim.dll 模块带崩的。这个模块是 NVIDIA 显卡驱动的模块。通过这个调用堆栈可以看到是 NVIDIA 显卡驱动带崩的。这个问题的解决方法就是更新 NVIDIA 显卡驱动。此问题详细请看记因为 NVIDIA 显驱错误而让 WPF 应用启动闪退问题

驱动问题是客户端崩的常见问题，表现就是在很多用户电脑工作好好的，在某些用户就起不来

修复 DirectX 时，我常用的就是 DirectX 修复工具，此工具下载地址是： https://blog.csdn.net/VBcom/article/details/6962388

讲完了谁带崩的问题，接下来再看另一个案例。对应 CPU 不动的问题，如下图所示的调用堆栈

大家猜猜上面堆栈告诉咱什么问题

通过以上的堆栈可以知道进入了锁。此时的常见套路就是从上到下找找，找第一个咱自己程序集的调用函数，如这里就找到了是在 lindexi.dll 里面的方法。可以知道的是这个方法有逻辑在等待锁，且这个锁就不返回。此时配合代码食用更佳。咱这里能够知道进程卡住的原因是因为等待锁，且这个锁不返回，而至于这个锁在业务上是什么作用就需要咱进一步配合代码进行分析了

再来看看对应 CPU 爆高的一个案例，此时堆栈里面的信息可以告诉咱，现在正在跑的方法是哪些。有可能就是当前的调用堆栈的顶部的几个方法有逻辑跑满了线程了。同样，此时配合代码食用更佳

但有可能此时面对的情况是没有代码。如使用的是第三方库等，此时靠堆栈信息是不够的。先让大家思考这个问题，如果此时没有代码还可以如何进一步分析？我将在后文和大家介绍如何通过三板斧来进一步分析

回顾一下，这就是咱拖入 DUMP 文件之后，依靠 Visual Studio 里面的调用堆栈进行问题分析的常见三个案例。对应软件崩溃的问题，可以通过调用堆栈看到是谁带崩的。对应 CPU 不动的问题，可以通过调用堆栈看到是谁卡住了主线程。对应 CPU 爆高的问题，可以通过调用堆栈看到是谁跑满了线程

但是仅靠调用堆栈可能还是不够的，有时候需要更多的信息。接下来我将和大家介绍如何通过“三板斧”来进一步分析

这里介绍的“三板斧”分别是寄存器、反汇编、内存这三个方面的工具。通过这三个方面的工具可以帮助我们进一步的分析问题

需要说明的是用到这三个工具时仅仅只是在咱有需要了解更多状态信息的时候。而且通过这三个工具也不一定能够准确了解到问题的原因。这三个工具的使用本身不难，但是其难点确是这几个工具所见内容的背后大家关于程序本身的理解以及软件运行机制的了解。如果对于软件运行机制不了解，那这三个工具所见内容可能会让人难以理解，或者是调查方向跑偏

依然使用刚才的例子，当看到 CPU 爆高的时候，通过调用堆栈可以看到是哪个方法跑满了线程。但是这个方法逻辑跑满了，其原因是什么呢？调用堆栈可无法回答此问题

试试先在 Visual Studio 里面打开内存、寄存器、反汇编窗格。这三个工具可以帮助我们进一步分析问题

打开之后的 Visual Studio 的界面布局大概如上图所示

拿本课程的 CPU 爆高的例子，先通过反汇编发现了可能存在的问题，如想看看 rcx 寄存器里面存放了什么。通过寄存器窗格可以看到 rcx 寄存器里面存放了什么内容。通过内存窗格可以看到这个地址里面存放了什么内容。刚好就看到了对应的内存里面存放了一段逗比代码

使用 “三板斧” 本身的难度不大，但是其难点在于其背后的知识。如汇编知识，寄存器的机制，以及软件本身的运行机制。这部分知识远远超过了本课程能介绍的范围，需要大家自行学习，但由于这部分知识的学习成本较高，所以在实际工作中，这部分知识可能并不是必须的。我只敢推荐大家在有余力的情况下进行学习，如果平时工作已经很忙了学不过来了，那这部分知识还可以先放着。但是如果能够掌握这部分知识，那在调试问题时会有所帮助

继续和大家介绍 Visual Studio 的另一个调试工具——局部变量。局部变量也是个好东西，可以帮助我们了解到程序运行时的状态。通过局部变量可以看到程序运行时的变量的值，可以帮助我们了解到程序运行时的状态

如看到了错误之前的局部变量有一个名为 lastErrorCode 的变量，也许可以通过这个变量的值来了解到错误的原因。但是这个错误码是什么意思呢？这个错误码的含义在哪里找呢？咱可以试试 error 这个工具，这个工具可以自动帮助咱找到可能的错误码的含义。这是工具是微软整理的，绝大部分调用系统层的组件所见的错误码都可以在这里找到

工具下载地址： https://learn.microsoft.com/en-us/windows/win32/debug/system-error-code-lookup-tool

如在这里咱可以看到的错误信息是文件或文件夹名错误，根据咱的业务逻辑，可能是文件名错误导致的问题。那接下来的调查方向就是看看为什么出现错误的文件名了，这时候也许一看代码就理解了

再举另一个真实的例子，如看到的是如上图的异常导致的崩溃。根据咱通过搜索引擎了解到的知识，这个 WindowsCodecs.dll 是 Windows 系统的 WIC 多媒体解码层。可能此时遇到的问题和图片等多媒体的编解码有关

刚好在本例子里面，通过局部变量看到了出问题的图片的文件地址，此时的调查就更加有方向了。除了可能存在的 WIC 层的问题外，还可以是图片文件本身的问题。如图片文件投毒等问题

延伸一下，如何了解图片、音视频等文件是否被投毒了？这里推荐一个工具，通过 MediaInfo 工具可以帮助咱看到文件的许多信息

如这个文件就是一个假装是 png 的 WebP 文件，然后投毒将 WIC 层搞崩了

MediaInfo 工具下载地址： https://mediaarea.net/en/MediaInfo/Download

好像… 还是有些问题调试不出来

太阳系最强 IDE 也顶不住呀

那就试试上接近能调试一切的 WinDbg 吧

这个工具非常强大，只是有一个问题。那就是有亿点点上手门槛

在这里我告诉大家一个非常简单的方法，让大家瞬间就能学会上手使用 WinDbg 工具调试问题。方法就是请一个熟悉 WinDbg 的伙伴，让他帮你调试，找到一个工具人帮你使用 WinDbg 调试问题是最快能学会使用 WinDbg 的方法

回顾一下，以上咱就聊了在用户端发现问题，先尝试使用 Windows 自带工具快速进行定位问题。以及捞到 DUMP 文件之后，如何在开发机器上通过 Visual Studio 进行进一步分析。分析的方法就是将 DUMP 文件拖入 Visual Studio 里面，然后点击混合调试按钮。等待 Visual Studio 自动分析，即可看到分析结果。分析的重点是调用堆栈、三板斧、局部变量。通过这三个方面的工具可以帮助我们进一步的分析问题

如果 Visual Studio 还不能解决问题，那就找个工具人来帮忙使用 WinDbg 继续调查问题

这就是第一个大方向的内容

第二个大方向就是事后现场的复现问题。什么时候需要复现问题？比如最简单来说就是软件启动即崩溃，完全来不及打开任务管理器捞 DUMP 文件。这时候就需要复现问题了，通过复现问题可以帮助我们更好的定位问题

复现问题时也不是只是简单重复跑程序，而是可以通过更多的工具辅助来在复现问题时更好的定位问题

首要介绍的就是 ProcDump 工具

当使用任务管理器捞不到 DUMP 或不好捞 DUMP 时，使用 ProcDump 工具能够更好的帮助我们捞 DUMP 文件。ProcDump 工具是 Sysinternals 的工具，下载地址是： https://learn.microsoft.com/zh-cn/sysinternals/downloads/procdump

为什么说有时候不好使用任务管理器捞 DUMP 呢？因为现实往往很复杂。除了闪崩，软件启动即崩溃导致的手速不够快，捞不到 DUMP 文件之外，还有其他很多问题。比如软件就是处于似崩未崩的状态，期望抓到某个时机的状态，如软件一定会在某次 CPU 爆高之后不能符合预期工作，然而 CPU 爆高的时间非常短，靠人类去看去抓是有些废程序猿的。比如软件半夜崩溃，只有在午夜12点才会崩溃，这时候人类可能已经睡着了，即使没睡着，可能错过了这个时间点就要等明天的午夜12点了。再比如是非必现的问题，需要压测才能复现，期望自动化收集，否则可能要跑几千次才能复现一次，靠人类手工一次次一个个去捞的工作量有些大

通过 ProcDump 可以在程序万种死法中有效的生成 Dump 文件，只需使用好 ProcDump 的参数。具体参数作用可以参考微软官方文档和如何在 NET 程序万种死法中有效的生成 Dump (上) - 一线码农 - 博客园

这是一个小游戏，让大家连连线，看看在什么情况下应该使用什么方法

在调查思路这里，复现问题时经常伴随使用 ProcDump 工具，因为 ProcDump 工具可以在非常多的情况下帮助我们捞 DUMP 文件

复现问题时，不仅只有 ProcDump 工具。还有可能面对的是事后现场的情况，此时需要使用更多的工具来辅助定位问题。以及当没有调查思路时，可以试试常见的问题的探索帮助寻找思路

来和大家讲讲事后现场的调查

什么是事后现场？事后现场问题在这里一般说的是当前的现场或能复现所抓取到的现场已经不是问题发生的现场，而是发生问题之后的现场了

比如找到问题了，但问题非本质问题。常见的就是通过 DUMP 分析是如空异常的情况，导致崩溃的原因是因为空指针异常。但是空指针异常是如何产生的呢？这时候就需要通过事后现场分析思路调查来进一步分析问题

比如发生问题的地方不是产生问题的地方。如本课程的例子里面，崩溃原因是一张假装 png 的 WebP 图片，那这张图片是哪里来的，为什么会使用这张图片。如果此时代码逻辑没有帮助的话，那就需要进一步通过复现问题调查事前现场来进一步分析问题

比如系统性的问题。常见的就是团伙作案，不是单个应用导致的问题。这类问题的难度在于其复杂度，可能难以抓到正确的现场。此时也需要通过多次复现问题，抓取更多的信息，通过事前和事后现场的分析来进一步分析问题

面对事后现场和团伙作案等问题，采用微软极品工具箱的 Process Monitor 工具，配合 DebugView 工具通常都能有不错的收获

Process Monitor 工具下载地址： https://learn.microsoft.com/zh-cn/sysinternals/downloads/portmon

Debugview++ 工具开源地址： https://github.com/CobaltFusion/DebugViewPP

DebugView 工具下载地址： https://learn.microsoft.com/en-us/sysinternals/downloads/debugview

从界面和交互上，DebugView++ 比 DebugView 更好用一些

举个真实栗子来和大家演示多个工具之间的配合使用来调用一个有趣且复杂的问题

这个问题的开始是测试同学和我报告了触摸失效问题，后来经过进一步调查发现其实是 explorer 未响应问题，表现就是 explorer 迷之闪黑

这个问题复杂之处在于 explorer 不是咱的，咱也不熟悉，也不知道是什么导致的。而且 explorer 太庞大了，捞到 DUMP 分析压力过大，耗时耗力。需要使用更多的工具辅助进一步分析问题

此时通过 Process Monitor 工具抓取 explorer 进程信息，发现了如上图的有趣的内容。里面很受我关注的就是存在了进程退出

通过网上四处搜发现 explorer 是一个多进程软件，进程的退出和迷之闪黑可能有所影响。既然进程退出了，那就试试上 ProcDump 工具在进程之前之后抓一个 DUMP 文件回来分析

由于 explorer 十分庞大，且咱也不熟悉 explorer 的代码，来回抓了几次 DUMP 分析都没有什么收获。直到某次抓取到了一个有趣的 DUMP 文件，通过这个 DUMP 文件发现了在进程退出之前的调用堆栈里面包含了 Shell32 的一些调用

再根据前面的 Process Monitor 工具抓到的在进程退出之前碰的是 Realtek Bluetooth 蓝牙模块，于是重心就在 Shell32 和蓝牙一起组合上面

既然大概定位到这里，那就继续上 ShellView 工具。通过 ShellView 工具进行大量的 Shell32 组件的禁用，我的做法大概就是看哪个不开森就禁用哪个，进行二分法的禁用，最终发现了是 Realtek Bluetooth 蓝牙模块导致的问题

二分法的禁用就是先一口气禁用一半的组件，看看问题是否解决。如果解决了，那就说明问题在这一半里面。如果没有解决，那就说明问题在另一半里面。然后再在这一半里面继续二分禁用，直到找到问题所在

经过以上的调查工具可以了解到是蓝牙相关模块的问题，集中火力找到明确的调试方向，很快就找到是蓝牙驱动的问题

详细的调试内容可比这里介绍的有趣的很，请看记一次调试资源管理器未响应经验

以上的案例里面 Process Monitor 立了首功，通过 Process Monitor 工具抓取了 explorer 进程的信息，发现了进程退出的信息，以及退出之前访问了蓝牙相关模块，最终通过 ShellView 工具禁用了蓝牙模块定位到了具体模块导致的问题。在许多事后现场问题中，都会使用 Process Monitor 工具配合复现，尝试找到故障之前的事前发生了什么，了解故障之前的行为。进而可以缩小定位问题的方向

Process Monitor 工具适用于辅助调试不熟悉的应用、复杂的情况，通过了解其行为来辅助缩小定位范围，提高调试效率。同时 Process Monitor 工具可以一口气抓多个进程的信息，也常用于辅助定位进程们团伙作案问题

以上就是调查思路里面的第二大方向的事后现场的内容。其思想核心就是通过复现配合工具抓取现场信息，通过现场信息进一步分析问题

有时候调查问题过程中没有头绪，没有思路。此时可以还可以试试一些常见问题的探索，尝试通过这些常用问题套路和经验找到入手点

这些常见的工具可以帮助我们进行一些常见问题的排查。有时候开发任务紧张，没有充足的时间进行全面的调查，通过常用的套路也可以提高定位效率，不一定我们需要来一次全面的调查，有可能只通过现象和猜测，配合常用套路就能找到问题的原因

这些常用工具和套路被我成为更多的调试工具，分为以下多个方面：

系统环境问题-依赖缺失等问题
内存问题，包括 OOM 系问题
注册表相关模块
窗口相关模块
键盘等等

这些方面都可以作为常见问题的入手点探索方向

先来聊聊依赖缺失问题

依赖缺失的表现行为很明显，一般就是程序猿常说的，“在我电脑上明明就是好的，为什么到你电脑上就不行了”这类的话，那就可以第一时间怀疑是依赖缺失问题。或者是软件无法启动，启动即崩溃，这类问题也可以怀疑是依赖缺失问题。或者是软件开始能跑，但是跑到某个模块就崩溃了，且很固定的到某个功能模块就崩溃，那此时也能怀疑是依赖缺失问题

有些不熟悉 Windows 的伙伴也许有这样的问题，明明自己写的应用似乎就没有什么依赖，为什么还可能遇到依赖缺失的问题呢？这是因为 Windows 系统本身就是一个依赖系统，很多功能都是通过依赖来实现的。比如说一个最简单的例子，你写了一个 C# 程序，但是你的 C# 程序里面调用了一个 MessageBox 函数，这个 MessageBox 函数是 Windows 系统的一个函数，你的 C# 程序调用了这个函数，那你的 C# 程序就依赖了 Windows 系统的 MessageBox 函数。如果你的 C# 程序在别的电脑上运行，别的电脑上没有这个 MessageBox 函数，那你的 C# 程序就会崩溃。软件运行过程中，需要依赖许多组件，包括直接依赖和间接依赖。有可能在代码编写阶段没有引入依赖，但实际上软件已经带上了许多隐式依赖内容，如常见的 C++ 程序需要的 VC++ 运行时依赖等等。这些依赖可能会在复杂的用户环境里遭遇投毒问题，导致软件无法正常运行

依赖缺失问题首推是采用 Dependencies 工具，使用这个工具可以帮助我们定位两种类型的问题：

是否在目标机器上依赖缺失问题
是否在目标机器上的依赖被投毒

Dependencies 工具开源地址： https://github.com/lucasg/Dependencies

识别依赖缺失问题的方法就是将自己的应用拖入到 Dependencies 工具里面，然后看看是否有缺失依赖的提示。如上图所示，可以看到这个应用缺乏了一个名为 Lindexi.dll 的依赖。此时可以看看输出文件里面是否真的包含了这个依赖文件，如果没有，那就说明这个依赖确实是缺失的。如果有，那再看看这个依赖文件的二进制是否符合预期，如可能被修改或者下载不全等问题

常用的依赖缺失调查方向套路是看看是否有 C++ 运行时系列的丢失。其中 C++ 运行时系列常见的就是 VC++ 的多个版本的分发库，或者是 VC++ 运行时，即 vcruntime140.dll 文件。以及 msvcp140.dll 文件缺失。其中重点需要说明的是，如果能看到有 vcruntime140d.dll 文件的依赖，那就证明开发侧存在问题，这里的 vcruntime140d.dll 的意思是 VC++ runtime 14.0 debug 版本的 dll 的意思。如果看到有这个 dll 的依赖，证明你的相关方提供给你的 C++ 库是使用 Debug 版本构建的，这是不能给到用户端的。最佳方法是重新让其构建一个 Release 版本的 DLL 给你。只有在实在没有办法的时候，才考虑在用户端配上开发环境

另一个就是看看是否有 ucrt 系列的丢失，这个常见就是软件能在 Win10 上跑得好好的，在 Win7 上就启动不了。常见就是缺失了 ucrt 系列的依赖。如果是遇到这种问题，简单的做法就是将这些文件拷贝到软件运行目录下，或者是将这些文件打包到软件的安装包里面即可

最后一个就是看看是否有某些仅在开发机才有的负载，如我就喜欢引用一个名为 Lindexi.dll 的文件，这个依赖文件只在我的电脑上存在，用户设备上是绝对没有的，那自然在用户设备上跑不起来也就符合预期了

使用 Dependencies 工具除了找依赖缺失之外，还可以用来找到是否被投毒的问题。如上图所示，看大家是否能够快速看出来问题

是的，上图里面包含了一个名为 vcruntime140.dll 文件，包含这个文件是正常的，但是不正常的地方在于其路径。为什么 vcruntime140.dll 加载的居然是在 C:\Program Files (x86)\Foo 文件夹里，这就证明被投毒了。大家可以在工具里面看看有没有存在不熟悉或奇怪的路径，如果有，那就可能是投毒的问题？这个问题就需要进一步的调查了

如我记录的影子系统让 C++ 程序无法运行这篇博客提到的就是非常标准的被投毒的问题，大家可以看到 MSVCR100.dll 加载的路径是在 C:\Program Files\PowerShadow\App 文件夹里面

以上就是常用套路里面的调查依赖缺失问题，不仅仅可能是崩溃等问题，有时候软件运行功能不正常也可以看看是否有依赖缺失或被投毒的问题

额外地，也可以使用 sxstrace 工具辅助定位启动不了的问题。只是从直观程度上讲，采用 SxsTrace 工具需要去爬日志，不如 Dependencies 工具来得简单。但 SxsTrace 工具能分析更多其他维度上的问题，如果 Dependencies 不能定位到问题，也好来试试系统自带的 SxsTrace 工具进行分析

继续看一下内存问题

对 Windows 内存机制不了解的伙伴也许常常会拿任务管理器里面看到的内存数值当成衡量应用软件运行占用内存的标准。比如我说软件已经 OOM 了，但是对Windows 内存机制不了解的伙伴拿出任务管理器一看，发现应用软件才占用 300MB 内存而已，于是就完全不相信可能存在的 OOM 问题

这里说的 OOM 问题指的是 OutofMemory 经典问题，直接表现就是内存不足了，代码里面想要申请内存但是申请内存失败

在开始聊这个话题之前，需要先做一点点科普。如果大家想要看一个符合客观事实的应用软件运行过程的内存使用情况，应该使用 VMMap 工具查看，而不是任务管理器。任务管理器只能当成一个快速查看的工具，而不是一个准确的工具。VMMap 工具可以帮助我们查看应用软件的内存使用情况，包括了虚拟内存、物理内存、私有内存、共享内存等等

VMMap 工具下载地址： https://learn.microsoft.com/zh-cn/sysinternals/downloads/vmmap

应用软件的内存使用是一个相对复杂的话题，不仅仅是看看占用了多少内存就能判断的。因为事实上一个应用软件的运行占用内存是需要分至少三个维度去看的。最直接的维度就是私有内存和共享内存的占用。一般而言，对于共享内存的占用咱是不做多关注的。另一个维度是内存使用种类。其中开发人员在进行应用软件的内存优化时，常常直接触碰的应该就是 Private Data 的 Private 部分。即前面两个维度里面的私有内存和 Private Data 种类。以及 Stack 的 Private 部分。而至于如 Image 等部分，就常常不是开发人员所关注的。这里需要对 Image 特别说明的是，这个单词在这里的意思不是图片的意思，至少不是类似于 png 或 jpg 图片的意思，而应该是内存映像之类的意思，常见的就是所加载的库。有时候可以看到这部分的 Size 大小非常大，这是没有问题的，非常正常的。比如说软件加载了显卡驱动模块，这个模块的 DLL 文件一下值就几百 MB 大小，这部分就直接被统计到 Image 部分里面，所以说这部分一般情况下不是开发人员所关注的

最后一个维度就是是否在 WorkingSet 里面。在 VMMap 工具里面的 WorkingSet 被缩写为 WS 单词。简单但不准确的理解 WorkingSet 工作集就是物理内存占用量。相信大家都知道 Windows 上有可放在硬盘上的虚拟内存和放在内存条里面的物理内存的概念。可以认为 WorkingSet 就是物理内存占用量。详细的概念请看官方文档： https://learn.microsoft.com/zh-cn/windows/win32/memory/working-set

在任务管理器里面常常看到的就是 WorkingSet 的占用量。但是这个占用量并不是准确的，至少可能一次 EmptyWorkingSet 就可以将大量的在物理内存里面的内存转换到硬盘上。于是单纯靠任务管理器里面的内存占用来尝试衡量应用软件的内存使用情况是不准确的。特别是在调查 OOM 问题以及对比多个应用软件的内存使用情况时，任务管理器里面的内存占用是不具备参考意义的，看任务管理器里面的内存占用会被误导

额外聊一个小知识，如果你的用户半懂不懂，想要在任务管理器里面看到的内存很低。那简单的做法就是定时调用一下 EmptyWorkingSet 函数好了。据说 360 加速球就是这么做的

常用的调查套路里面，可以使用 VMMap 工具来查看应用软件的内存使用情况，看看软件当前现场是否有内存使用异常的情况。此时需要关注点可能还需要包括碎片化问题，内存泄露问题。碎片化问题指的是尽管内存还有空间余量，但是申请内存却失败了，因为内存虽然够但是碎片化的存在，无法找到连续的内存空间。内存泄露问题指的是内存申请后没有释放，导致内存占用越来越高的问题

额外说明一个知识点，对于 32 位进程来说，用户态能使用的内存就是 2 GB 空间。一旦发现应用软件已经用了接近 2GB 的内存空间，则可以认为这个软件可能已经发生了 OOM 问题了。因为配合碎片化问题的存在，接近 2GB 的内存空间就有可能存在无法申请足够的连续的内存空间而导致 OOM 问题。一旦发生了 OOM 问题，可能会导致软件进入非预期逻辑分支，如本该初始化的逻辑没有初始化，导致后续访问出现空异常等问题

这些时候，配合 ProcDump 一起食用效果更好。如果通过 VMMap 工具感觉到可能是内存问题，那此时通过 ProcDump 抓一个 DUMP 文件回来分析，可能会有更多的收获

通过 VMMap 不仅可以查看应用软件真实内存是怎样，还可以在用户设备上进行简单的调试。如追踪软件启动，找到是哪个模块在申请内存。因为很有可能只有在某个用户的设备上才会存在问题，那在对应的用户的设备上跑 VMMap 寻找申请大量内存的模块是非常有帮助的

通过 VMMap 也可以看到是否有内存碎片化的存在，即内存空间一看就发现出现非常多的碎片化的情况

当然了，对于 dotnet 系的应用来说，别忘了还有 dotMemory 这个好用的工具。这个工具既可以在用户设备上跑起来，抓取到应用软件运行内存的 dotnet 系信息，还可以对捞回来的 DUMP 文件进行分析。这个软件的交互做的非常好，有可能大家看界面就知道如何使用了

通过 dotMemory 工具可以看到各个模块的内存申请情况，各个类型存在内存的数量，以及各个类型的引用情况。适合于寻找内存泄露问题以及通过内存情况反推出软件的代码运行逻辑

在聊到内存 OOM 相关问题时，一个会被开发者忽略的点是可能遇到的是爆 GDI 对象的问题。试试打开任务管理器，在选择列里开启 GDI 对象列，看看进程占用的 GDI 对象有多少

许多的 GDI 对象所占用的内存都不计入到进程里面，这就导致了进程看起来没有使用多少内存，但是系统全局的内存却是不足了。或者是进程使用了大量的 GDI 对象，导致了许多 GDI 相关函数调用失败，而通过 LastErrorCode 获取到的错误被翻译为 OOM 相关错误，进而表现出 OOM 现象

此时可以通过任务管理器快速确定是否是 GDI 对象爆炸问题，然后通过 GDIView 工具查看 GDI 对象的使用情况。GDIView 工具可以帮助我们查看系统全局的 GDI 对象使用情况，以及每个进程的 GDI 对象使用情况

根据官方文档可以知道，使用 GDI 的应用程序限制为每个进程 10240 GDI 句柄，每个会话 65536 个 GDI 句柄。原因是 Windows 在内部使用 16 位 WORD 来存储每个会话的句柄索引

GDIView 工具下载地址： https://www.nirsoft.net/utils/gdi_handles.html

举一个实际的案例，我的师兄写了一个程序，这个程序会不断使用 GDI 获取屏幕截图，此时获取到了大量的 Bitmap 对象，导致了系统资源大量被消耗，反过来导致可用物理内存不足，最终导致了 OOM 问题

通过任务管理器看到我的师兄的程序的 GDI 对象十分多，再通过 GDIView 工具看到了大量的 Bitmap 对象，如此即可快速找到入手点。经过和师兄沟通发现可能是截图相关模块存在 GDI 对象泄露问题，反复复现和截图模块相关逻辑，看到任务管理器的 GDI 对象数量不断添加，就快速定位到了问题

以上就是本课程介绍的 OOM 问题的常用调查套路和工具。使用 VMMap 工具了解真实的内存是怎样的，避免被任务管理器误导。可在用户设备上跑 VMMap 工具了解到是哪个模块申请了大量内存，以及是否存在内存碎片化问题。使用 dotMemory 工具了解到 dotnet 系的内存使用情况，以及可能存在的内存泄露问题。如果内存没有问题，那就多看一下 GDI 对象的使用量，使用 GDIView 工具了解到 GDI 对象的使用情况

内存是一个复杂庞大的话题，本课程这里只和大家介绍了一些常见的简单情况，希望能给大家在没有调查思路的时候提供一些入手点

接下来来看看 Windows 系上特有的一个问题，注册表问题

注册表问题也是一个常被 Windows 开发新手忽略的问题。有些开发者有疑惑说，我的应用代码里面明明都没有碰到注册表，为什么还可能会有注册表相关问题。其实跑在 Windows 上的程序，无论如何都会碰到注册表的。从软件进程的启动开始就在碰注册表，后续的加载 COM 组件等，都会涉及到注册表。注册表问题可能会导致软件无法启动，启动即崩溃，启动后功能不正常等问题

注册表问题可能有些深奥，本课程这里只介绍一个简单的真实案例。我发现我的 Notepad 记事本软件启动就炸掉了，不知道为什么。我通过 Process Monitor 工具抓取时，发现了其注册表有以下有趣的行为。这里就是非常靠近软件进程退出的地方

由于 Process Monitor 工具抓取注册表行为时非常刷屏，降低大家的难度，我将有问题的一行日志选择了出来，看看大家是否猜到问题

其实这个案例里面我的调查是靠经验的，这里刚好是我上回学习 COM 组件劫持时所投的毒。可以试试将注册表的各个访问项在搜索引擎里面搜索一下，看看是否有人说这个注册表项是有问题的。如果有，那就可以尝试根据网上提供的方法进一步定位问题

以上案例的详细内容请参阅后门及持久化访问4—-Com组件劫持 - 浅笑996 - 博客园

相信刚才通过 Process Monitor 工具大家也感受到了被注册表刷屏的恐惧。如果应用软件的表现行为是第一次能跑，第二次就不能跑，且可能是和注册表有关的时候。此时可以尝试一下 RegistryChangesView 和 whatchanged 工具，通过这些工具可以快速帮助大家找到从事前到事后注册表的变化情况，减少刷屏的影响，提升调查效率

RegistryChangesView 工具下载地址： https://www.nirsoft.net/utils/registry_changes_view.html

whatchanged 工具下载地址： https://www.majorgeeks.com/files/details/what_changed.html

通过 RegistryChangesView 和 whatchanged 工具配合找到注册表变更项，再通过 Process Monitor 工具进一步辅助定位，可以了解到是哪个进程改了注册表，改了什么内容以及在什么时候改的。这样就可以帮助大家更好找到问题的入手点

注册表相关问题如果深入了解还是非常有深度的，本课程这里只介绍了一个简单的案例。希望大家能够通过这个案例了解到注册表问题的存在，以及通过 Process Monitor 工具，RegistryChangesView 和 whatchanged 工具等工具帮助大家更好的调查注册表问题

接下来看看窗口相关模块的问题

回到一开始的用户反馈的软件用不了的问题，经过咱的一番排查，发现了软件的进程没有崩溃，没有异常，没有依赖问题。捞一个 DUMP 回来也看不到问题，即无论是在 Visual Studio 里面分析还是在 WinDbg 里面分析都看不到问题。那此时就可以怀疑是窗口相关的问题了

如上图所示，大家猜猜进程还在，但是用户打开的软件却啥都没有发生，可能会是什么问题？

细心的伙伴也许一眼就看到了，这个窗口的 Top 在 -1000 坐标里面。这就有趣了，如果刚好用户的屏幕分辨率不够大，那这个窗口就会被放到屏幕外面去了。此时用户打开软件，软件进程还在，但是用户看不到软件的窗口，自然就以为软件打不开用不了

调查窗口相关问题时，使用少珺提供的 WindowDebugger 窗口调试神器可以调试 Win32 窗口的十分多方面的内容。这个工具可以按照多个策略搜寻窗口，如进程名、窗口句柄、窗口标题等等。搜到了窗口之后，可以看到 Win32 窗口的各个信息，如上图界面显示的窗口坐标、窗口大小、窗口标题等等。此外，还可以看到窗口的父窗口、子窗口，以及窗口的样式属性等等信息

更棒的是 WindowDebugger 窗口调试神器可以更改窗口的各项属性，处理辅助调试之外，还可以用作开发工具，用于在开发侧了解窗口的各项属性，方便开发人员调试窗口相关问题

WindowDebugger 窗口调试神器开源地址： https://github.com/kkwpsv/WindowDebugger

继续回到了用户反馈的问题的这个故事上，经过了鸡飞狗跳的调试，发现了窗口之所以非到 -1000 的坐标的原因是因为有业务逻辑写了有趣的代码，判断当窗口失去焦点的时候，将窗口坐标设置到了 -1000 的位置。于是故事里的开发工程师就很疑惑了，为什么用户双击这个软件的时候，还会有其他软件来抢窗口

在 Windows 上开发的时候，特别是开发全屏软件，任务栏被弹出来也是一个令人烦恼的事情。虽然有 WPF 稳定的全屏化窗口方法提供了十分稳定的方法，但是对于某些一闪而过的过来打扰的窗口，还是会降低用户的观感的

故事里的开发工程师就想找到一闪而过的窗口具体是哪个窗口。由于窗口是一闪而过的，用 WindowDebugger 窗口调试神器抓不到。此时可以使用 Walterlv 开发的 Walterlv.ForegroundWindowMonitor 工具。这个工具可以实时输出焦点窗口的信息，包括窗口的标题、窗口的句柄、窗口的坐标等等。通过这个工具可以实时输出焦点窗口的信息，方便开发人员调试窗口相关问题

如上图就打开了实时输出焦点窗口工具抓取到了是一个翻译工具一闪而过，既然知道了一闪而过的窗口，那顺着窗口提供的信息，就可以进一步调查了

实时输出焦点窗口工具开源地址： https://github.com/walterlv/Walterlv.ForegroundWindowMonitor

用户报告的问题总不是只有一刀，故事里的开发工程师很开森卸掉了翻译工具之后，发现虽然自己的窗口起来了，能被看到了。但是似乎无法接收任何按键输入，十分奇怪

故事里的开发工程师先是打开 VisualStudio 自带的 Spy++ 工具，用 Spy++ 工具抓取自己的窗口，然后监听窗口消息。发现了键盘消息都没有被自己的窗口接收到，再通过 Spy++ 爬窗口树才发现了自己在主窗口之上盖了一个窗口且让主窗口失去了焦点。于是开发工程师就很开森的优化了一顿代码，看起来一切都正常了

然而有趣的是，更新之后的软件给到了用户玩了一会，用户就又来报告说过一会窗口就不见了。开发工程师经过了一顿调查发现没有异常，无论是 Visual Studio 还是 WinDbg 都抓不到任何的异常，且软件进程也还在。用 WindowDebugger 窗口调试神器却找不到进程的主窗口。看起来似乎是窗口被关闭了。用 Spy++ 抓取消息时，似乎发现窗口是被键盘消息退出的

开发工程师打开了 KeyCastOW 键盘显示工具，尝试抓取一下键盘消息，结果就看到了 Alt-F4 快捷键被按下。这是一个非常通用的关闭窗口的快捷键。下一步就是找找看是不是有有趣的键盘设备、或模拟键盘设备、或某些奇怪的软件发送了键盘消息了，可以尝试拔掉各种外设以及结束各种进程，来看看是否还会有软件发送键盘消息

CastOW 键盘显示工具开源地址： https://github.com/brookhong/KeyCastOW

如果使用 Key CastOW 工具还是抓不到键盘消息，可以使用更狠的驱动级的 OpenArk64 工具。这个工具是驱动级的，我自己实际使用过程中发现会蓝屏，大家如果要玩这个工具的话，推荐在沙盒里面玩。OpenArk 是一款非常强大且好用的工具，我十分喜欢这个工具，也推荐大家去玩玩这个工具。在一些用户的设备上，有某些恶意广告软件会注入模块，然而这些广告软件写的不咋稳定，最终会导致进程炸掉。用 OpenArk64 在用户设备上定位模块也是一个不错的选择。使用 OpenArk64 集成的许多功能，可以在没有思路的时候这点点，那点点，也许就能找到更多线索

OpenArk64 工具开源地址： https://github.com/BlackINT3/OpenArk

故事的最后，开发工程师终于找到了是一个有趣的触摸屏幕在假装自己是一个键盘，且当用户触摸到触摸框的边缘的时候，自动发送 Alt-F4 键盘消息。于是开发工程师就很开心的将这个触摸屏幕砸了，软件就再也没有出现过一闪而过的窗口，也再也没有出现过窗口被关闭的问题，因为这个屏幕就再也没亮过，手动滑稽

如果一个问题是纯软件层的问题，那调试难度可能就已经很高了。再加上可能存在的硬件相关的问题，那调试难度就更高了。这就是为什么开玩笑说故事里面的开发工程师要砸掉触摸屏幕的原因

以上就是本课程介绍的窗口系常用的工具，包括 WindowDebugger 窗口调试神器、Walterlv.ForegroundWindowMonitor 实时输出焦点窗口工具、KeyCastOW 键盘显示工具、OpenArk64 驱动级的键盘消息抓取工具

窗口系相关问题的调试是有比较多 Win32 窗口相关前置知识点的，这部分知识需要大家平时积累

且在 Win32 非常复杂的窗口属性里面，多个不同的属性的组合以及窗口之间的关系组合，可能有很多都是网上难以搜到的特殊情况。通过 WindowDebugger 窗口调试神器辅助调试，尝试开关多个不同的属性，很多时候也可以减少问题的范围面，提升调查效率

常见问题除了这些之外，还有许多专项的问题。比如网络系问题、触摸系问题、音视频系问题、DPI和DWM相关问题、数据库相关问题等等。其他专项问题都有比较明确的特征，不会说需要探索一下摸索一下，有比较特征的问题可以直接使用专项工具进行调查。本课程就不在这里展开

以上就是本课程里面介绍的常用调查套路和工具。包括了从当下的现场出发，再到复现步骤过程中配合抓取更多信息的工具，最后到一些常见的问题的寻找入手点。但往往有很多现实遇到的问题都是十分复杂的，需要一步步进行调查，逐步深入，让我来和大家介绍一个我的终极方法

小黄鸭调试法是终极方法，当自己完全没有思路的时候，不妨找只小黄鸭聊聊天。和小黄鸭说说自己所遇到的问题，问题的表现行为，以及用了哪些调试工具，这些调试工具的结果是如何的，自己有什么猜测。很多时候，当自己和小黄鸭说完之后，自己就会有新的想法，甚至直接就找到了问题的入手点

小黄鸭没有被限定为一只小黄鸭玩具，也可以是某个工具人，或者是某个人工智障。有时候找个工具人聊聊天，也会有意想不到的效果

小黄鸭调试法是一个软件工程里面很有名的调试方法，详细请参阅 https://zh.wikipedia.org/wiki/%E5%B0%8F%E9%BB%84%E9%B8%AD%E8%B0%83%E8%AF%95%E6%B3%95

以上就是本次课程的内容，希望大家能够通过这次课程了解到一些常用 Windows 调试工具的使用方法，以及了解到一些常用的调试套路。希望能在实际的软件开发调试过程中有所帮助

如有工具下载失败，可发邮件向我要工具

更多 dotnet 系的代码调试方法请参阅： dotnet 代码调试方法

更多技术博客，请参阅博客导航

Vortice 使用 DirectComposition 显示透明窗口

Tue, 07 Apr 2026 22:01:41 +0000

通过 DirectComposition 配合 WS_EX_LAYERED 或 WS_EX_NOREDIRECTIONBITMAP 窗口样式，可以让窗口高性能地背景透明，完全依靠 DWM 将窗口背景和桌面画面合成

本文是渲染相关系列博客中的一篇，该系列博客已按照逻辑顺序编排，方便大家依次阅读。如您对渲染相关感兴趣，可以通过以下链接访问整个系列：渲染相关系列博客导航

在 DirectX 使用 Vortice 从零开始控制台创建 Direct2D1 窗口修改颜色博客中和大家介绍了最简方式创建了窗口和对接了 DirectX 层。在此基础上，大家也能看到此时创建的窗口是无法应用透明背景效果的

即使强行设置 SwapChainDescription1.AlphaMode 为 AlphaMode.Premultiplied 也会在 IDXGIFactory2.CreateSwapChainForHwnd 报错：

DXGI ERROR: IDXGIFactory::CreateSwapChain: Alpha blended swapchains must be created with CreateSwapChainForComposition, or CreateSwapChainForCoreWindow with the DXGI_SWAP_CHAIN_FLAG_FOREGROUND_LAYER flag.

传统 Win32 应用可以通过 UpdateLayeredWindow 方法设置窗口透明，然而 UpdateLayeredWindow 是有比较大的性能代价的，详细请参阅 WPF 从最底层源代码了解 AllowsTransparency 性能差的原因

性能较好的透明窗口实现可参阅 WPF 制作支持点击穿透的高性能的透明背景异形窗口

以上是在 WPF 框架里面帮忙封装好的，现在咱只有纯控制台，需要自己手动干一些活

为了方便大家阅读，本文将重新从零控制台开始，先创建好 WS_EX_LAYERED 的窗口，再将 DirectX 对接上去。总代码控制在 500 行左右。额外，为了方便 Win32 方法调用，本文还请出了 CsWin32 库，详细使用方法请参阅 dotnet 使用 CsWin32 库简化 Win32 函数调用逻辑

在本文的追加部分内容，补充了 DirectComposition + WS_EX_NOREDIRECTIONBITMAP 制作带标题栏的透明窗口内容方案

准备工作

按照 .NET 惯例，先安装一些库。本文的 D2D 基本没有戏份，仅用于绘制一点用于辅助测试的内容，本身此技术就和 D2D 无关

  <ItemGroup>
    <PackageReference Include="Vortice.Direct2D1" Version="3.8.2" />
    <PackageReference Include="Vortice.Direct3D11" Version="3.8.2" />
    <PackageReference Include="Vortice.DirectComposition" Version="3.8.2" />
    <PackageReference Include="Vortice.DXGI" Version="3.8.2" />
    <PackageReference Include="Vortice.Win32" Version="2.3.0" />

    <PackageReference Include="Microsoft.Windows.CsWin32" Version="0.3.257">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>

安装之后的 csproj 项目文件代码如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <IsAotCompatible>true</IsAotCompatible>
    <PublishAot>true</PublishAot>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Vortice.Direct2D1" Version="3.8.2" />
    <PackageReference Include="Vortice.Direct3D11" Version="3.8.2" />
    <PackageReference Include="Vortice.DirectComposition" Version="3.8.2" />
    <PackageReference Include="Vortice.DXGI" Version="3.8.2" />
    <PackageReference Include="Vortice.Win32" Version="2.3.0" />

    <PackageReference Include="Microsoft.Windows.CsWin32" Version="0.3.257">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>

如以上代码所示，本文提供的代码也是 AOT 友好的。在我的测试中，构建的 32 位的程序只需 2.12 MB 的体积。如果不知道本文的项目是如何组织的，可以在本文末尾找到本文全部代码的下载方法，拉取代码了解更多细节

添加 NativeMethods.txt 文件，添加以下内容，让 CsWin32 辅助生成一些代码

EnumDisplayMonitors
GetMonitorInfo
MONITORINFOEXW
EnumDisplaySettings
GetDisplayConfigBufferSizes
QueryDisplayConfig
DisplayConfigGetDeviceInfo
DISPLAYCONFIG_SOURCE_DEVICE_NAME
DISPLAYCONFIG_TARGET_DEVICE_NAME

RegisterClassEx
GetModuleHandle
LoadCursor
IDC_ARROW
WndProc
CreateWindowEx
CW_USEDEFAULT
ShowWindow
SW_SHOW
GetMessage
TranslateMessage
DispatchMessage
DefWindowProc
GetClientRect
WM
WM_PAINT
GetWindowLong
SetWindowLong
DwmIsCompositionEnabled
UpdateLayeredWindow
DwmExtendFrameIntoClientArea
DCompositionCreateDevice

以上提供的列表是超过本文所用范围的，多了也没有什么关系，一来这是测试项目，二来发布的时候 AOT 带裁剪

创建窗口

创建窗口的步骤和上一篇博客提供的方法十分接近，只是需要配置 WS_EX_LAYERED 样式，核心代码如下

        WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_OVERLAPPEDWINDOW
                                  | WINDOW_EX_STYLE.WS_EX_LAYERED; // Layered 是透明窗口的关键（但即使没有设置也没关系）
        var style = WNDCLASS_STYLES.CS_OWNDC | WNDCLASS_STYLES.CS_HREDRAW | WNDCLASS_STYLES.CS_VREDRAW;

        var defaultCursor = LoadCursor(
            new HINSTANCE(IntPtr.Zero), new PCWSTR(IDC_ARROW.Value));

        var className = $"lindexi-{Guid.NewGuid().ToString()}";
        var title = "The Title";
        fixed (char* pClassName = className)
        fixed (char* pTitle = title)
        {
            var wndClassEx = new WNDCLASSEXW
            {
                cbSize = (uint) Marshal.SizeOf<WNDCLASSEXW>(),
                style = style,
                lpfnWndProc = new WNDPROC(WndProc), // 注： 这里没有作为字段，可能会被 GC 回收，请不要在实际项目这么编写
                hInstance = new HINSTANCE(GetModuleHandle(null).DangerousGetHandle()),
                hCursor = defaultCursor,
                hbrBackground = new HBRUSH(IntPtr.Zero),
                lpszClassName = new PCWSTR(pClassName)
            };
            ushort atom = RegisterClassEx(in wndClassEx);

            var dwStyle = WINDOW_STYLE.WS_OVERLAPPEDWINDOW;

            var windowHwnd = CreateWindowEx(
                exStyle,
                new PCWSTR((char*) atom),
                new PCWSTR(pTitle),
                dwStyle,
                0, 0, 1900, 1000,
                HWND.Null, HMENU.Null, HINSTANCE.Null, null);

            return windowHwnd;
        }

以上代码放在 CreateWindow 方法中。在开始之前，也先调用 DwmIsCompositionEnabled 方法，判断是否可用

        DwmIsCompositionEnabled(out var compositionEnabled);

        if (!compositionEnabled)
        {
            Console.WriteLine($"无法启用透明窗口效果");
        }

预期在 Win10 以上系统都是能使用的，除非系统被魔改

窗口的消息处理代码 WndProc 先不着急写，等待完成渲染部分的逻辑再一起写

完成窗口创建之后，即可将窗口显示出来，代码如下

        var window = CreateWindow();
        ShowWindow(window, SHOW_WINDOW_CMD.SW_NORMAL);

随后先开启独立的线程作为渲染线程，再跑起来消息循环

渲染线程相关逻辑，我封装到 RenderManager 类型里面，其代码如下

        var renderManager = new RenderManager(window);
        renderManager.StartRenderThread();

跑起来渲染线程之后，使用标准的消息循环跑起来应用

        while (true)
        {
            var msg = new MSG();
            var getMessageResult = GetMessage(&msg, HWND, 0,
                0);

            if (!getMessageResult)
            {
                break;
            }

            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

在 RenderManager 里面也提供窗口尺寸变更的方法，可以在消息循环中调用。此时的消息循环的核心代码如下

    private LRESULT WndProc(HWND hwnd, uint message, WPARAM wParam, LPARAM lParam)
    {
        switch ((WindowsMessage)message)
        {
            case WindowsMessage.WM_NCCALCSIZE:
            {
                return new LRESULT(0);
            }
            case WindowsMessage.WM_SIZE:
            {
                RenderManager?.ReSize();
                break;
            }
        }

        return DefWindowProc(hwnd, message, wParam, lParam);
    }

以上的 WM_NCCALCSIZE 用于声明客户区，通过直接返回 0 告诉系统整个区域都是客户区。否则将出现标题栏不可见，但是点击有效，能拖动窗口也能在原本的最小化、最大化、关闭窗口按钮所在的位置点击响应对应的功能

透明窗口的实现在窗口创建过程中，最关键点只有 WS_EX_LAYERED 和 WM_NCCALCSIZE 的逻辑 ~~。其中 WM_NCCALCSIZE 最为关键。不带 WS_EX_LAYERED 只会出现边框而已~~

以上为采用 WS_EX_LAYERED 的方式，此方法没有采用 WS_EX_NOREDIRECTIONBITMAP 来的高效。如 Windows 窗口样式什么是 WS_EX_NOREDIRECTIONBITMAP 样式博客所述，可以知道，对比采用 WS_EX_LAYERED 分层窗口的方式需要由 CPU 处理分层窗口导致的性能损耗（不一定，详见注），采用 WS_EX_NOREDIRECTIONBITMAP 方式配合 DirectComposition 可以实现更加高性能的窗口透明效果，直接将 DirectComposition 的像素交给 DWM 合成，可让全过程发生在 GPU 中，无 CPU-GPU 的拷贝损耗和带宽占用

注：从 Windows 8 和 8.1 开始，虽然 User32 一直没有发生显著变化，但细微变化也有，即完全支持 GPU 上的每像素 alpha 值混合处理，且将窗口表面传输到系统内存的费用也取消了。也就是说，如果我不需要执行每像素命中测试，现在就能够生成分层窗口效果，同时不会对性能造成影响 https://learn.microsoft.com/zh-cn/archive/msdn-magazine/2014/june/windows-with-c-high-performance-window-layering-using-the-windows-composition-engine

由于本文在编写的时候，本金鱼忘记了 WS_EX_NOREDIRECTIONBITMAP 配置，后面想加上时，担心破坏文章的连贯性，于是将 WS_EX_NOREDIRECTIONBITMAP 部分安排在本文末尾的追加内容中

渲染线程

独立的渲染线程也是 WPF 等 UI 框架所采用的方式，只需要新建一个线程跑起来就可以了，如果有心的话，再设置线程为 STA 的就更好，代码如下

unsafe class RenderManager(HWND hwnd)
{
    public HWND HWND => hwnd;
    private readonly Format _colorFormat = Format.B8G8R8A8_UNorm;

    public void StartRenderThread()
    {
        var thread = new Thread(() => { RenderCore(); })
        {
            IsBackground = true,
            Name = "Render"
        };
        thread.Priority = ThreadPriority.Highest;
        thread.Start();
    }
}

以上的 RenderCore 就是核心的渲染方法了

由于渲染线程是独立的，不能在 ReSize 方法直接修改渲染线程相关的逻辑。本文这里简单使用一个字段表示窗口尺寸变更，需要渲染线程修改交换链尺寸

unsafe class RenderManager(HWND hwnd)
{
    public void ReSize()
    {
        _isReSize = true;
    }

    private bool _isReSize;
}

在 RenderCore 的一开始就是执行初始化逻辑，初始化为本文的关键，核心就是对接 DirectComposition 实现透明窗口效果

初始化渲染

先获取客户区，即窗口尺寸，此尺寸用于后续交换链的创建

        RECT windowRect;
        GetClientRect(HWND, &windowRect);
        var clientSize = new SizeI(windowRect.right - windowRect.left, windowRect.bottom - windowRect.top);

按照上一篇博客提供的方法获取显卡信息，代码如下

        var dxgiFactory2 = DXGI.CreateDXGIFactory1<IDXGIFactory2>();

        IDXGIAdapter1? hardwareAdapter = GetHardwareAdapter(dxgiFactory2)
            // 这里 ToList 只是想列出所有的 IDXGIAdapter1 在实际代码里，大部分都是获取第一个
            .ToList().FirstOrDefault();
        if (hardwareAdapter == null)
        {
            throw new InvalidOperationException("Cannot detect D3D11 adapter");
        }

    private static IEnumerable<IDXGIAdapter1> GetHardwareAdapter(IDXGIFactory2 factory)
    {
        using IDXGIFactory6? factory6 = factory.QueryInterfaceOrNull<IDXGIFactory6>();
        if (factory6 != null)
        {
            // 这个系统的 DX 支持 IDXGIFactory6 类型
            // 先告诉系统，要高性能的显卡
            for (uint adapterIndex = 0;
                 factory6.EnumAdapterByGpuPreference(adapterIndex, GpuPreference.HighPerformance,
                     out IDXGIAdapter1? adapter).Success;
                 adapterIndex++)
            {
                if (adapter == null)
                {
                    continue;
                }

                AdapterDescription1 desc = adapter.Description1;
                if ((desc.Flags & AdapterFlags.Software) != AdapterFlags.None)
                {
                    // Don't select the Basic Render Driver adapter.
                    adapter.Dispose();
                    continue;
                }

                Console.WriteLine($"枚举到 {adapter.Description1.Description} 显卡");
                yield return adapter;
            }
        }
        else
        {
            // 不支持就不支持咯，用旧版本的方式获取显示适配器接口
        }

        // 如果枚举不到，那系统返回啥都可以
        for (uint adapterIndex = 0;
             factory.EnumAdapters1(adapterIndex, out IDXGIAdapter1? adapter).Success;
             adapterIndex++)
        {
            AdapterDescription1 desc = adapter.Description1;

            if ((desc.Flags & AdapterFlags.Software) != AdapterFlags.None)
            {
                // Don't select the Basic Render Driver adapter.
                adapter.Dispose();

                continue;
            }

            Console.WriteLine($"枚举到 {adapter.Description1.Description} 显卡");
            yield return adapter;
        }
    }

尝试创建 ID3D11Device 设备，代码如下

        FeatureLevel[] featureLevels = new[]
        {
            FeatureLevel.Level_12_2,
            FeatureLevel.Level_12_1,
            FeatureLevel.Level_12_0,
            FeatureLevel.Level_11_1,
            FeatureLevel.Level_11_0,
            FeatureLevel.Level_10_1,
            FeatureLevel.Level_10_0,
            FeatureLevel.Level_9_3,
            FeatureLevel.Level_9_2,
            FeatureLevel.Level_9_1,
        };

        IDXGIAdapter1 adapter = hardwareAdapter;
        DeviceCreationFlags creationFlags = DeviceCreationFlags.BgraSupport;
        var result = D3D11.D3D11CreateDevice
        (
            adapter,
            DriverType.Unknown,
            creationFlags,
            featureLevels,
            out ID3D11Device d3D11Device, out FeatureLevel featureLevel,
            out ID3D11DeviceContext d3D11DeviceContext
        );

本文以上的 FeatureLevel[] 中添加了 Level_12_2 等的不合理需求，如果创建失败了，则执行降级逻辑。按照技术原理，只需有 Level_11_1 即可

        if (result.Failure)
        {
            // 降低等级试试
            featureLevels = new[]
            {
                //FeatureLevel.Level_12_2,
                //FeatureLevel.Level_12_1,
                //FeatureLevel.Level_12_0,
                FeatureLevel.Level_11_1,
                FeatureLevel.Level_11_0,
                FeatureLevel.Level_10_1,
                FeatureLevel.Level_10_0,
                FeatureLevel.Level_9_3,
                FeatureLevel.Level_9_2,
                FeatureLevel.Level_9_1,
            };

            result = D3D11.D3D11CreateDevice
            (
                adapter,
                DriverType.Unknown,
                creationFlags,
                featureLevels,
                out d3D11Device, out featureLevel,
                out d3D11DeviceContext
            );
        }

将获取到的 ID3D11Device 当成 ID3D11Device1 设备来用，这一步基本不会遇到出错的，代码如下

        // 大部分情况下，用的是 ID3D11Device1 和 ID3D11DeviceContext1 类型
        // 从 ID3D11Device 转换为 ID3D11Device1 类型
        ID3D11Device1 d3D11Device1 = d3D11Device.QueryInterface<ID3D11Device1>();
        var d3D11DeviceContext1 = d3D11DeviceContext.QueryInterface<ID3D11DeviceContext1>();

        // 获取到了新的两个接口，就可以减少 `d3D11Device` 和 `d3D11DeviceContext` 的引用计数。调用 Dispose 不会释放掉刚才申请的 D3D 资源，只是减少引用计数
        d3D11Device.Dispose();
        d3D11DeviceContext.Dispose();

准备交换链参数，代码如下

        // 缓存的数量，包括前缓存。大部分应用来说，至少需要两个缓存，这个玩过游戏的伙伴都知道
        const int FrameCount = 2;
        SwapChainDescription1 swapChainDescription = new()
        {
            Width = (uint) clientSize.Width,
            Height = (uint) clientSize.Height,
            Format = _colorFormat,
            BufferCount = FrameCount,
            BufferUsage = Usage.RenderTargetOutput,
            SampleDescription = SampleDescription.Default,
            Scaling = Scaling.Stretch,
            SwapEffect = SwapEffect.FlipSequential, // 使用 FlipSequential 配合 Composition
            AlphaMode = AlphaMode.Premultiplied,
            Flags = SwapChainFlags.None,
        };

交换链中有以下参数必须固定为此搭配：

Scaling： Scaling.Stretch
SwapEffect： SwapEffect.FlipDiscard 或 SwapEffect.FlipSequential ，正常来说都会采用 FlipSequential 配合 Composition 使用
AlphaMode： AlphaMode.Premultiplied 。使用 AlphaMode.Ignore 和 AlphaMode.Unspecified 参数也是合法的，但是如此就丢失了窗口透明了，不是咱的需求。而 AlphaMode.Straight 参数则是不搭的

如果以上参数不搭配，则会在创建交换链时，返回 0x887A0001 错误

上文提到了 AlphaMode.Premultiplied 预乘，简单来说就是最终输出的值里的 RGB 分量都乘以透明度。更多细节请参阅支持的像素格式和 Alpha 模式 - Win32 apps - Microsoft Learn

判断系统版本，决定能否使用 DirectComposition 功能，代码如下

        // 使用 DirectComposition 才能支持透明窗口
        bool useDirectComposition = true;
        // 使用 DirectComposition 时有系统版本要求
        useDirectComposition = useDirectComposition & OperatingSystem.IsWindowsVersionAtLeast(8, 1);

如此可以让代码走两个分支，使用 DirectComposition 的分支的代码如下

        IDXGISwapChain1 swapChain;

        if (useDirectComposition)
        {
            // 使用 CreateSwapChainForComposition 创建支持预乘 Alpha 的 SwapChain
            swapChain =
                dxgiFactory2.CreateSwapChainForComposition(d3D11Device1, swapChainDescription);

            // 创建 DirectComposition 设备和目标
            IDXGIDevice dxgiDevice = d3D11Device1.QueryInterface<IDXGIDevice>();
            IDCompositionDevice compositionDevice = DComp.DCompositionCreateDevice<IDCompositionDevice>(dxgiDevice);
            compositionDevice.CreateTargetForHwnd(HWND, true, out IDCompositionTarget compositionTarget);

            // 创建视觉对象并设置 SwapChain 作为内容
            IDCompositionVisual compositionVisual = compositionDevice.CreateVisual();
            compositionVisual.SetContent(swapChain);
            compositionTarget.SetRoot(compositionVisual);
            compositionDevice.Commit();
        }

从上面代码可见核心步骤是先让 CreateSwapChainForComposition 创建出交换链对象。再将 ID3D11Device1 当成 IDXGIDevice 设备，用于调用 DComp.DCompositionCreateDevice 创建出 IDCompositionDevice 设备

调用 IDCompositionDevice 的 CreateTargetForHwnd 方法即可为当前的窗口挂上 IDCompositionTarget 对象。随后再调用 IDCompositionDevice 设备的 CreateVisual 创建 IDCompositionVisual 视觉对象。将刚才创建出来的交换链作为视觉对象的内容，如此即可完成交换链与内容的绑定

            // 创建视觉对象并设置 SwapChain 作为内容
            IDCompositionVisual compositionVisual = compositionDevice.CreateVisual();
            compositionVisual.SetContent(swapChain);

现在交换链所渲染的画面已经能够到 IDCompositionVisual 里了，再将 IDCompositionVisual 作为 IDCompositionTarget 的根，即可让 IDCompositionVisual 参与 DWM 合成

            compositionTarget.SetRoot(compositionVisual);
            compositionDevice.Commit();

如果没有 DirectComposition 可用，则依然使用上一篇博客介绍的方法创建交换链，代码如下

        IDXGISwapChain1 swapChain;

        if (useDirectComposition)
        {
            ...
        }
        else
        {
            var fullscreenDescription = new SwapChainFullscreenDescription()
            {
                Windowed = true,
            };

            // 比如设置为忽略，否则将会报错。错误信息如下，只有 CreateSwapChainForComposition 或 CreateSwapChainForCoreWindow 才能使用
            // DXGI ERROR: IDXGIFactory::CreateSwapChain: Alpha blended swapchains must be created with CreateSwapChainForComposition, or CreateSwapChainForCoreWindow with the DXGI_SWAP_CHAIN_FLAG_FOREGROUND_LAYER flag.
            swapChainDescription.AlphaMode = AlphaMode.Ignore;

            swapChain = dxgiFactory2.CreateSwapChainForHwnd(d3D11Device1, hwnd, swapChainDescription,
                fullscreenDescription);
        }

以上代码的 DirectComposition 为本文的核心，只需要创建出输出带预乘的交换链，配合 WS_EX_LAYERED 窗口，即可渲染出透明窗口

接下来的逻辑就是和 D2D 对接，尝试渲染透明的界面用于测试

对接渲染

由于 D2D 没有什么戏份，本文就只贴出核心代码

        using D2D.ID2D1Factory1 d2DFactory = D2D.D2D1.D2D1CreateFactory<D2D.ID2D1Factory1>();

                var d3D11Texture2D = _renderContext.SwapChain.GetBuffer<ID3D11Texture2D>(0);

                var dxgiSurface = d3D11Texture2D.QueryInterface<IDXGISurface>();
                var renderTargetProperties = new D2D.RenderTargetProperties()
                {
                    PixelFormat = new PixelFormat(D2DColorFormat, Vortice.DCommon.AlphaMode.Premultiplied),
                    Type = D2D.RenderTargetType.Hardware,
                };

                D2D.ID2D1RenderTarget d2D1RenderTarget =
                    d2DFactory.CreateDxgiSurfaceRenderTarget(dxgiSurface, renderTargetProperties);

        while (!_isDisposed)
        {
                D2D.ID2D1RenderTarget renderTarget = d2D1RenderTarget;

                renderTarget.BeginDraw();

                var color = new Color4(Random.Shared.NextSingle(), Random.Shared.NextSingle(),
                    Random.Shared.NextSingle(), 0.1f);
                renderTarget.Clear(color);

                renderTarget.EndDraw();

                _renderContext.SwapChain.Present(1, PresentFlags.None);
                _renderContext.D3D11DeviceContext1.Flush();
        }

如果准备处理窗口尺寸改变，则需要在循环里面判断 _isReSize 字段，调用交换链的 ResizeBuffers 方法，代码如下

            if (_isReSize)
            {
                // 处理窗口大小变化
                _isReSize = false;

                GetClientRect(HWND, out var pClientRect);
                var clientSize = new SizeI(pClientRect.right - pClientRect.left, pClientRect.bottom - pClientRect.top);

                var swapChain = _renderContext.SwapChain;

                swapChain.ResizeBuffers(2,
                    (uint) (clientSize.Width),
                    (uint) (clientSize.Height),
                    _colorFormat,
                    SwapChainFlags.None
                );
            }

尝试运行代码，可见一个不断闪烁的背景透明的窗口

代码

本文代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 369de6b65c4122cec6a6c9ffbcc0b352a419e83e

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 369de6b65c4122cec6a6c9ffbcc0b352a419e83e

获取代码之后，进入 DirectX/D2D/FarjairyakaBurnefuwache 文件夹，即可获取到源代码

更多技术博客，请参阅博客导航

采用 WS_EX_NOREDIRECTIONBITMAP 的方案

上文提及的是采用 WS_EX_LAYERED 分层窗口的方式，此方式与采用 WS_EX_NOREDIRECTIONBITMAP 的方案的代码写法非常接近，只是 WS_EX_NOREDIRECTIONBITMAP 可以带来更高的性能

其改动全在 CreateWindow 中，只需将 WINDOW_EX_STYLE 从 WS_EX_LAYERED 换成 WS_EX_NOREDIRECTIONBITMAP 即可

在使用 WS_EX_NOREDIRECTIONBITMAP 中，还可以在 WndProc 干掉 WM_NCCALCSIZE 用来保留窗口边框，即窗口标题栏

修改之后的 CreateWindow 方法中的 WINDOW_EX_STYLE 配置如下

    private unsafe HWND CreateWindow()
    {
        DwmIsCompositionEnabled(out var compositionEnabled);

        if (!compositionEnabled)
        {
            Console.WriteLine($"无法启用透明窗口效果");
        }

        // [Windows 窗口样式 什么是 WS_EX_NOREDIRECTIONBITMAP 样式](/post/Windows-%E7%AA%97%E5%8F%A3%E6%A0%B7%E5%BC%8F-%E4%BB%80%E4%B9%88%E6%98%AF-WS_EX_NOREDIRECTIONBITMAP-%E6%A0%B7%E5%BC%8F.html )
        WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP;

        var style = WNDCLASS_STYLES.CS_OWNDC | WNDCLASS_STYLES.CS_HREDRAW | WNDCLASS_STYLES.CS_VREDRAW;

        var defaultCursor = LoadCursor(
            new HINSTANCE(IntPtr.Zero), new PCWSTR(IDC_ARROW.Value));

        var className = $"lindexi-{Guid.NewGuid().ToString()}";
        var title = "The Title";
        _myInstanceWndProc = new WNDPROC(WndProc);
        fixed (char* pClassName = className)
        fixed (char* pTitle = title)
        {
            var wndClassEx = new WNDCLASSEXW
            {
                cbSize = (uint) Marshal.SizeOf<WNDCLASSEXW>(),
                style = style,
                lpfnWndProc = _myInstanceWndProc,
                hInstance = new HINSTANCE(GetModuleHandle(null).DangerousGetHandle()),
                hCursor = defaultCursor,
                hbrBackground = new HBRUSH(IntPtr.Zero),
                lpszClassName = new PCWSTR(pClassName)
            };
            ushort atom = RegisterClassEx(in wndClassEx);

            var dwStyle = WINDOW_STYLE.WS_OVERLAPPEDWINDOW | WINDOW_STYLE.WS_VISIBLE;

            var windowHwnd = CreateWindowEx(
                exStyle,
                new PCWSTR((char*) atom),
                new PCWSTR(pTitle),
                dwStyle,
                0, 0, 1900, 1000,
                HWND.Null, HMENU.Null, HINSTANCE.Null, null);

            return windowHwnd;
        }
    }

    private WNDPROC _myInstanceWndProc;

可见核心关键改动只有 WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP; 这一行

注：原博客代码里面，是直接使用 new WNDPROC(WndProc) 局部变量的写法，会导致当委托被回收的时候，抛出如下异常:

Process terminated.
A callback was made on a garbage collected delegate of type 'NearajurkeekallnoYabarfoge!Windows.Win32.UI.WindowsAndMessaging.WNDPROC::Invoke'.
   at Windows.Win32.PInvoke.GetMessage(Windows.Win32.UI.WindowsAndMessaging.MSG*, Windows.Win32.Foundation.HWND, UInt32, UInt32)
   at NearajurkeekallnoYabarfoge.DemoWindow.Run()
   at NearajurkeekallnoYabarfoge.Program.Main(System.String[])

解决方法就是将委托放在字段里面，防止被回收。详细请看： https://github.com/lindexi/lindexi_gd/pull/85

如果期望显示标题栏，则可以继续在 WndProc 进行改动，删除 WM_NCCALCSIZE 相关代码，删除之后的代码如下

    private LRESULT WndProc(HWND hwnd, uint message, WPARAM wParam, LPARAM lParam)
    {
        if ((WindowsMessage) message == WindowsMessage.WM_SIZE)
        {
            _renderManager?.ReSize();
        }

        return DefWindowProc(hwnd, message, wParam, lParam);
    }

更改使用 WS_EX_NOREDIRECTIONBITMAP 的代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 5b79f1c45819750fa9e931d78b3797a81c877294

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 5b79f1c45819750fa9e931d78b3797a81c877294

获取代码之后，进入 DirectX/D2D/NearajurkeekallnoYabarfoge 文件夹，即可获取到源代码

此方案即可制作出保留窗口标题，窗口内容透明可与窗口背后的内容做 Alpha 透明合成叠加的窗口效果

性能提醒

无论是采用 WS_EX_LAYERED 还是 WS_EX_NOREDIRECTIONBITMAP 的方案，都会导致 DWM 需要更多的性能损耗

如果自己的应用是没有透明背景需求的，建议不要带上这两个选项以降低 DWM 合成的损耗。或依然保持窗口样式，但在交换链配置 swapChainDescription.AlphaMode = AlphaMode.Ignore; 也能减少 DWM 的损耗

只有在 4k 全屏应用里面，才能比较明显看到开启透明窗口带来的性能损耗

性能测试

为了说明性能的差异，我做了对比测试

本次实验的机器配置如下：

屏幕： 3840x2160 (4K) + 百分百 DPI
CPU： i5-12450H
GPU：集显

测试结果如下：

DirectCompositionPremultipliedAlphaMode

采用 DirectComposition 和配置交换链的 AlphaMode 为 Premultiplied 预乘，此为本文的演示透明窗口组合效果。代码片段如下

        WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP;

        SwapChainDescription1 swapChainDescription = new()
        {
            Width = (uint) clientSize.Width,
            Height = (uint) clientSize.Height,
            Format = _colorFormat,
            BufferCount = FrameCount,
            BufferUsage = Usage.RenderTargetOutput,
            SampleDescription = SampleDescription.Default,
            Scaling = Scaling.Stretch,
            SwapEffect = SwapEffect.FlipSequential, // 使用 FlipSequential 配合 Composition
            AlphaMode = AlphaMode.Premultiplied,
            Flags = SwapChainFlags.None,
        };

        var swapChain = dxgiFactory2.CreateSwapChainForComposition(d3D11Device1, swapChainDescription);

运行效果：

CPU：忽略不计
GPU：占用 75-80
DWM：占用 65-70
满帧率

可见此时会让 DWM 非常繁忙。整体的 GPU 占用比较高

DirectCompositionWithWS_EX_LAYERED

和 DirectCompositionPremultipliedAlphaMode 不同的是，仅将窗口样式从 WS_EX_NOREDIRECTIONBITMAP 换成 WS_EX_LAYERED 而已，代码差异如下

-       WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP;
+       WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_LAYERED;

        SwapChainDescription1 swapChainDescription = new()
        {
            Width = (uint) clientSize.Width,
            Height = (uint) clientSize.Height,
            Format = _colorFormat,
            BufferCount = FrameCount,
            BufferUsage = Usage.RenderTargetOutput,
            SampleDescription = SampleDescription.Default,
            Scaling = Scaling.Stretch,
            SwapEffect = SwapEffect.FlipSequential, // 使用 FlipSequential 配合 Composition
            AlphaMode = AlphaMode.Premultiplied,
            Flags = SwapChainFlags.None,
        };

        var swapChain = dxgiFactory2.CreateSwapChainForComposition(d3D11Device1, swapChainDescription);

运行效果：

CPU：忽略不计
GPU：占用 77-85
DWM：占用 75-80
满帧率

可见采用 WS_EX_LAYERED 样式基本和 WS_EX_NOREDIRECTIONBITMAP 持平，差异几乎测试不到，符合文档说明内容

DirectCompositionIgnoreAlphaMode

和 DirectCompositionPremultipliedAlphaMode 不同的是，仅将 AlphaMode 设置为忽略，此时将丢失窗口透明效果

        WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP;

-       swapChainDescription.AlphaMode = AlphaMode.Premultiplied;
+       swapChainDescription.AlphaMode = AlphaMode.Ignore;

        var swapChain = dxgiFactory2.CreateSwapChainForComposition(d3D11Device1, swapChainDescription);

运行效果：

CPU：忽略不计
GPU：占用 5
DWM： 0-1
满帧率

此时的窗口没有透明效果，聪明的 DWM 也就没有需要执行合成逻辑，自然占用也就少了

DirectCompositionWithoutWS_EX_NOREDIRECTIONBITMAP

和 DirectCompositionPremultipliedAlphaMode 不同的是，去掉了窗口的 WS_EX_NOREDIRECTIONBITMAP 样式，此时也会丢失窗口的透明效果，且这个组合是不正确的，正常不会有人会这么做

-        WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP;
+        WINDOW_EX_STYLE exStyle = default;

        swapChainDescription.AlphaMode = AlphaMode.Premultiplied;

        var swapChain = dxgiFactory2.CreateSwapChainForComposition(d3D11Device1, swapChainDescription);

运行效果：

CPU：忽略不计
GPU：占用 45-50
DWM： 40
满帧率

这个组合比较奇怪，跑出来的效果也比较奇怪。我感觉是因为此时需要重定向表面，导致存在一些带宽损耗

CreateSwapChainForHwnd

直接使用 CreateSwapChainForHwnd 传统方式，不再使用 DirectComposition 创建，丢失窗口透明效果，代码差异如下

        WINDOW_EX_STYLE exStyle = WINDOW_EX_STYLE.WS_EX_NOREDIRECTIONBITMAP;

-       swapChainDescription.AlphaMode = AlphaMode.Premultiplied;
+       swapChainDescription.AlphaMode = AlphaMode.Ignore;

-       var swapChain = dxgiFactory2.CreateSwapChainForComposition(d3D11Device1, swapChainDescription);
+       var swapChain = dxgiFactory2.CreateSwapChainForHwnd(d3D11Device1, HWND, swapChainDescription, fullscreenDescription);        

运行效果：

CPU：忽略不计
GPU：占用 5
DWM： 0-1
满帧率

此时可见使用传统的 CreateSwapChainForHwnd 方式和 DirectComposition 忽略 AlphaMode 的性能持平，此时两者都能达到较好的效果

无论是对 CreateSwapChainForHwnd 设置的 WINDOW_EX_STYLE 为无或 WS_EX_LAYERED 都对此结果没有影响

性能测试代码

以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin b678a0cc6d689aa63fd1239bb88113ff8a4b9fcd

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin b678a0cc6d689aa63fd1239bb88113ff8a4b9fcd

获取代码之后，进入 DirectX/D2D/LurqificelgallRikurneawekearner 文件夹，即可获取到源代码

特别感谢

特别感谢 @luojunyuan 帮忙修复博客示例代码

dotnet 读 WPF 源代码笔记从 WM_POINTER 消息到 Touch 事件

Tue, 07 Apr 2026 22:01:27 +0000

本文记录我读 WPF 源代码的笔记，本文将介绍在 WPF 底层是如何从 Win32 的消息循环里获取到的 WM_POINTER 消息处理转换作为 Touch 事件的参数

由于 WPF 触摸部分会兼顾开启 Pointer 消息和不开启 Pointer 消息，在 WPF 框架里面的逻辑会有部分是兼容逻辑，为了方便大家理解，本文分为两个部分。第一个部分是脱离 WPF 框架，聊聊一个 Win32 程序如何从 Win32 的消息循环获取到的 WM_POINTER 消息处理转换为输入坐标点，以及在触摸下获取触摸信息。第二部分是 WPF 框架是如何安排上这些处理逻辑，如何和 WPF 框架的进行对接

第一部分脱离了 WPF 框架，也就没有了兼容不开启 Pointer 消息的负担，我将使用简单的描述点出关键部分

处理 Pointer 消息

在 Win32 应用程序中，大概有三个方式来进行对 Pointer 消息进行处理。我将从简单到复杂和大家讲述这三个方式

最简单获取触摸信息方式

方式1:

接收到 WM_POINTER 消息之后，将 wparam 转换为 pointerId 参数，调用 GetPointerTouchInfo 方法即可获取到 POINTER_INFO 信息

获取 POINTER_INFO 的 ptPixelLocationRaw 字段，即可拿到基于屏幕坐标系的像素点

只需将其转换为窗口坐标系和处理 DPI 即可使用

此方法的最大缺点在于 ptPixelLocationRaw 字段拿到的是丢失精度的点，像素为单位。如果在精度稍微高的触摸屏下，将会有明显的锯齿效果

优点在于其获取特别简单

获取高精度触摸点坐标方式

方式2：

依然是接收到 WM_POINTER 消息之后，将 wparam 转换为 pointerId 参数，调用 GetPointerTouchInfo 方法即可获取到 POINTER_INFO 信息

只是从获取 POINTER_INFO 的 ptPixelLocationRaw 字段换成 ptHimetricLocationRaw 字段

使用 ptHimetricLocationRaw 字段的优势在于可以获取不丢失精度的信息，但需要额外调用 GetPointerDeviceRects 函数获取 displayRect 和 pointerDeviceRect 信息用于转换坐标点，转换逻辑如以下代码所示

            PInvoke.GetPointerDeviceRects(pointerInfo.sourceDevice, &pointerDeviceRect, &displayRect);

            // 如果想要获取比较高精度的触摸点，可以使用 ptHimetricLocationRaw 字段
            // 由于 ptHimetricLocationRaw 采用的是 pointerDeviceRect 坐标系，需要转换到屏幕坐标系
            // 转换方法就是先将 ptHimetricLocationRaw 的 X 坐标，压缩到 [0-1] 范围内，然后乘以 displayRect 的宽度，再加上 displayRect 的 left 值，即得到了屏幕坐标系的 X 坐标。压缩到 [0-1] 范围内的方法就是除以 pointerDeviceRect 的宽度
            // 为什么需要加上 displayRect.left 的值？考虑多屏的情况，屏幕可能是副屏
            // Y 坐标同理
            var point2D = new Point2D(
                pointerInfo.ptHimetricLocationRaw.X / (double) pointerDeviceRect.Width * displayRect.Width +
                displayRect.left,
                pointerInfo.ptHimetricLocationRaw.Y / (double) pointerDeviceRect.Height * displayRect.Height +
                displayRect.top);

            // 获取到的屏幕坐标系的点，需要转换到 WPF 坐标系
            // 转换过程的两个重点：
            // 1. 底层 ClientToScreen 只支持整数类型，直接转换会丢失精度。即使是 WPF 封装的 PointFromScreen 或 PointToScreen 方法也会丢失精度
            // 2. 需要进行 DPI 换算，必须要求 DPI 感知

            // 先测量窗口与屏幕的偏移量，这里直接取 0 0 点即可，因为这里获取到的是虚拟屏幕坐标系，不需要考虑多屏的情况
            var screenTranslate = new Point(0, 0);
            PInvoke.ClientToScreen(new HWND(hwnd), ref screenTranslate);
            // 获取当前的 DPI 值
            var dpi = VisualTreeHelper.GetDpi(this);
            // 先做平移，再做 DPI 换算
            point2D = new Point2D(point2D.X - screenTranslate.X, point2D.Y - screenTranslate.Y);
            point2D = new Point2D(point2D.X / dpi.DpiScaleX, point2D.Y / dpi.DpiScaleY);

以上方式2的代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 322313ee55d0eeaae7148b24ca279e1df087871e

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 322313ee55d0eeaae7148b24ca279e1df087871e

获取代码之后，进入 WPFDemo/DefilireceHowemdalaqu 文件夹，即可获取到源代码

方式2的优点在于可以获取到更高的精度。缺点是相对来说比较复杂，需要多了点点处理

最复杂全功能方式

方式3：

此方式会更加复杂，但功能能够更加全面，适合用在要求更高控制的应用里面

先调用 GetPointerDeviceProperties 方法，获取 HID 描述符上报的对应设备属性，此时可以获取到的是具备完全的 HID 描述符属性的方法，可以包括 Windows 的 Pen 协议里面列举的各个属性，如宽度高度旋转角等信息

收到 WM_POINTER 消息时，调用 GetRawPointerDeviceData 获取最原始的触摸信息，再对原始触摸信息进行解析处理

原始触摸信息的解析处理需要先应用获取每个触摸点的数据包长度，再拆数据包。原始触摸信息拿到的是一个二进制数组，这个二进制数组里面可能包含多个触摸点的信息，需要根据数据包长度拆分为多个触摸点信息

解析处理就是除了前面两个分别是属于 X 和 Y 之外，后面的数据就根据 GetPointerDeviceProperties 方法获取到的触摸描述信息进行套入

此方式的复杂程度比较高，且拿到的是原始的触摸信息，需要做比较多的处理。即使解析到 X 和 Y 坐标点之后，还需要执行坐标的转换，将其转换为屏幕坐标系

这里拿到的 X 和 Y 坐标点是设备坐标系，这里的设备坐标系不是 GetPointerDeviceRects 函数获取的 pointerDeviceRect 设备范围坐标系，而是对应 GetPointerDeviceProperties 方法获取到的描述符的逻辑最大值和最小值的坐标范围

其正确计算方法为从 GetPointerDeviceProperties 方法获取到的 X 和 Y 描述信息，分别取 POINTER_DEVICE_PROPERTY 的 logicalMax 作为最大值范围。分别将 X 和 Y 除以 logicalMax 缩放到 [0,1] 范围内，再乘以屏幕尺寸即可转换为屏幕坐标系

这里的屏幕尺寸是通过 GetPointerDeviceRects 函数获取的 displayRect 尺寸

转换为屏幕坐标系之后，就需要再次处理 DPI 和转换为窗口坐标系的才能使用

方式3的内容比较多，我将详细过程放在 WPF 通过 GetRawPointerDeviceData 从 WM_POINTER 消息触摸裸数据

核心处理示例代码如下，以下代码写在窗口消息处理里，为了清晰起见以下代码只包含关键部分，可在本章末尾找到全部代码下载方法

    [SupportedOSPlatform("windows5.0")]
    private unsafe LRESULT Hook(HWND hwnd, uint msg, WPARAM wParam, LPARAM lParam)
    {
        if (msg == WM_POINTERUPDATE /*Pointer Update*/)
        {
            var result = CallWindowProc(_oldWndProc, hwnd, msg, wParam, lParam);

            Debug.Assert(OperatingSystem.IsWindowsVersionAtLeast(10, 0), "能够收到 WM_Pointer 消息，必定系统版本号不会低");

            var pointerId = (uint) (ToInt32(wParam) & 0xFFFF);
            GetPointerTouchInfo(pointerId, out POINTER_TOUCH_INFO info);
            POINTER_INFO pointerInfo = info.pointerInfo;

            global::Windows.Win32.Foundation.RECT pointerDeviceRect = default;
            global::Windows.Win32.Foundation.RECT displayRect = default;

            GetPointerDeviceRects(pointerInfo.sourceDevice, &pointerDeviceRect, &displayRect);

            uint propertyCount = 0;
            GetPointerDeviceProperties(pointerInfo.sourceDevice, &propertyCount, null);
            POINTER_DEVICE_PROPERTY* pointerDevicePropertyArray =
                stackalloc POINTER_DEVICE_PROPERTY[(int) propertyCount];
            GetPointerDeviceProperties(pointerInfo.sourceDevice, &propertyCount, pointerDevicePropertyArray);
            var pointerDevicePropertySpan =
                new Span<POINTER_DEVICE_PROPERTY>(pointerDevicePropertyArray, (int) propertyCount);

            GetPointerCursorId(pointerId, out uint cursorId);

            var touchInfo = new StringBuilder();
            touchInfo.Append($"[{DateTime.Now}] ");
            touchInfo.AppendLine(
                $"PointerId={pointerId} CursorId={cursorId} PointerDeviceRect={RectToString(pointerDeviceRect)} DisplayRect={RectToString(displayRect)} PropertyCount={propertyCount} SourceDevice={pointerInfo.sourceDevice}");

            var xPropertyIndex = -1;
            var yPropertyIndex = -1;
            var contactIdentifierPropertyIndex = -1;
            var widthPropertyIndex = -1;
            var heightPropertyIndex = -1;

            for (var i = 0; i < pointerDevicePropertySpan.Length; i++)
            {
                POINTER_DEVICE_PROPERTY pointerDeviceProperty = pointerDevicePropertySpan[i];
                var usagePageId = pointerDeviceProperty.usagePageId;
                var usageId = pointerDeviceProperty.usageId;
                // 单位
                var unit = pointerDeviceProperty.unit;
                // 单位指数。 它与 Unit 字段一起定义了设备报告中数据的物理单位。具体来说：
                // - Unit：定义了数据的基本单位，例如厘米、英寸、弧度等。
                // - UnitExponent：表示单位的数量级（即 10 的幂次）。它用于缩放单位值，使其适应不同的范围
                var unitExponent = pointerDeviceProperty.unitExponent;
                touchInfo.Append(
                        $"{UsagePageAndIdConverter.ConvertToString(usagePageId, usageId)} Unit={StylusPointPropertyUnitHelper.FromPointerUnit(unit)}({unit}) UnitExponent={unitExponent}")
                    .Append(
                        $"  LogicalMin={pointerDeviceProperty.logicalMin} LogicalMax={pointerDeviceProperty.logicalMax}")
                    .Append(
                        $"  PhysicalMin={pointerDeviceProperty.physicalMin} PhysicalMax={pointerDeviceProperty.physicalMax}")
                    .AppendLine();

                if (usagePageId == (ushort) HidUsagePage.Generic)
                {
                    if (usageId == (ushort) HidUsage.X)
                    {
                        xPropertyIndex = i;
                    }
                    else if (usageId == (ushort) HidUsage.Y)
                    {
                        yPropertyIndex = i;
                    }
                }
                else if (usagePageId == (ushort) HidUsagePage.Digitizer)
                {
                    if (usageId == (ushort) DigitizersUsageId.Width)
                    {
                        widthPropertyIndex = i;
                    }
                    else if (usageId == (ushort) DigitizersUsageId.Height)
                    {
                        heightPropertyIndex = i;
                    }
                    else if (usageId == (ushort) DigitizersUsageId.ContactIdentifier)
                    {
                        contactIdentifierPropertyIndex = i;
                    }
                }
            }

            var historyCount = pointerInfo.historyCount;
            int[] rawPointerData = new int[propertyCount * historyCount];

            fixed (int* pValue = rawPointerData)
            {
                bool success = GetRawPointerDeviceData(pointerId, historyCount, propertyCount,
                    pointerDevicePropertyArray, pValue);
                Debug.Assert(success);
            }

            var rawPointerPoint = new RawPointerPoint();

            for (int i = 0; i < historyCount; i++)
            {
                var baseIndex = i * propertyCount;

                if (xPropertyIndex >= 0 && yPropertyIndex >= 0)
                {
                    var xValue = rawPointerData[baseIndex + xPropertyIndex];
                    var yValue = rawPointerData[baseIndex + yPropertyIndex];
                    var xProperty = pointerDevicePropertySpan[xPropertyIndex];
                    var yProperty = pointerDevicePropertySpan[yPropertyIndex];

                    // 从 Pointer 算到的只能是屏幕坐标的点，转换进应用程序窗口坐标还需要自己再次计算
                    var xForScreen = ((double) xValue - xProperty.logicalMin) /
                        (xProperty.logicalMax - xProperty.logicalMin) * displayRect.Width;
                    var yForScreen = ((double) yValue - yProperty.logicalMin) /
                        (yProperty.logicalMax - yProperty.logicalMin) * displayRect.Height;

                    rawPointerPoint = rawPointerPoint with
                    {
                        X = xForScreen,
                        Y = yForScreen,
                    };
                }

                if (contactIdentifierPropertyIndex >= 0)
                {
                    // 这里的 Id 关联会出现 id 重复的问题，似乎是在上层处理的
                    var contactIdentifierValue = rawPointerData[baseIndex + contactIdentifierPropertyIndex];

                    rawPointerPoint = rawPointerPoint with
                    {
                        Id = contactIdentifierValue
                    };
                }

                if (widthPropertyIndex >= 0 && heightPropertyIndex >= 0)
                {
                    var widthValue = rawPointerData[baseIndex + widthPropertyIndex];
                    var heightValue = rawPointerData[baseIndex + heightPropertyIndex];

                    var widthProperty = pointerDevicePropertySpan[widthPropertyIndex];
                    var heightProperty = pointerDevicePropertySpan[heightPropertyIndex];

                    // 计算宽度高度的方法：
                    // 1. 计算出宽度 Value 和最大值最小值的比例
                    // 2. 按照比例计算出宽度高度在屏幕上的像素值
                    // 3. 按照比例配合物理最小值和最大值计算出宽度高度的物理值
                    var widthScale = ((double) widthValue - widthProperty.logicalMin) /
                                     (widthProperty.logicalMax - widthProperty.logicalMin);

                    var heightScale = ((double) heightValue - heightProperty.logicalMin) /
                                      (heightProperty.logicalMax - heightProperty.logicalMin);

                    var widthPixel = widthScale * displayRect.Width;
                    var heightPixel = heightScale * displayRect.Height;

                    rawPointerPoint = rawPointerPoint with
                    {
                        RawWidth = widthValue,
                        RawHeight = heightValue,
                        PixelWidth = widthPixel,
                        PixelHeight = heightPixel,
                    };

                    if (StylusPointPropertyUnitHelper.FromPointerUnit(widthProperty.unit) ==
                        StylusPointPropertyUnit.Centimeters)
                    {
                        var unitExponent = (int) widthProperty.unitExponent;

                        // 根据 HID 规范，单位指数的值范围是 0x00-0x0F，带上 mask 可以强行约束范围
                        const byte HidExponentMask = 0x0F;
                        // HID hut1_6.pdf 23.18.4 Generic Unit Exponent
                        // 以下代码也能从 WPF 的 System.Windows.Input.StylusPointer.PointerStylusPointPropertyInfoHelper 找到
                        unitExponent = (byte)(unitExponent & HidExponentMask) switch
                        {
                            5 => 5,
                            6 => 6,
                            7 => 7,
                            8 => -8,
                            9 => -7,
                            0x0A => -6,
                            0x0B => -5,
                            0x0C => -4,
                            0x0D => -3,
                            0x0E => -2,
                            0x0F => -1,
                            _ => unitExponent
                        };
                        // 也可以这么写，正好也是相同的值。只是这么写在玩二进制的转换，不如打一个表好
                        // - unchecked((short) (0xFFF0 | 0xA)) == -6
                        // - unchecked((short) (0xFFF0 | 0x9)) == -7
                        //if (unitExponent > 7)
                        //{
                        //    unitExponent = unchecked((short)(0xFFF0 | unitExponent));
                        //}

                        // 宽度高度都使用相同的单位值好了，预计也没有哪个厂商的触摸框有这么有趣，宽度和高度分别采用不同的单位
                        var exponent = Math.Pow(10, unitExponent);

                        var widthPhysical = widthScale * (widthProperty.physicalMax - widthProperty.physicalMin) *
                                            exponent;
                        var heightPhysical = heightScale * (heightProperty.physicalMax - heightProperty.physicalMin) *
                                             exponent;

                        rawPointerPoint = rawPointerPoint with
                        {
                            // 物理尺寸的计算能够保持和 WPF 的 StylusPoint 拿到的相同
                            PhysicalWidth = widthPhysical,
                            PhysicalHeight = heightPhysical,
                        };
                    }
                }

                if (rawPointerPoint != default)
                {
                    // 默认调试只取一个点好了
                    break;
                }
            }

            touchInfo.AppendLine(
                $"PointerPoint PointerId={pointerInfo.pointerId} XY={pointerInfo.ptPixelLocationRaw.X},{pointerInfo.ptPixelLocationRaw.Y} rc ContactXY={info.rcContactRaw.X},{info.rcContactRaw.Y} ContactWH={info.rcContactRaw.Width},{info.rcContactRaw.Height}");
            touchInfo.AppendLine(
                $"RawPointerPoint Id={rawPointerPoint.Id} XY={rawPointerPoint.X:0.00},{rawPointerPoint.Y:0.00} RawWH={rawPointerPoint.RawWidth},{rawPointerPoint.RawHeight} PixelWH={rawPointerPoint.PixelWidth:0.00},{rawPointerPoint.PixelHeight:0.00} PhysicalWH={rawPointerPoint.PhysicalWidth:0.00},{rawPointerPoint.PhysicalHeight:0.00}cm");

            // 转换为 WPF 坐标系
            var scale = VisualTreeHelper.GetDpi(this).PixelsPerDip;
            // 计算出窗口的左上角坐标对应到屏幕坐标的点
            // 为什么不是在 PointToScreen 传入坐标点，而是传入 0 点呢？这是因为经过了 PointToScreen 方法会丢失精度，即小数点之后的内容会被丢失。因此正常的计算方法都是取 0 点计算出窗口坐标系相对于屏幕坐标系的偏移量
            // 减去偏移量之后，再经过 DPI 缩放即可获取窗口坐标系的坐标
            var originPointToScreen = this.PointToScreen(new Point(0, 0));

            var xWpf = (rawPointerPoint.X + displayRect.left - originPointToScreen.X) / scale;
            var yWpf = (rawPointerPoint.Y + displayRect.top - originPointToScreen.Y) / scale;
            var widthWpf = rawPointerPoint.PixelWidth / scale;
            var heightWpf = rawPointerPoint.PixelHeight / scale;
            touchInfo.AppendLine(
                $"RawPointerPoint For WPF XY={xWpf:0.00},{yWpf:0.00} WH={widthWpf:0.00},{heightWpf:0.00}");

            if (double.IsRealNumber(xWpf) && double.IsRealNumber(yWpf) && double.IsRealNumber(widthWpf) &&
                double.IsRealNumber(heightWpf))
            {
                TouchSizeBorder.Visibility = Visibility.Visible;
                if (TouchSizeBorder.RenderTransform is TranslateTransform translateTransform)
                {
                    translateTransform.X = xWpf - widthWpf / 2;
                    translateTransform.Y = yWpf - heightWpf / 2;
                }

                TouchSizeBorder.Width = widthWpf;
                TouchSizeBorder.Height = heightWpf;
            }

            TouchInfoTextBlock.Text += "\r\n" + touchInfo.ToString();

            return result;
        }

        return CallWindowProc(_oldWndProc, hwnd, msg, wParam, lParam);

        static string RectToString(global::Windows.Win32.Foundation.RECT rect)
        {
            return $"[XY:{rect.left},{rect.top};WH:{rect.Width},{rect.Height}]";
        }
    }

    private static int ToInt32(WPARAM wParam) => ToInt32((IntPtr) wParam.Value);
    private static int ToInt32(IntPtr ptr) => IntPtr.Size == 4 ? ptr.ToInt32() : (int) (ptr.ToInt64() & 0xffffffff);

可以看到方式3相对来说还是比较复杂的，但其优点是可以获取到更多的设备描述信息，获取到输入点的更多信息，如可以计算出触摸宽度对应的物理触摸尺寸面积等信息。我写了一个 Demo 采用了方式3获取触摸信息，可以拿到十分具体的触摸信息，包括触摸物体物理尺寸等信息。这里需要强调一点，如果期望在 WPF 获取到触摸物体物理面积等信息，则需要硬件触摸框的功能支持。只有在支持上报正确触摸面积/尺寸的触摸框下，咱才能在 WPF 里面获取到触摸信息

采用以上方式3的 Demo 的代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin c779f7cdf7970ede4fa31f73ff9f92228c7c1498

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin c779f7cdf7970ede4fa31f73ff9f92228c7c1498

获取代码之后，进入 WPFDemo/NawrernalgarGibehayle 文件夹，即可获取到源代码

对于 WPF 框架来说，自然是选最复杂且功能全强的方法了

在 WPF 框架的对接

了解了一个 Win32 应用与 WM_POINTER 消息的对接方式，咱来看看 WPF 具体是如何做的。了解了对接方式之后，阅读 WPF 源代码的方式可以是通过必须调用的方法的引用，找到整个 WPF 的脉络

在开始之前必须说明的是，本文的大部分代码都是有删减的代码，只保留和本文相关的部分。现在 WPF 是完全开源的，基于最友好的 MIT 协议，可以自己拉下来代码进行二次修改发布，想看完全的代码和调试整个过程可以自己从开源地址拉取整个仓库下来，开源地址是： https://github.com/dotnet/wpf

本文以下部分仅为开启 WM_POINTER 消息时的 WPF 框架对接的逻辑，如对不开启 WM_POINTER 支持时的逻辑感兴趣，还请参阅 WPF 触摸到事件

在 WPF 里面，触摸初始化的故事开始是在 PointerTabletDeviceCollection.cs 里面，调用 GetPointerDevices 方法进行初始化获取设备数量，之后的每个设备都调用 GetPointerDeviceProperties 方法，获取 HID 描述符上报的对应设备属性，有删减的代码如下

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// Maintains a collection of pointer device information for currently installed pointer devices
    /// </summary>
    internal class PointerTabletDeviceCollection : TabletDeviceCollection
    {
        internal void Refresh()
        {
            ... // 忽略其他代码
                    UnsafeNativeMethods.POINTER_DEVICE_INFO[] deviceInfos
                         = new UnsafeNativeMethods.POINTER_DEVICE_INFO[deviceCount];

                    IsValid = UnsafeNativeMethods.GetPointerDevices(ref deviceCount, deviceInfos);
            ... // 忽略其他代码
        }
    }
}

获取到设备之后，将其转换放入到 WPF 定义的 PointerTabletDevice 里面，大概的代码如下

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// Maintains a collection of pointer device information for currently installed pointer devices
    /// </summary>
    internal class PointerTabletDeviceCollection : TabletDeviceCollection
    {
        internal void Refresh()
        {
            ... // 忽略其他代码
                    UnsafeNativeMethods.POINTER_DEVICE_INFO[] deviceInfos
                         = new UnsafeNativeMethods.POINTER_DEVICE_INFO[deviceCount];

                    IsValid = UnsafeNativeMethods.GetPointerDevices(ref deviceCount, deviceInfos);

                    if (IsValid)
                    {
                        foreach (var deviceInfo in deviceInfos)
                        {
                            // Old PenIMC code gets this id via a straight cast from COM pointer address
                            // into an int32.  This does a very similar thing semantically using the pointer
                            // to the tablet from the WM_POINTER stack.  While it may have similar issues
                            // (chopping the upper bits, duplicate ids) we don't use this id internally
                            // and have never received complaints about this in the WISP stack.
                            int id = MS.Win32.NativeMethods.IntPtrToInt32(deviceInfo.device);

                            PointerTabletDeviceInfo ptdi = new PointerTabletDeviceInfo(id, deviceInfo);

                            // Don't add a device that fails initialization.  This means we will try a refresh
                            // next time around if we receive stylus input and the device is not available.
                            // <see cref="HwndPointerInputProvider.UpdateCurrentTabletAndStylus">
                            if (ptdi.TryInitialize())
                            {
                                PointerTabletDevice tablet = new PointerTabletDevice(ptdi);

                                _tabletDeviceMap[tablet.Device] = tablet;
                                TabletDevices.Add(tablet.TabletDevice);
                            }
                        }
                    }
            ... // 忽略其他代码
        }

        /// <summary>
        /// Holds a mapping of TabletDevices from their WM_POINTER device id
        /// </summary>
        private Dictionary<IntPtr, PointerTabletDevice> _tabletDeviceMap = new Dictionary<IntPtr, PointerTabletDevice>();
    }
}

namespace System.Windows.Input
{
    /// <summary>
    ///     Collection of the tablet devices that are available on the machine.
    /// </summary>
    public class TabletDeviceCollection : ICollection, IEnumerable
    {
        internal List<TabletDevice> TabletDevices { get; set; } = new List<TabletDevice>();
    }
}

在 PointerTabletDeviceInfo 的 TryInitialize 方法，即 if (ptdi.TryInitialize()) 这行代码里面，将会调用 GetPointerDeviceProperties 获取设备属性信息，其代码逻辑如下

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// WM_POINTER specific information about a TabletDevice
    /// </summary>
    internal class PointerTabletDeviceInfo : TabletDeviceInfo
    {
        internal PointerTabletDeviceInfo(int id, UnsafeNativeMethods.POINTER_DEVICE_INFO deviceInfo)
        {
            _deviceInfo = deviceInfo;

            Id = id;
            Name = _deviceInfo.productString;
            PlugAndPlayId = _deviceInfo.productString;
        }

        internal bool TryInitialize()
        {
            ... // 忽略其他代码

            var success = TryInitializeSupportedStylusPointProperties();

            ... // 忽略其他代码

            return success;
        }

        private bool TryInitializeSupportedStylusPointProperties()
        {
            bool success = false;

            ... // 忽略其他代码

            // Retrieve all properties from the WM_POINTER stack
            success = UnsafeNativeMethods.GetPointerDeviceProperties(Device, ref propCount, null);

            if (success)
            {
                success = UnsafeNativeMethods.GetPointerDeviceProperties(Device, ref propCount, SupportedPointerProperties);

                if (success)
                {
                    ... // 执行更具体的初始化逻辑
                }
            }

            ... // 忽略其他代码
        }

        /// <summary>
        /// The specific id for this TabletDevice
        /// </summary>
        internal IntPtr Device { get { return _deviceInfo.device; } }

        /// <summary>
        /// Store the WM_POINTER device information directly
        /// </summary>
        private UnsafeNativeMethods.POINTER_DEVICE_INFO _deviceInfo;
    }
}

为什么这里会调用 GetPointerDeviceProperties 两次？第一次只是拿数量，第二次才是真正的拿值

回顾以上代码，可以看到 PointerTabletDeviceInfo 对象是在 PointerTabletDeviceCollection 的 Refresh 方法里面创建的，如以下代码所示

    internal class PointerTabletDeviceCollection : TabletDeviceCollection
    {
        internal void Refresh()
        {
            ... // 忽略其他代码
                    UnsafeNativeMethods.POINTER_DEVICE_INFO[] deviceInfos
                         = new UnsafeNativeMethods.POINTER_DEVICE_INFO[deviceCount];

                    IsValid = UnsafeNativeMethods.GetPointerDevices(ref deviceCount, deviceInfos);
                        foreach (var deviceInfo in deviceInfos)
                        {
                            // Old PenIMC code gets this id via a straight cast from COM pointer address
                            // into an int32.  This does a very similar thing semantically using the pointer
                            // to the tablet from the WM_POINTER stack.  While it may have similar issues
                            // (chopping the upper bits, duplicate ids) we don't use this id internally
                            // and have never received complaints about this in the WISP stack.
                            int id = MS.Win32.NativeMethods.IntPtrToInt32(deviceInfo.device);

                            PointerTabletDeviceInfo ptdi = new PointerTabletDeviceInfo(id, deviceInfo);

                            if (ptdi.TryInitialize())
                            {
                                
                            }
                        }
            ... // 忽略其他代码
        }
    }

从 GetPointerDevices 获取到的 POINTER_DEVICE_INFO 信息会存放在 PointerTabletDeviceInfo 的 _deviceInfo 字段里面，如下面代码所示

    internal class PointerTabletDeviceInfo : TabletDeviceInfo
    {
        internal PointerTabletDeviceInfo(int id, UnsafeNativeMethods.POINTER_DEVICE_INFO deviceInfo)
        {
            _deviceInfo = deviceInfo;

            Id = id;
        }

        /// <summary>
        /// The specific id for this TabletDevice
        /// </summary>
        internal IntPtr Device { get { return _deviceInfo.device; } }

        /// <summary>
        /// Store the WM_POINTER device information directly
        /// </summary>
        private UnsafeNativeMethods.POINTER_DEVICE_INFO _deviceInfo;
    }

调用 GetPointerDeviceProperties 时，就会将 POINTER_DEVICE_INFO 的 device 字段作为参数传入，从而获取到 POINTER_DEVICE_PROPERTY 结构体列表信息

获取到的 POINTER_DEVICE_PROPERTY 结构体信息和 HID 描述符上报的信息非常对应。结构体的定义代码大概如下

        /// <summary>
        /// A struct representing the information for a particular pointer property.
        /// These correspond to the raw data from WM_POINTER.
        /// </summary>
        [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
        internal struct POINTER_DEVICE_PROPERTY
        {
            internal Int32 logicalMin;
            internal Int32 logicalMax;
            internal Int32 physicalMin;
            internal Int32 physicalMax;
            internal UInt32 unit;
            internal UInt32 unitExponent;
            internal UInt16 usagePageId;
            internal UInt16 usageId;
        }

根据 HID 基础知识可以知道，通过 usagePageId 和 usageId 即可了解到此设备属性的具体含义。更多请参阅 HID 标准文档： http://www.usb.org/developers/hidpage/Hut1_12v2.pdf

在 WPF 使用到的 Pointer 的 usagePageId 只有以下枚举所列举的值

        /// <summary>
        ///
        /// WM_POINTER stack must parse out HID spec usage pages
        /// <see cref="http://www.usb.org/developers/hidpage/Hut1_12v2.pdf"/> 
        /// </summary>
        internal enum HidUsagePage
        {
            Undefined = 0x00,
            Generic = 0x01,
            Simulation = 0x02,
            Vr = 0x03,
            Sport = 0x04,
            Game = 0x05,
            Keyboard = 0x07,
            Led = 0x08,
            Button = 0x09,
            Ordinal = 0x0a,
            Telephony = 0x0b,
            Consumer = 0x0c,
            Digitizer = 0x0d,
            Unicode = 0x10,
            Alphanumeric = 0x14,
            BarcodeScanner = 0x8C,
            WeighingDevice = 0x8D,
            MagneticStripeReader = 0x8E,
            CameraControl = 0x90,
            MicrosoftBluetoothHandsfree = 0xfff3,
        }

在 WPF 使用到的 Pointer 的 usageId 只有以下枚举所列举的值

       /// <summary>
       ///
       /// 
       /// WISP pre-parsed these, WM_POINTER stack must do it itself
       /// 
       /// See Stylus\biblio.txt - 1
       /// <see cref="http://www.usb.org/developers/hidpage/Hut1_12v2.pdf"/> 
       /// </summary>
       internal enum HidUsage
       {
           TipPressure = 0x30,
           X = 0x30,
           BarrelPressure = 0x31,
           Y = 0x31,
           Z = 0x32,
           XTilt = 0x3D,
           YTilt = 0x3E,
           Azimuth = 0x3F,
           Altitude = 0x40,
           Twist = 0x41,
           TipSwitch = 0x42,
           SecondaryTipSwitch = 0x43,
           BarrelSwitch = 0x44,
           TouchConfidence = 0x47,
           Width = 0x48,
           Height = 0x49,
           TransducerSerialNumber = 0x5B,
       }

在 WPF 的古老版本里面，约定了使用 GUID 去获取 StylusPointDescription 里面的额外数据信息。为了与此行为兼容，在 WPF 里面就定义了 HidUsagePage 和 HidUsage 与 GUID 的对应关系，实现代码如下

namespace System.Windows.Input
{
    /// <summary>
    /// StylusPointPropertyIds
    /// </summary>
    /// <ExternalAPI/>
    internal static class StylusPointPropertyIds
    {
        /// <summary>
        /// The x-coordinate in the tablet coordinate space.
        /// </summary>
        /// <ExternalAPI/>
        public static readonly Guid X = new Guid(0x598A6A8F, 0x52C0, 0x4BA0, 0x93, 0xAF, 0xAF, 0x35, 0x74, 0x11, 0xA5, 0x61);
        /// <summary>
        /// The y-coordinate in the tablet coordinate space.
        /// </summary>
        /// <ExternalAPI/>
        public static readonly Guid Y = new Guid(0xB53F9F75, 0x04E0, 0x4498, 0xA7, 0xEE, 0xC3, 0x0D, 0xBB, 0x5A, 0x90, 0x11);

        public static readonly Guid Z = ...

        ...

        /// <summary>
        ///
        /// WM_POINTER stack usage preparation based on associations maintained from the legacy WISP based stack
        /// </summary>
        private static Dictionary<HidUsagePage, Dictionary<HidUsage, Guid>> _hidToGuidMap = new Dictionary<HidUsagePage, Dictionary<HidUsage, Guid>>()
        {
            { HidUsagePage.Generic,
                new Dictionary<HidUsage, Guid>()
                {
                    { HidUsage.X, X },
                    { HidUsage.Y, Y },
                    { HidUsage.Z, Z },
                }
            },
            { HidUsagePage.Digitizer,
                new Dictionary<HidUsage, Guid>()
                {
                    { HidUsage.Width, Width },
                    { HidUsage.Height, Height },
                    { HidUsage.TouchConfidence, SystemTouch },
                    { HidUsage.TipPressure, NormalPressure },
                    { HidUsage.BarrelPressure, ButtonPressure },
                    { HidUsage.XTilt, XTiltOrientation },
                    { HidUsage.YTilt, YTiltOrientation },
                    { HidUsage.Azimuth, AzimuthOrientation },
                    { HidUsage.Altitude, AltitudeOrientation },
                    { HidUsage.Twist, TwistOrientation },
                    { HidUsage.TipSwitch, TipButton },
                    { HidUsage.SecondaryTipSwitch, SecondaryTipButton },
                    { HidUsage.BarrelSwitch, BarrelButton },
                    { HidUsage.TransducerSerialNumber, SerialNumber },
                }
            },
        };

        /// <summary>
        /// Retrieves the GUID of the stylus property associated with the usage page and usage ids
        /// within the HID specification.
        /// </summary>
        /// <param name="page">The usage page id of the HID specification</param>
        /// <param name="usage">The usage id of the HID specification</param>
        /// <returns>
        /// If known, the GUID associated with the usagePageId and usageId.
        /// If not known, GUID.Empty
        /// </returns>
        internal static Guid GetKnownGuid(HidUsagePage page, HidUsage usage)
        {
            Guid result = Guid.Empty;

            Dictionary<HidUsage, Guid> pageMap = null;

            if (_hidToGuidMap.TryGetValue(page, out pageMap))
            {
                pageMap.TryGetValue(usage, out result);
            }

            return result;
        }
    }
}

通过以上的 _hidToGuidMap 的定义关联关系，调用 GetKnownGuid 方法，即可将 POINTER_DEVICE_PROPERTY 描述信息关联到 WPF 框架层的定义

具体的对应逻辑如下

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// Contains a WM_POINTER specific functions to parse out stylus property info
    /// </summary>
    internal class PointerStylusPointPropertyInfoHelper
    {
        /// <summary>
        /// Creates WPF property infos from WM_POINTER device properties.  This appropriately maps and converts HID spec
        /// properties found in WM_POINTER to their WPF equivalents.  This is based on code from the WISP implementation
        /// that feeds the legacy WISP based stack.
        /// </summary>
        /// <param name="prop">The pointer property to convert</param>
        /// <returns>The equivalent WPF property info</returns>
        internal static StylusPointPropertyInfo CreatePropertyInfo(UnsafeNativeMethods.POINTER_DEVICE_PROPERTY prop)
        {
            StylusPointPropertyInfo result = null;

            // Get the mapped GUID for the HID usages
            Guid propGuid =
                StylusPointPropertyIds.GetKnownGuid(
                    (StylusPointPropertyIds.HidUsagePage)prop.usagePageId,
                    (StylusPointPropertyIds.HidUsage)prop.usageId);

            if (propGuid != Guid.Empty)
            {
                StylusPointProperty stylusProp = new StylusPointProperty(propGuid, StylusPointPropertyIds.IsKnownButton(propGuid));

                // Set Units
                StylusPointPropertyUnit? unit = StylusPointPropertyUnitHelper.FromPointerUnit(prop.unit);

                // If the parsed unit is invalid, set the default
                if (!unit.HasValue)
                {
                    unit = StylusPointPropertyInfoDefaults.GetStylusPointPropertyInfoDefault(stylusProp).Unit;
                }

                // Set to default resolution
                float resolution = StylusPointPropertyInfoDefaults.GetStylusPointPropertyInfoDefault(stylusProp).Resolution;

                short mappedExponent = 0;

                if (_hidExponentMap.TryGetValue((byte)(prop.unitExponent & HidExponentMask), out mappedExponent))
                {
                    float exponent = (float)Math.Pow(10, mappedExponent);

                    // Guard against divide by zero or negative resolution
                    if (prop.physicalMax - prop.physicalMin > 0)
                    {
                        // Calculated resolution is a scaling factor from logical units into the physical space
                        // at the given exponentiation.
                        resolution =
                            (prop.logicalMax - prop.logicalMin) / ((prop.physicalMax - prop.physicalMin) * exponent);
                    }
                }

                result = new StylusPointPropertyInfo(
                      stylusProp,
                      prop.logicalMin,
                      prop.logicalMax,
                      unit.Value,
                      resolution);
            }

            return result;
        }
    }
}

以上的一个小细节点在于对 unit 单位的处理，即 StylusPointPropertyUnit? unit = StylusPointPropertyUnitHelper.FromPointerUnit(prop.unit); 这行代码的实现定义，具体实现如下

    internal static class StylusPointPropertyUnitHelper
    {
        /// <summary>
        /// Convert WM_POINTER units to WPF units
        /// </summary>
        /// <param name="pointerUnit"></param>
        /// <returns></returns>
        internal static StylusPointPropertyUnit? FromPointerUnit(uint pointerUnit)
        {
            StylusPointPropertyUnit unit = StylusPointPropertyUnit.None;

            _pointerUnitMap.TryGetValue(pointerUnit & UNIT_MASK, out unit);

            return (IsDefined(unit)) ? unit : (StylusPointPropertyUnit?)null;
        }

        /// <summary>
        /// Mapping for WM_POINTER based unit, taken from legacy WISP code
        /// </summary>
        private static Dictionary<uint, StylusPointPropertyUnit> _pointerUnitMap = new Dictionary<uint, StylusPointPropertyUnit>()
        {
            { 1, StylusPointPropertyUnit.Centimeters },
            { 2, StylusPointPropertyUnit.Radians },
            { 3, StylusPointPropertyUnit.Inches },
            { 4, StylusPointPropertyUnit.Degrees },
        };

        /// <summary>
        /// Mask to extract units from raw WM_POINTER data
        /// <see cref="http://www.usb.org/developers/hidpage/Hut1_12v2.pdf"/> 
        /// </summary>
        private const uint UNIT_MASK = 0x000F;
    }

这里的单位的作用是什么呢？用于和 POINTER_DEVICE_PROPERTY 的物理值做关联对应关系，比如触摸面积 Width 和 Height 的物理尺寸就是通过大概如下算法计算出来的

                short mappedExponent = 0;

                if (_hidExponentMap.TryGetValue((byte)(prop.unitExponent & HidExponentMask), out mappedExponent))
                {
                    float exponent = (float)Math.Pow(10, mappedExponent);

                    // Guard against divide by zero or negative resolution
                    if (prop.physicalMax - prop.physicalMin > 0)
                    {
                        // Calculated resolution is a scaling factor from logical units into the physical space
                        // at the given exponentiation.
                        resolution =
                            (prop.logicalMax - prop.logicalMin) / ((prop.physicalMax - prop.physicalMin) * exponent);
                    }
                }

        /// <summary>
        /// Contains the mappings from WM_POINTER exponents to our local supported values.
        /// This mapping is taken from WISP code, see Stylus\Biblio.txt - 4,
        /// as an array of HidExponents.
        /// </summary>
        private static Dictionary<byte, short> _hidExponentMap = new Dictionary<byte, short>()
        {
            { 5, 5 },
            { 6, 6 },
            { 7, 7 },
            { 8, -8 },
            { 9, -7 },
            { 0xA, -6 },
            { 0xB, -5 },
            { 0xC, -4 },
            { 0xD, -3 },
            { 0xE, -2 },
            { 0xF, -1 },
        };

通过 resolution 与具体后续收到的触摸点的值进行计算，带上 StylusPointPropertyUnit 单位，这就是触摸设备上报的物理尺寸了

以上 logicalMax 和 logicalMin 在行业内常被称为逻辑值，以上的 physicalMax 和 physicalMin 常被称为物理值

经过以上的处理之后，即可将 GetPointerDeviceProperties 拿到的设备属性列表给转换为 WPF 框架对应的定义属性内容

以上过程有一个细节，那就是 GetPointerDeviceProperties 拿到的设备属性列表的顺序是非常关键的，设备属性列表的顺序和在后续 WM_POINTER 消息拿到的裸数据的顺序是直接对应的

大家可以看到，在开启 Pointer 消息时，触摸模块初始化获取触摸信息是完全通过 Win32 的 WM_POINTER 模块提供的相关方法完成的。这里需要和不开 WM_POINTER 消息的从 COM 获取触摸设备信息区分，和 dotnet 读 WPF 源代码笔记插入触摸设备的初始化获取设备信息提供的方法是不相同的

完成上述初始化逻辑之后，接下来看看消息循环收到 WM_POINTER 消息的处理

收到 WM_POINTER 消息时，调用 GetRawPointerDeviceData 获取最原始的触摸信息，再对原始触摸信息进行解析处理

在 WPF 里面，大家都知道，底层的消息循环处理的在 HwndSource.cs 里面定义，输入处理部分如下

namespace System.Windows.Interop
{
    /// <summary>
    ///     The HwndSource class presents content within a Win32 HWND.
    /// </summary>
    public class HwndSource : PresentationSource, IDisposable, IWin32Window, IKeyboardInputSink
    {
        private IntPtr InputFilterMessage(IntPtr hwnd, int msg, IntPtr wParam, IntPtr lParam, ref bool handled)
        {
            ... // 忽略其他代码
            // NOTE (alexz): invoke _stylus.FilterMessage before _mouse.FilterMessage
            // to give _stylus a chance to eat mouse message generated by stylus
            if (!_isDisposed && _stylus != null && !handled)
            {
                result = _stylus.Value.FilterMessage(hwnd, message, wParam, lParam, ref handled);
            }
            ... // 忽略其他代码
        }

        private SecurityCriticalDataClass<IStylusInputProvider>        _stylus;
    }
}

以上代码的 _stylus 就是根据不同的配置参数决定是否使用 Pointer 消息处理的 HwndPointerInputProvider 类型，代码如下

namespace System.Windows.Interop
{
    /// <summary>
    ///     The HwndSource class presents content within a Win32 HWND.
    /// </summary>
    public class HwndSource : PresentationSource, IDisposable, IWin32Window, IKeyboardInputSink
    {
        private void Initialize(HwndSourceParameters parameters)
        {
            ... // 忽略其他代码
            if (StylusLogic.IsStylusAndTouchSupportEnabled)
            {
                // Choose between Wisp and Pointer stacks
                if (StylusLogic.IsPointerStackEnabled)
                {
                    _stylus = new SecurityCriticalDataClass<IStylusInputProvider>(new HwndPointerInputProvider(this));
                }
                else
                {
                    _stylus = new SecurityCriticalDataClass<IStylusInputProvider>(new HwndStylusInputProvider(this));
                }
            }
            ... // 忽略其他代码
        }
    }
}

在本文这里初始化的是 HwndPointerInputProvider 类型，将会进入到 HwndPointerInputProvider 的 FilterMessage 方法处理输入数据

namespace System.Windows.Interop
{
    /// <summary>
    /// Implements an input provider per hwnd for WM_POINTER messages
    /// </summary>
    internal sealed class HwndPointerInputProvider : DispatcherObject, IStylusInputProvider
    {
        /// <summary>
        /// Processes the message loop for the HwndSource, filtering WM_POINTER messages where needed
        /// </summary>
        /// <param name="hwnd">The hwnd the message is for</param>
        /// <param name="msg">The message</param>
        /// <param name="wParam"></param>
        /// <param name="lParam"></param>
        /// <param name="handled">If this has been successfully processed</param>
        /// <returns></returns>
        IntPtr IStylusInputProvider.FilterMessage(IntPtr hwnd, WindowMessage msg, IntPtr wParam, IntPtr lParam, ref bool handled)
        {
            handled = false;

            // Do not process any messages if the stack was disabled via reflection hack
            if (PointerLogic.IsEnabled)
            {
                switch (msg)
                {
                    case WindowMessage.WM_ENABLE:
                        {
                            IsWindowEnabled = MS.Win32.NativeMethods.IntPtrToInt32(wParam) == 1;
                        }
                        break;
                    case WindowMessage.WM_POINTERENTER:
                        {
                            // Enter can be processed as an InRange.  
                            // The MSDN documentation is not correct for InRange (according to feisu)
                            // As such, using enter is the correct way to generate this.  This is also what DirectInk uses.
                            handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.InRange, Environment.TickCount);
                        }
                        break;
                    case WindowMessage.WM_POINTERUPDATE:
                        {
                            handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.Move, Environment.TickCount);
                        }
                        break;
                    case WindowMessage.WM_POINTERDOWN:
                        {
                            handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.Down, Environment.TickCount);
                        }
                        break;
                    case WindowMessage.WM_POINTERUP:
                        {
                            handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.Up, Environment.TickCount);
                        }
                        break;
                    case WindowMessage.WM_POINTERLEAVE:
                        {
                            // Leave can be processed as an OutOfRange.  
                            // The MSDN documentation is not correct for OutOfRange (according to feisu)
                            // As such, using leave is the correct way to generate this.  This is also what DirectInk uses.
                            handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.OutOfRange, Environment.TickCount);
                        }
                        break;
                }
            }

            return IntPtr.Zero;
        }

        ... // 忽略其他代码
    }
}

对于收到 Pointer 的按下移动抬起消息，都会进入到 ProcessMessage 方法

进入之前调用的 GetPointerId(wParam) 代码的 GetPointerId 方法实现如下

        /// <summary>
        /// Extracts the pointer id
        /// </summary>
        /// <param name="wParam">The parameter containing the id</param>
        /// <returns>The pointer id</returns>
        private uint GetPointerId(IntPtr wParam)
        {
            return (uint)MS.Win32.NativeMethods.SignedLOWORD(wParam);
        }

    internal partial class NativeMethods
    {
        public static int SignedLOWORD(IntPtr intPtr)
        {
            return SignedLOWORD(IntPtrToInt32(intPtr));
        }

        public static int IntPtrToInt32(IntPtr intPtr)
        {
            return unchecked((int)intPtr.ToInt64());
        }

        public static int SignedLOWORD(int n)
        {
            int i = (int)(short)(n & 0xFFFF);

            return i;
        }
    }

当然了，以上代码简单写就和下面代码差不多

            var pointerId = (uint) (ToInt32(wparam) & 0xFFFF);

在 WM_POINTER 的设计上，将会源源不断通过消息循环发送指针消息，发送的指针消息里面不直接包含具体的数据信息，而是只将 PointerId 当成 wparam 发送。咱从消息循环里面拿到的只有 PointerId 的值，转换方法如上述代码所示

为什么是这样设计的呢？考虑到现在大部分触摸屏的精度都不低，至少比许多很便宜鼠标的高，这就可能导致应用程序完全无法顶得住每次触摸数据过来都通过消息循环怼进来。在 WM_POINTER 的设计上，只是将 PointerId 通过消息循环发送过来，具体的消息体数据需要使用 GetPointerInfo 方法来获取。这么设计有什么优势？这么设计是用来解决应用卡顿的时候，被堆积消息的问题。假定现在有三个触摸消息进来，第一个触摸消息进来就发送了 Win32 消息给到应用，然而应用等待到系统收集到了三个触摸点消息时，才调用 GetPointerInfo 方法。那此时系统触摸模块就可以很开森的知道了应用处于卡顿状态，即第二个和第三个触摸消息到来时，判断第一个消息还没被应用消费，就不再发送 Win32 消息给到应用。当应用调用 GetPointerInfo 方法时，就直接返回第三个点给到应用，跳过中间第一个和第二个触摸点。同时，使用历史点的概念，将第一个点和第二个点和第三个点给到应用，如果此时应用感兴趣的话

利用如上所述机制，即可实现到当触摸设备产生的触摸消息过快时，不会让应用的消息循环过度忙碌，而是可以让应用有机会一次性拿到过去一段时间内的多个触摸点信息。如此可以提升整体系统的性能，减少应用程序忙碌于处理过往的触摸消息

举一个虚拟的例子，让大家更好的理解这套机制的思想。假定咱在制作一个应用，应用有一个功能，就是有一个矩形元素，这个元素可以响应触摸拖动，可以用触摸拖动矩形元素。这个应用编写的有些离谱，每次拖动的做法就是设置新的坐标点为当前触摸点，但是这个过程需要 15 毫秒，因为中间添加了一些有趣且保密（其实我还没编出来）的算法。当应用跑在一个触摸设备上，这个触摸设备在触摸拖动的过程中，每 10 毫秒将产生一次触摸点信息报告给到系统。假定当前的系统的触摸模块是如实的每次收到设备发送过来的触摸点，都通过 Win32 消息发送给到应用，那将会让应用的消费速度慢于消息的生产速度，这就意味着大家可以明显看到拖动矩形元素时具备很大的延迟感。如拖着拖着才发现矩形元素还在后面慢慢挪动，整体的体验比较糟糕。那如果采用现在的这套玩法呢？应用程序从 Win32 消息收到的是 PointerId 信息，再通过 GetPointerInfo 方法获取触摸点信息，此时获取到的触摸点就是最后一个触摸点，对于咱这个应用来说刚刚好，直接就是响应设置矩形元素坐标为最后一个触摸点的对应坐标。如此即可看到矩形元素飞快跳着走，且由于刚好矩形元素拖动过程为 15 毫秒，小于 16 毫秒，意味着大部分情况下大家看到的是矩形元素平滑的移动，即飞快跳着走在人类看来是一个连续移动的过程

期望通过以上的例子可以让大家了解到微软的“良苦”用心

这里需要额外说明的是 PointerId 和 TouchDevice 等的 Id 是不一样的，在下文将会给出详细的描述

在 WPF 这边，如上面代码所示，收到触摸点信息之后，将会进入到 ProcessMessage 方法，只是这个过程中我感觉有一点小锅的是，时间戳拿的是当前系统时间戳 Environment.TickCount 的值，而不是取 Pointer 消息里面的时间戳内容

继续看一下 ProcessMessage 方法的定义和实现

namespace System.Windows.Interop
{
    /// <summary>
    /// Implements an input provider per hwnd for WM_POINTER messages
    /// </summary>
    internal sealed class HwndPointerInputProvider : DispatcherObject, IStylusInputProvider
    {
        /// <summary>
        /// Processes the latest WM_POINTER message and forwards it to the WPF input stack.
        /// </summary>
        /// <param name="pointerId">The id of the pointer message</param>
        /// <param name="action">The stylus action being done</param>
        /// <param name="timestamp">The time (in ticks) the message arrived</param>
        /// <returns>True if successfully processed (handled), false otherwise</returns>
        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {
            ... // 忽略其他代码
        }
    }

    ... // 忽略其他代码
}

在 ProcessMessage 里面将创建 PointerData 对象，这个 PointerData 类型是一个辅助类，在构造函数里面将调用 GetPointerInfo 方法获取指针点信息

        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {
            bool handled = false;

            // Acquire all pointer data needed
            PointerData data = new PointerData(pointerId);

            ... // 忽略其他代码
        }

以下是 PointerData 构造函数的简单定义的有删减的代码

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// Provides a wrapping class that aggregates Pointer data from a pointer event/message
    /// </summary>
    internal class PointerData
    {
        /// <summary>
        /// Queries all needed data from a particular pointer message and stores
        /// it locally.
        /// </summary>
        /// <param name="pointerId">The id of the pointer message</param>
        internal PointerData(uint pointerId)
        {
            if (IsValid = GetPointerInfo(pointerId, ref _info))
            {
                _history = new POINTER_INFO[_info.historyCount];

                // Fill the pointer history
                // If we fail just return a blank history
                if (!GetPointerInfoHistory(pointerId, ref _info.historyCount, _history))
                {
                    _history = Array.Empty<POINTER_INFO>();
                }

                ... // 忽略其他代码
            }
        }

        /// <summary>
        /// Standard pointer information
        /// </summary>
        private POINTER_INFO _info;

        /// <summary>
        /// The full history available for the current pointer (used for coalesced input)
        /// </summary>
        private POINTER_INFO[] _history;

        /// <summary>
        /// If true, we have correctly queried pointer data, false otherwise.
        /// </summary>
        internal bool IsValid { get; private set; } = false;
    }

通过上述代码可以看到，开始是调用 GetPointerInfo 方法获取指针点信息。在 WPF 的基础事件里面也是支持历史点的，意图和 Pointer 的设计意图差不多，都是为了解决业务端的消费数据速度问题。于是在 WPF 底层也就立刻调用 GetPointerInfoHistory 获取历史点信息

对于 Pointer 消息来说，对触摸和触笔有着不同的数据提供分支，分别是 GetPointerTouchInfo 方法和 GetPointerPenInfo 方法

在 PointerData 构造函数里面，也通过判断 POINTER_INFO 的 pointerType 字段决定调用不同的方法，代码如下

            if (IsValid = GetPointerInfo(pointerId, ref _info))
            {
                switch (_info.pointerType)
                {
                    case POINTER_INPUT_TYPE.PT_TOUCH:
                        {
                            // If we have a touch device, pull the touch specific information down
                            IsValid &= GetPointerTouchInfo(pointerId, ref _touchInfo);
                        }
                        break;
                    case POINTER_INPUT_TYPE.PT_PEN:
                        {
                            // Otherwise we have a pen device, so pull down pen specific information
                            IsValid &= GetPointerPenInfo(pointerId, ref _penInfo);
                        }
                        break;
                    default:
                        {
                            // Only process touch or pen messages, do not process mouse or touchpad
                            IsValid = false;
                        }
                        break;
                }
            }

对于 WPF 的 HwndPointerInputProvider 模块来说，只处理 PT_TOUCH 和 PT_PEN 消息，即触摸和触笔消息。对于 Mouse 鼠标和 Touchpad 触摸板来说都不走 Pointer 处理，依然是走原来的 Win32 消息。为什么这么设计呢？因为 WPF 里面没有 Pointer 路由事件，在 WPF 里面分开了 Touch 和 Stylus 和 Mouse 事件。就不需要全部都在 Pointer 模块处理了，依然在原来的消息循环里面处理，既减少 Pointer 模块的工作量，也能减少后续从 Pointer 分发到 Touch 和 Stylus 和 Mouse 事件的工作量。原先的模块看起来也跑得很稳，那就一起都不改了

完成 PointerData 的构造函数之后，继续到 HwndPointerInputProvider 的 ProcessMessage 函数里面，在此函数里面判断是 PT_TOUCH 和 PT_PEN 消息，则进行处理

        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {
            bool handled = false;

            // Acquire all pointer data needed
            PointerData data = new PointerData(pointerId);

            // Only process touch or pen messages, do not process mouse or touchpad
            if (data.IsValid
                && (data.Info.pointerType == UnsafeNativeMethods.POINTER_INPUT_TYPE.PT_TOUCH
                || data.Info.pointerType == UnsafeNativeMethods.POINTER_INPUT_TYPE.PT_PEN))
            {
                ... // 忽略其他代码
            }

            return handled;
        }

对于触摸和触笔的处理上，先是执行触摸设备关联。触摸设备关联一个在上层业务的表现就是让当前的指针消息关联上 TouchDevice 的 Id 或 StylusDevice 的 Id 值

关联的方法是通过 GetPointerCursorId 方法先获取 CursorId 的值，再配合对应的输入的 Pointer 的输入设备 POINTER_INFO 的 sourceDevice 字段，即可与初始化过程中创建的设备相关联，实现代码如下

            if (data.IsValid
                && (data.Info.pointerType == UnsafeNativeMethods.POINTER_INPUT_TYPE.PT_TOUCH
                || data.Info.pointerType == UnsafeNativeMethods.POINTER_INPUT_TYPE.PT_PEN))
            {
                uint cursorId = 0;

                if (UnsafeNativeMethods.GetPointerCursorId(pointerId, ref cursorId))
                {
                    IntPtr deviceId = data.Info.sourceDevice;

                    // If we cannot acquire the latest tablet and stylus then wait for the
                    // next message.
                    if (!UpdateCurrentTabletAndStylus(deviceId, cursorId))
                    {
                        return false;
                    }

                     ... // 忽略其他代码
                }

                ... // 忽略其他代码
            }

在 WPF 初始化工作里面将输入的 Pointer 的输入设备 POINTER_INFO 的 sourceDevice 当成 deviceId 的概念，即 TabletDevice 的 Id 值。而 cursorId 则是对应 StylusDevice 的 Id 值，其更新代码的核心非常简单，如下面代码

        /// <summary>
        /// Attempts to update the current stylus and tablet devices for the latest WM_POINTER message.
        /// Will attempt retries if the tablet collection is invalid or does not contain the proper ids.
        /// </summary>
        /// <param name="deviceId">The id of the TabletDevice</param>
        /// <param name="cursorId">The id of the StylusDevice</param>
        /// <returns>True if successfully updated, false otherwise.</returns>
        private bool UpdateCurrentTabletAndStylus(IntPtr deviceId, uint cursorId)
        {
            _currentTabletDevice = tablets?.GetByDeviceId(deviceId);

            _currentStylusDevice = _currentTabletDevice?.GetStylusByCursorId(cursorId);
            
            ... // 忽略其他代码

                if (_currentTabletDevice == null || _currentStylusDevice == null)
                {
                    return false;
                }
            

            return true;
        }

对应的 GetByDeviceId 方法的代码如下

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// Maintains a collection of pointer device information for currently installed pointer devices
    /// </summary>
    internal class PointerTabletDeviceCollection : TabletDeviceCollection
    {
        /// <summary>
        /// Holds a mapping of TabletDevices from their WM_POINTER device id
        /// </summary>
        private Dictionary<IntPtr, PointerTabletDevice> _tabletDeviceMap = new Dictionary<IntPtr, PointerTabletDevice>();

         ... // 忽略其他代码

        /// <summary>
        /// Retrieve the TabletDevice associated with the device id
        /// </summary>
        /// <param name="deviceId">The device id</param>
        /// <returns>The TabletDevice associated with the device id</returns>
        internal PointerTabletDevice GetByDeviceId(IntPtr deviceId)
        {
            PointerTabletDevice tablet = null;

            _tabletDeviceMap.TryGetValue(deviceId, out tablet);

            return tablet;
        }
    }
}

对应的 GetStylusByCursorId 的代码如下

namespace System.Windows.Input.StylusPointer
{  
    /// <summary>
    /// A WM_POINTER based implementation of the TabletDeviceBase class.
    /// </summary>
    internal class PointerTabletDevice : TabletDeviceBase
    {
        /// <summary>
        /// A mapping from StylusDevice id to the actual StylusDevice for quick lookup.
        /// </summary>
        private Dictionary<uint, PointerStylusDevice> _stylusDeviceMap = new Dictionary<uint, PointerStylusDevice>();

        /// <summary>
        /// Retrieves the StylusDevice associated with the cursor id.
        /// </summary>
        /// <param name="cursorId">The id of the StylusDevice to retrieve</param>
        /// <returns>The StylusDevice associated with the id</returns>
        internal PointerStylusDevice GetStylusByCursorId(uint cursorId)
        {
            PointerStylusDevice stylus = null;
            _stylusDeviceMap.TryGetValue(cursorId, out stylus);
            return stylus;
        }
    }
}

通过以上方式即可通过 PointerId 获取的 cursorId 进而获取到对应 WPF 里面的设备对象，进而拿到 WPF 里面的设备 Id 号。通过上文的描述也可以看到 PointerId 和 TouchDevice 等的 Id 是不一样的，但是之间有关联关系

调用了 UpdateCurrentTabletAndStylus 的一个副作用就是同步更新了 _currentTabletDevice 和 _currentStylusDevice 字段的值，后续逻辑即可直接使用这两个字段而不是传参数

完成关联逻辑之后，即进入 GenerateRawStylusData 方法，这个方法是 WPF 获取 Pointer 具体的消息的核心方法，方法签名如下

namespace System.Windows.Interop
{
    /// <summary>
    /// Implements an input provider per hwnd for WM_POINTER messages
    /// </summary>
    internal sealed class HwndPointerInputProvider : DispatcherObject, IStylusInputProvider
    {
        /// <summary>
        /// Creates raw stylus data from the raw WM_POINTER properties
        /// </summary>
        /// <param name="pointerData">The current pointer info</param>
        /// <param name="tabletDevice">The current TabletDevice</param>
        /// <returns>An array of raw pointer data</returns>
        private int[] GenerateRawStylusData(PointerData pointerData, PointerTabletDevice tabletDevice)
        {
            ... // 忽略其他代码
        }

        ... // 忽略其他代码
    }
}

此 GenerateRawStylusData 被调用是这么写的

namespace System.Windows.Interop
{
    /// <summary>
    /// Implements an input provider per hwnd for WM_POINTER messages
    /// </summary>
    internal sealed class HwndPointerInputProvider : DispatcherObject, IStylusInputProvider
    {
        /// <summary>
        /// Processes the latest WM_POINTER message and forwards it to the WPF input stack.
        /// </summary>
        /// <param name="pointerId">The id of the pointer message</param>
        /// <param name="action">The stylus action being done</param>
        /// <param name="timestamp">The time (in ticks) the message arrived</param>
        /// <returns>True if successfully processed (handled), false otherwise</returns>
        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {
            PointerData data = new PointerData(pointerId);

            ... // 忽略其他代码
                uint cursorId = 0;
                if (UnsafeNativeMethods.GetPointerCursorId(pointerId, ref cursorId))
                {
                    ... // 忽略其他代码
                    GenerateRawStylusData(data, _currentTabletDevice);
                    ... // 忽略其他代码
                }

        }
        ... // 忽略其他代码
    }
}

在 GenerateRawStylusData 方法里面，先通过 PointerTabletDevice 取出支持的 Pointer 的设备属性列表的长度，用于和输入点的信息进行匹配。回忆一下，这部分获取逻辑是在上文介绍到对 GetPointerDeviceProperties 函数的调用提到的，且也说明了此函数拿到的设备属性列表的顺序是非常关键的，设备属性列表的顺序和在后续 WM_POINTER 消息拿到的裸数据的顺序是直接对应的

    /// <summary>
    /// Implements an input provider per hwnd for WM_POINTER messages
    /// </summary>
    internal sealed class HwndPointerInputProvider : DispatcherObject, IStylusInputProvider
    {
        /// <summary>
        /// Creates raw stylus data from the raw WM_POINTER properties
        /// </summary>
        /// <param name="pointerData">The current pointer info</param>
        /// <param name="tabletDevice">The current TabletDevice</param>
        /// <returns>An array of raw pointer data</returns>
        private int[] GenerateRawStylusData(PointerData pointerData, PointerTabletDevice tabletDevice)
        {
            // Since we are copying raw pointer data, we want to use every property supported by this pointer.
            // We may never access some of the unknown (unsupported by WPF) properties, but they should be there
            // for consumption by the developer.
            int pointerPropertyCount = tabletDevice.DeviceInfo.SupportedPointerProperties.Length;

            // The data is as wide as the pointer properties and is per history point
            int[] rawPointerData = new int[pointerPropertyCount * pointerData.Info.historyCount];

            ... // 忽略其他代码
        }

        ... // 忽略其他代码
    }

由每个 Pointer 的属性长度配合总共的历史点数量，即可获取到这里面使用到的 rawPointerData 数组的长度。这部分代码相信大家很好就理解了

接着就是核心部分，调用 GetRawPointerDeviceData 获取最原始的触摸信息，再对原始触摸信息进行解析处理

            int pointerPropertyCount = tabletDevice.DeviceInfo.SupportedPointerProperties.Length;

            // The data is as wide as the pointer properties and is per history point
            int[] rawPointerData = new int[pointerPropertyCount * pointerData.Info.historyCount];

            // Get the raw data formatted to our supported properties
            if (UnsafeNativeMethods.GetRawPointerDeviceData(
                pointerData.Info.pointerId,
                pointerData.Info.historyCount,
                (uint)pointerPropertyCount,
                tabletDevice.DeviceInfo.SupportedPointerProperties,
                rawPointerData))
            {
                ... // 忽略其他代码
            }

在 Pointer 的设计里面，历史点 historyCount 是包含当前点的，且当前点就是最后一个点。这就是为什么这里只需要传入历史点数量即可，换句话说就是历史点最少包含一个点，那就是当前点

由于 Pointer 获取到的点都是相对于屏幕坐标的，这里需要先偏移一下修改为窗口坐标系，代码如下

                // Get the X and Y offsets to translate device coords to the origin of the hwnd
                int originOffsetX, originOffsetY;
                GetOriginOffsetsLogical(out originOffsetX, out originOffsetY);

        private void GetOriginOffsetsLogical(out int originOffsetX, out int originOffsetY)
        {
            Point originScreenCoord = _source.Value.RootVisual.PointToScreen(new Point(0, 0));

            // Use the inverse of our logical tablet to screen matrix to generate tablet coords
            MatrixTransform screenToTablet = new MatrixTransform(_currentTabletDevice.TabletToScreen);
            screenToTablet = (MatrixTransform)screenToTablet.Inverse;

            Point originTabletCoord = originScreenCoord * screenToTablet.Matrix;

            originOffsetX = (int)Math.Round(originTabletCoord.X);
            originOffsetY = (int)Math.Round(originTabletCoord.Y);
        }

        /// <summary>
        /// The HwndSource for WM_POINTER messages
        /// </summary>
        private SecurityCriticalDataClass<HwndSource> _source;

这里的 GetOriginOffsetsLogical 的实现逻辑就是取窗口的 0,0 点，看这个点会在屏幕的哪里，从而知道其偏移量。至于添加到 MatrixTransform 矩阵的 TabletToScreen 则在后文的具体转换逻辑会讲到，这里先跳过

获取到相对于窗口的坐标偏移量之后，即可将其叠加给到每个点上，用于将这些点转换为窗口坐标系。但是在此之前还需要将获取到的 rawPointerData 进行加工。这一个步骤仅仅只是在 WPF 有需求，仅仅只是为了兼容 WISP 获取到的裸数据的方式。其相差点在于通过 Pointer 获取到的 rawPointerData 的二进制数据格式里面，没有带上按钮的支持情况的信息，在 WPF 这边需要重新创建一个数组对 rawPointerData 重新排列，确保每个点的数据都加上按钮的信息数据

这部分处理仅只是为了兼容考虑，让后续的 StylusPointCollection 开森而已，咱就跳着看就好了

                int numButtons = tabletDevice.DeviceInfo.SupportedPointerProperties.Length - tabletDevice.DeviceInfo.SupportedButtonPropertyIndex;

                int rawDataPointSize = (numButtons > 0) ? pointerPropertyCount - numButtons + 1 : pointerPropertyCount;

                // Instead of a single entry for each button we use one entry for all buttons so reflect that in the raw data size
                data = new int[rawDataPointSize * pointerData.Info.historyCount];

                for (int i = 0, j = rawPointerData.Length - pointerPropertyCount; i < data.Length; i += rawDataPointSize, j -= pointerPropertyCount)
                {
                    Array.Copy(rawPointerData, j, data, i, rawDataPointSize);

                    // Apply offsets from the origin to raw pointer data here
                    data[i + StylusPointDescription.RequiredXIndex] -= originOffsetX;
                    data[i + StylusPointDescription.RequiredYIndex] -= originOffsetY;

                    ... // 忽略其他代码
                }

             ... // 忽略其他代码
            return data;

重新拷贝的过程，还将点的坐标更换成窗口坐标系，即以上的 data[i + StylusPointDescription.RequiredXIndex] -= originOffsetX; 和 data[i + StylusPointDescription.RequiredYIndex] -= originOffsetY; 两个代码

完成获取之后，就将获取到的裸数据给返回了，这就是 GenerateRawStylusData 的内容

在 ProcessMessage 方法里面获取到 GenerateRawStylusData 返回的原始指针信息，即可将其给到 RawStylusInputReport 作为参数，代码如下

                    // Generate a raw input to send to the input manager to start the event chain in PointerLogic
                    Int32[] rawData = GenerateRawStylusData(data, _currentTabletDevice);
                    RawStylusInputReport rsir =
                        new RawStylusInputReport(
                            InputMode.Foreground,
                            timestamp,
                            _source.Value,
                            action,
                            () => { return _currentTabletDevice.StylusPointDescription; },
                            _currentTabletDevice.Id,
                            _currentStylusDevice.Id,
                            rawData)
                        {
                            StylusDevice = _currentStylusDevice.StylusDevice,
                        };

将创建的 RawStylusInputReport 更新到当前的设备，作为设备的最新的指针信息

        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {

            PointerData data = new PointerData(pointerId);

             ... // 忽略其他代码

                    _currentStylusDevice.Update(this, _source.Value, data, rsir);
             ... // 忽略其他代码
        }

        private SecurityCriticalDataClass<HwndSource> _source;

且还加入到 InputManager 的 ProcessInput 里面，进入 WPF 的框架内的消息调度

        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {

            PointerData data = new PointerData(pointerId);

             ... // 忽略其他代码

                    _currentStylusDevice.Update(this, _source.Value, data, rsir);
                    // Now send the input report
                    InputManager.UnsecureCurrent.ProcessInput(irea);
             ... // 忽略其他代码
        }

在进入 InputManager 的 ProcessInput 调度消息之前，先看看 _currentStylusDevice.Update 里面的对原始指针信息的解析实现逻辑

在 _currentStylusDevice.Update 里面的对原始指针信息的解析实现完全是靠 StylusPointCollection 和 StylusPoint 的构造函数实现的

namespace System.Windows.Input.StylusPointer
{
    /// <summary>
    /// A WM_POINTER specific implementation of the StylusDeviceBase.
    /// 
    /// Supports direct access to WM_POINTER structures and basing behavior off of the WM_POINTER data.
    /// </summary>
    internal class PointerStylusDevice : StylusDeviceBase
    {
        /// <summary>
        /// Updates the internal StylusDevice state based on the WM_POINTER input and the formed raw data.
        /// </summary>
        /// <param name="provider">The hwnd associated WM_POINTER provider</param>
        /// <param name="inputSource">The PresentationSource where this message originated</param>
        /// <param name="pointerData">The aggregated pointer data retrieved from the WM_POINTER stack</param>
        /// <param name="rsir">The raw stylus input generated from the pointer data</param>
        internal void Update(HwndPointerInputProvider provider, PresentationSource inputSource,
            PointerData pointerData, RawStylusInputReport rsir)
        {
             ... // 忽略其他代码

            // First get the initial stylus points.  Raw data from pointer input comes in screen coordinates, keep that here since that is what we expect.
            _currentStylusPoints = new StylusPointCollection(rsir.StylusPointDescription, rsir.GetRawPacketData(), GetTabletToElementTransform(null), Matrix.Identity);

             ... // 忽略其他代码
        }
    }
}

这里的 rsir.GetRawPacketData() 是返回上文提到的 GenerateRawStylusData 方法给出的裸数据的拷贝，代码如下

    internal class RawStylusInputReport : InputReport
    {
        /// <summary>
        ///     Read-only access to the raw data that was reported.
        /// </summary>
        internal int[] GetRawPacketData()
        {
            if (_data == null)
                return null;
            return (int[])_data.Clone();
        }

        /// <summary>
        /// The raw data for this input report
        /// </summary>
        int[] _data;

        ... // 忽略其他代码
    }

这里的 GetTabletToElementTransform 包含了一个核心转换，方法代码如下

    internal class PointerStylusDevice : StylusDeviceBase
    {
        /// <summary>
        ///     Returns the transform for converting from tablet to element
        ///     relative coordinates.
        /// </summary>
        internal GeneralTransform GetTabletToElementTransform(IInputElement relativeTo)
        {
            GeneralTransformGroup group = new GeneralTransformGroup();
            Matrix toDevice = _inputSource.Value.CompositionTarget.TransformToDevice;
            toDevice.Invert();
            group.Children.Add(new MatrixTransform(PointerTabletDevice.TabletToScreen * toDevice));
            group.Children.Add(StylusDevice.GetElementTransform(relativeTo));
            return group;
        }

        ... // 忽略其他代码
    }

这里面方法存在重点内容，那就是 PointerTabletDevice 的 TabletToScreen 属性的计算方法。这个矩阵的计算需要用到开始初始化过程的 GetPointerDeviceRects 函数获取的 displayRect 尺寸，以及 GetPointerDeviceProperties 获取的 X 和 Y 属性描述信息，属性的定义代码如下

        internal Matrix TabletToScreen
        {
            get
            {
                return new Matrix(_tabletInfo.SizeInfo.ScreenSize.Width / _tabletInfo.SizeInfo.TabletSize.Width, 0,
                                   0, _tabletInfo.SizeInfo.ScreenSize.Height / _tabletInfo.SizeInfo.TabletSize.Height,
                                   0, 0);
            }
        }

可以看到这是一个用于缩放的 Matrix 对象，正是 GetPointerDeviceRects 获取的屏幕尺寸以及 GetPointerDeviceProperties 获取的 X 和 Y 属性描述信息构成的 TabletSize 的比值

回顾一下 _tabletInfo 的 SizeInfo 的创建代码，可以看到 TabletSize 完全是由描述符的尺寸决定，代码如下

            // 以下代码在 PointerTabletDeviceInfo.cs 文件中
            // private bool TryInitializeSupportedStylusPointProperties()
            SupportedPointerProperties = new UnsafeNativeMethods.POINTER_DEVICE_PROPERTY[propCount];

            success = UnsafeNativeMethods.GetPointerDeviceProperties(Device, ref propCount, SupportedPointerProperties);

            ... // 忽略其他代码

            // private bool TryInitializeDeviceRects()
            var deviceRect = new UnsafeNativeMethods.RECT();
            var displayRect = new UnsafeNativeMethods.RECT();

            success = UnsafeNativeMethods.GetPointerDeviceRects(_deviceInfo.device, ref deviceRect, ref displayRect);

            if (success)
            {
                // We use the max X and Y properties here as this is more readily useful for raw data
                // which is where all conversions come from.
                SizeInfo = new TabletDeviceSizeInfo
                (
                    new Size(SupportedPointerProperties[StylusPointDescription.RequiredXIndex].logicalMax,
                    SupportedPointerProperties[StylusPointDescription.RequiredYIndex].logicalMax),

                    new Size(displayRect.right - displayRect.left, displayRect.bottom - displayRect.top)
                );
            }

    internal struct TabletDeviceSizeInfo
    {
        public Size TabletSize;
        public Size ScreenSize;

        internal TabletDeviceSizeInfo(Size tabletSize, Size screenSize)
        {
            TabletSize = tabletSize;
            ScreenSize = screenSize;
        }
    }

如此即可使用 TabletToScreen 属性将收到的基于 Tablet 坐标系的裸指针消息的坐标转换为屏幕坐标，再配合 TransformToDevice 取反即可转换到 WPF 坐标系

在以上代码里面，由于传入 GetTabletToElementTransform 的 relativeTo 参数是 null 的值，将导致 StylusDevice.GetElementTransform(relativeTo) 返回一个单位矩阵，这就意味着在 GetTabletToElementTransform 方法里面的 group.Children.Add(StylusDevice.GetElementTransform(relativeTo)); 是多余的，也许后续 WPF 版本这里会被我优化掉

回顾一下 StylusPointCollection 的构造函数参数，有用的参数只有前三个，分别是 rsir.StylusPointDescription 传入描述符信息，以及 rsir.GetRawPacketData() 返回裸指针数据，以及 GetTabletToElementTransform(null) 方法返回转换为 WPF 坐标系的矩阵

_currentStylusPoints = new StylusPointCollection(rsir.StylusPointDescription, rsir.GetRawPacketData(), GetTabletToElementTransform(null), Matrix.Identity);

那 StylusPointCollection 的最后一个参数，即上述代码传入的 Matrix.Identity 有什么用途？其实在 StylusPointCollection 的设计里面，第三个参数和第四个参数是二选一的，且第三个参数的优先级大于第四个参数。即在 StylusPointCollection 底层会判断第三个参数是否有值，如果没有值才会使用第四个参数

在 StylusPointCollection 构造函数里面将会对裸 Pointer 数据进行处理，现在 GetRawPacketData 拿到的裸 Pointer 数据的 int 数组里面的数据排列内容大概如下

| X 坐标 | Y 坐标 | 压感（可选）| StylusPointDescription 里面的属性列表一一对应 |
| X 坐标 | Y 坐标 | 压感（可选）| StylusPointDescription 里面的属性列表一一对应 |
| X 坐标 | Y 坐标 | 压感（可选）| StylusPointDescription 里面的属性列表一一对应 |

存放的是一个或多个点信息，每个点的信息都是相同的二进制长度，分包非常简单

进入到 StylusPointCollection 的构造函数，看看其代码签名定义

namespace System.Windows.Input
{
    public class StylusPointCollection : Collection<StylusPoint>
    {
        internal StylusPointCollection(StylusPointDescription stylusPointDescription, int[] rawPacketData, GeneralTransform tabletToView, Matrix tabletToViewMatrix)
        {
            ... // 忽略其他代码
        }
    }
}

在构造函数里面，先调用 StylusPointDescription 的 GetInputArrayLengthPerPoint 方法，获取每个点的二进制长度，代码如下

    public class StylusPointCollection : Collection<StylusPoint>
    {
        internal StylusPointCollection(StylusPointDescription stylusPointDescription, int[] rawPacketData, GeneralTransform tabletToView, Matrix tabletToViewMatrix)
        {
            ... // 忽略其他代码
            int lengthPerPoint = stylusPointDescription.GetInputArrayLengthPerPoint();

            ... // 忽略其他代码
        }
    }

获取到了一个点的二进制长度，自然就能算出传入的 rawPacketData 参数包含多少个点的信息

        internal StylusPointCollection(StylusPointDescription stylusPointDescription, int[] rawPacketData, GeneralTransform tabletToView, Matrix tabletToViewMatrix)
        {
            ... // 忽略其他代码
            int lengthPerPoint = stylusPointDescription.GetInputArrayLengthPerPoint();
            int logicalPointCount = rawPacketData.Length / lengthPerPoint;
            Debug.Assert(0 == rawPacketData.Length % lengthPerPoint, "Invalid assumption about packet length, there shouldn't be any remainder");
            ... // 忽略其他代码
        }

以上代码的 Debug.Assert 就是要确保传入的 rawPacketData 是可以被 lengthPerPoint 即每个点的二进制长度所整除

完成准备工作之后，接下来就可以将 rawPacketData 解出点了，如下面代码所示

            int lengthPerPoint = stylusPointDescription.GetInputArrayLengthPerPoint();
            int logicalPointCount = rawPacketData.Length / lengthPerPoint;

            for (int count = 0, i = 0; count < logicalPointCount; count++, i += lengthPerPoint)
            {
                //first, determine the x, y values by xf-ing them
                Point p = new Point(rawPacketData[i], rawPacketData[i + 1]);

                ... // 忽略其他代码

                int startIndex = 2;

                ... // 忽略其他代码

                int[] data = null;
                int dataLength = lengthPerPoint - startIndex;
                if (dataLength > 0)
                {
                    //copy the rest of the data
                    var rawArrayStartIndex = i + startIndex;
                    data = rawPacketData.AsSpan(rawArrayStartIndex, dataLength).ToArray();
                }

                StylusPoint newPoint = new StylusPoint(p.X, p.Y, StylusPoint.DefaultPressure, _stylusPointDescription, data, false, false);

                ... // 忽略其他代码

                ((List<StylusPoint>)this.Items).Add(newPoint);
            }

以上代码忽略的部分包含了一些细节，如对 Point 的坐标转换，使用 Point p = new Point(rawPacketData[i], rawPacketData[i + 1]); 拿到的点的坐标是属于 Tablet 坐标，需要使用传入的参数转换为 WPF 坐标，如下面代码所示

        internal StylusPointCollection(StylusPointDescription stylusPointDescription, int[] rawPacketData, GeneralTransform tabletToView, Matrix tabletToViewMatrix)
        {
                ... // 忽略其他代码

                Point p = new Point(rawPacketData[i], rawPacketData[i + 1]);
                if (tabletToView != null)
                {
                    tabletToView.TryTransform(p, out p);
                }
                else
                {
                    p = tabletToViewMatrix.Transform(p);
                }

                ... // 忽略其他代码
        }

通过以上的代码就可以看到 StylusPointCollection 构造函数使用了第三个或第四个参数作为变换，如果第三个参数存在则优先使用第三个参数

其他处理的逻辑就是对压感的额外处理，压感作为 StylusPoint 的一个明确参数，需要额外判断处理

                int startIndex = 2; // X 和 Y 占用了两个元素
                bool containsTruePressure = stylusPointDescription.ContainsTruePressure;
                if (containsTruePressure)
                {
                    // 如果有压感的话，压感也需要多占一个元素
                    //don't copy pressure in the int[] for extra data
                    startIndex++;
                }

                StylusPoint newPoint = new StylusPoint(p.X, p.Y, StylusPoint.DefaultPressure, _stylusPointDescription, data, false, false);
                if (containsTruePressure)
                {
                    // 压感必定是第三个元素，有压感则更新压感
                    //use the algorithm to set pressure in StylusPoint
                    int pressure = rawPacketData[i + 2];
                    newPoint.SetPropertyValue(StylusPointProperties.NormalPressure, pressure);
                }

                int[] data = null;
                int dataLength = lengthPerPoint - startIndex;
                if (dataLength > 0)
                {
                    //copy the rest of the data
                    var rawArrayStartIndex = i + startIndex;
                    data = rawPacketData.AsSpan(rawArrayStartIndex, dataLength).ToArray();
                }

后续对 StylusPoint 获取属性时，即可通过描述信息获取，描述信息获取到值的方式就是取以上代码传入的 data 二进制数组的对应下标的元素，比如触摸点的宽度或高度信息

完成转换为 StylusPointCollection 之后，即可使用 InputManager.UnsecureCurrent.ProcessInput 方法将裸输入信息调度到 WPF 输入管理器

        private bool ProcessMessage(uint pointerId, RawStylusActions action, int timestamp)
        {
             ... // 忽略其他代码
                    InputReportEventArgs irea = new InputReportEventArgs(_currentStylusDevice.StylusDevice, rsir)
                    {
                        RoutedEvent = InputManager.PreviewInputReportEvent,
                    };

                    // Now send the input report
                    InputManager.UnsecureCurrent.ProcessInput(irea);
             ... // 忽略其他代码
        }

进入到 ProcessInput 里面将会走标准的路由事件机制，通过路由机制触发 Touch 或 Stylus 事件，接下来的逻辑看一下调用堆栈即可，和其他的输入事件逻辑差不多

>   Lindexi.dll!Lindexi.MainWindow.MainWindow_TouchDown(object sender, System.Windows.Input.TouchEventArgs e)
    PresentationCore.dll!System.Windows.RoutedEventArgs.InvokeHandler(System.Delegate handler, object target)
    PresentationCore.dll!System.Windows.EventRoute.InvokeHandlersImpl(object source, System.Windows.RoutedEventArgs args, bool reRaised) 
    PresentationCore.dll!System.Windows.UIElement.RaiseEventImpl(System.Windows.DependencyObject sender, System.Windows.RoutedEventArgs args)
    PresentationCore.dll!System.Windows.UIElement.RaiseTrustedEvent(System.Windows.RoutedEventArgs args) 
    PresentationCore.dll!System.Windows.Input.InputManager.ProcessStagingArea()
    PresentationCore.dll!System.Windows.Input.TouchDevice.RaiseTouchDown() 
    PresentationCore.dll!System.Windows.Input.TouchDevice.ReportDown() 
    PresentationCore.dll!System.Windows.Input.StylusTouchDeviceBase.OnDown() 
    PresentationCore.dll!System.Windows.Input.StylusPointer.PointerLogic.PromoteMainDownToTouch(System.Windows.Input.StylusPointer.PointerStylusDevice stylusDevice, System.Windows.Input.StagingAreaInputItem stagingItem)
    PresentationCore.dll!System.Windows.Input.InputManager.RaiseProcessInputEventHandlers(System.Tuple<System.Windows.Input.ProcessInputEventHandler, System.Delegate[]> postProcessInput, System.Windows.Input.ProcessInputEventArgs processInputEventArgs) 
    PresentationCore.dll!System.Windows.Input.InputManager.ProcessStagingArea()
    PresentationCore.dll!System.Windows.Interop.HwndPointerInputProvider.ProcessMessage(uint pointerId, System.Windows.Input.RawStylusActions action, int timestamp) 
    PresentationCore.dll!System.Windows.Interop.HwndPointerInputProvider.System.Windows.Interop.IStylusInputProvider.FilterMessage(nint hwnd, MS.Internal.Interop.WindowMessage msg, nint wParam, nint lParam, ref bool handled) 
    PresentationCore.dll!System.Windows.Interop.HwndSource.InputFilterMessage(nint hwnd, int msg, nint wParam, nint lParam, ref bool handled)

由于我跑的是 Release 版本的 WPF 导致了有一些函数被内联，如从 HwndPointerInputProvider.ProcessMessage 到 InputManager.ProcessStagingArea 中间就少了 InputManager.ProcessInput 函数，完全的无函数内联的堆栈应该如下

    PresentationCore.dll!System.Windows.Input.InputManager.ProcessStagingArea()
    PresentationCore.dll!System.Windows.Input.InputManager.ProcessInput()
    PresentationCore.dll!System.Windows.Interop.HwndPointerInputProvider.ProcessMessage(uint pointerId, System.Windows.Input.RawStylusActions action, int timestamp)

如下面代码是 ProcessInput 函数的代码

    public sealed class InputManager : DispatcherObject
    {
        public bool ProcessInput(InputEventArgs input)
        {
            ... // 忽略其他代码
            PushMarker();
            PushInput(input, null);
            RequestContinueProcessingStagingArea();

            bool handled = ProcessStagingArea();
            return handled;
        }
    }

进入到 ProcessStagingArea 方法会执行具体的调度逻辑，用上述触摸按下的堆栈作为例子，将会进入到 PointerLogic 的 PostProcessInput 方法里面，由 PostProcessInput 方法调用到 PromoteMainToOther 再到 PromoteMainToTouch 最后到 PromoteMainDownToTouch 方法。只不过中间的几个方法被内联了，直接从堆栈上看就是从 RaiseProcessInputEventHandlers 到 PromoteMainDownToTouch 方法，堆栈如下

PresentationCore.dll!System.Windows.Input.StylusPointer.PointerLogic.PromoteMainDownToTouch(...)
PresentationCore.dll!System.Windows.Input.InputManager.RaiseProcessInputEventHandlers(...)

核心触发按下的代码就在 PromoteMainDownToTouch 里，其代码大概如下

        private void PromoteMainDownToTouch(PointerStylusDevice stylusDevice, StagingAreaInputItem stagingItem)
        {
            PointerTouchDevice touchDevice = stylusDevice.TouchDevice;

            ... // 忽略其他代码

            touchDevice.OnActivate();
            touchDevice.OnDown();
        }

从上文可以知道，在 HwndPointerInputProvider 的 ProcessMessage 里面调用了 _currentStylusDevice.Update 方法时，就将输入的数据存放到 PointerStylusDevice 里面

后续的逻辑就和 WPF 模拟触摸设备提到的使用方法差不多，只是数据提供源是从 PointerStylusDevice 提供。如果大家对进入到 InputManager 的后续逻辑感兴趣，可参考 WPF 通过 InputManager 模拟调度触摸事件提供的方法自己跑一下

在 WPF 里面，除了走 WM_Pointer 之外，还有默认的 RealTimeStylus 机制。根据 lsj 大佬的考古，预计在 Win10 的版本下，底层的 RealTimeStylus 机制的数据也是从 WM_Pointer 里面来的，如下图所示

以上的 581 和 582 等就是对应的 WM_Pointer 消息号。更多细节信息请参阅 WPF 从零自己实现从 RealTimeStylus 获取触摸信息

更多触摸请看 WPF 触摸相关

dotnet 源代码生成器分析器入门

Tue, 07 Apr 2026 22:01:24 +0000

本文将带领大家入门 dotnet 的 SourceGenerator 源代码生成器技术，期待大家阅读完本文能够看懂理解和编写源代码生成器和分析器

恭喜你看到了本文，进入到 C# dotnet 的深水区。如果你还是在浅水玩耍的小鲜肉，推荐你点击右上方的关闭按钮，避免受到过于深入的知识的污染

我所在的团队在 Rosyln 刚出来没两年就开始玩了，那时候还没有现在这么多机制。我之前很多关于 Rosyln 的博客都涉及到了很底层的玩法，导致入门门槛过高。随着 dotnet 生态的不断建设，渐渐有了源代码生成技术、增量源代码生成技术等等。这次我打算综合之前的经验和知识，根据现在的 dotnet 的生态技术，编写这篇入门博客，让大家更好地入门源代码生成器和分析器，降低入门门槛。本文将尽量使用比较缓的知识爬坡方式编写，以便让大家更舒适地进入到源代码生成器和分析器的世界

在开始之前期望大家已经了解基础的 dotnet C# 基础知识，了解基础的概念和项目组织结构

在阅读本文过程中，发现本文有任何错误或不足之处，欢迎大家在评论区留言或发送邮件给我，我会尽快修正。如果大家有任何问题或疑问，也欢迎大家在评论区留言或发送邮件给我，我会尽快回复

本文内容比较长，知识量比较多，推荐先点收藏

项目搭建

本文先从项目搭建开始告诉大家如何创建一个源代码生成器项目。本文后续的内容将会在这个项目中进行演示。本文的编写顺序是先搭建项目，然后再讲解一些基础的概念和用法，再到如何进行调试，最后提供一些实际的演练给到大家。基础知识部分也放在演练里面，先做演练再讲基础知识，防止一口气拍出大量基础知识劝退大家

本文的推荐打开方式是一边阅读本文，一边打开 Visual Studio 2022 或更高版本，对照本文的内容进行操作。照着本文的内容对照着编写代码，可以让大家更好地理解本文的内容，照着过一遍预计就能掌握基础的源代码生成器和分析器的知识，入门源代码生成器和分析器的编写

本文过程中会添加一些外部链接文档，这些外部链接文档都是可选阅读内容，只供大家感兴趣时扩展阅读。本文的核心内容是在本文中编写的，不需要阅读外部链接文档也能够掌握本文的内容。作为入门博客，我担心自己编写过程中存在高手盲区问题，于是尽可能将更多细节写出来，尽管这样会导致一些重复的表述

先新建一个控制台项目，新建完成之后在 Visual Studio 2022 或更高版本中打开项目，双击 csproj 项目文件，即可进行编辑项目文件

本文这里新建了一个名为 DercelgefarKarhelchaye.Analyzer 的控制台项目。也许细心的伙伴发现了这个项目使用了 Analyzer 作为后缀，这是因为在 dotnet 中源代码生成器和分析器是一体的，按照历史原因的惯性，依然将其命名为分析器项目。在 Visual Studio 2022 的每个项目依赖项里面，大家都会看到如下图的一个名为分析器的项，而没有专门一个名为源代码生成器的项，其原因也是如此

如果在这一步就开始卡住了也不用慌，本文在整个过程中都会给出示例代码。我整个代码仓库比较庞大，使用本文各个部分提供的拉取源代码的命令行代码，可以减少拉取的数据，提升拉取的速度，且能够确保切换到正确的 commit 代码

创建之后，在 Visual Studio 的解决方案里的界面大概如下

编辑名为 DercelgefarKarhelchaye.Analyzer 的控制台项目的 csproj 项目文件，将其 TargetFramework 降级到 netstandard2.0 版本，且按照 dotnet 的惯例，使用 NuGet 添加必要的组件。编辑之后的 csproj 项目文件的内容如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

为什么需要降级为 netstandard2.0 版本？这是为了让此分析器项目能够同时在 dotnet CLI 和 Visual Studio 2022 里面使用。在 Visual Studio 2022 里，当前依然使用的是 .NET Framework 的版本。于是求最小公倍数，选择了 netstandard2.0 版本。预计后续版本才能使用到最新的 dotnet 框架版本

由于分析器本身需要利用到部分 VisualStudio 的基础设施支持，为了能够在 VisualStudio 里面更好地工作，某些情况下需要关注 Microsoft.CodeAnalysis.CSharp 库的版本，尽管大部分情况下都不应该惯着开发者，直接有多新就用多新，详细请参阅支持的 Roslyn 包版本映射 - Visual Studio (Windows) - Microsoft Learn

以上的 <LangVersion>latest</LangVersion> 只是为了方便让咱使用最新的语言特性。前面选择的 netstandard2.0 会导致语言特性默认开得比较低，这里设置为 latest 可以让我们使用最新的语言特性，让代码编写更加方便。这里需要再次提醒，在 dotnet 里面，语言和框架是分开的。使用低版本框架也能使用高版本语言。如果对语言和框架的关系依然有所疑惑，推荐先了解一下 dotnet 的基础知识，不要着急往下看。编写源代码生成器和分析器需要对 dotnet 有一定的了解，否则写着就开始混淆概念了

以上的 <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules> 的作用是强制执行扩展分析器规则。这个属性是为了让我们在编写分析器的时候能够更加严格，让我们的代码更加规范。这里大家不需要细致了解，如有兴趣，请参阅 Roslyn 分析器 EnforceExtendedAnalyzerRules 属性的作用

以上的 Microsoft.CodeAnalysis.Analyzers 和 Microsoft.CodeAnalysis.CSharp 是必须的组件。Microsoft.CodeAnalysis.Analyzers 是分析器的基础组件，Microsoft.CodeAnalysis.CSharp 是 C# 的基础组件。这两个组件是必须的，没有这两个组件，我们就无法编写分析器和源代码生成器

通过以上的步骤也可以让大家看到，其实 dotnet 分析器项目也没什么特殊的，依然可以通过一个简单的控制台项目修改而来。其核心关键仅仅只是安装了 Microsoft.CodeAnalysis.Analyzers 和 Microsoft.CodeAnalysis.CSharp 两个组件而已

现在只是有了一个空的分析器项目，但是还不知道这个项目的效果。为了让分析器项目工作，那就需要有一个被分析的项目。为此咱就再次新建一个控制台项目，让这个控制台项目成为被分析项目

我这里新建了一个名为 DercelgefarKarhelchaye 的控制台项目。编辑 DercelgefarKarhelchaye 的 csproj 项目文件，让其引用 DercelgefarKarhelchaye.Analyzer 项目，且设置 DercelgefarKarhelchaye.Analyzer 为分析器。编辑之后的 csproj 项目文件的内容如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\DercelgefarKarhelchaye.Analyzer\DercelgefarKarhelchaye.Analyzer.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false"/>
  </ItemGroup>

</Project>

可以看到以上的 csproj 项目文件和正常的控制台项目的差别仅仅只有在对 DercelgefarKarhelchaye.Analyzer.csproj 的引用上。且和正常的引用项目的方式不同的是，这里额外添加了 OutputItemType="Analyzer" ReferenceOutputAssembly="false" 两个配置。这两个配置的作用如下：

以上的 OutputItemType="Analyzer" 是告诉 dotnet 这个引用项目是一个分析器项目。这个配置是必须的，没有这个配置，dotnet 就不知道这个项目是一个分析器项目。通过这个配置是告诉 dotnet 这个项目是一个分析器项目，才能让 dotnet 在编译的时候能够正确地当成分析器处理这个项目
以上的 ReferenceOutputAssembly="false" 是告诉 dotnet 不要引用这个项目的输出程序集。正常的项目是不应该引用分析器项目的程序集的，分析器项目的作用仅仅只是作为分析器，而不是提供程序集给其他项目引用。这个配置是为了让 dotnet 在编译的时候不要引用这个项目的输出程序集，避免引用错误或导致不小心用了不应该使用的类型

对于正常的项目引用来说，一旦存在项目引用，那被引用的项目的输出程序集就会被引用。此时项目上就可以使用被引用项目的公开类型，以及获取 NuGet 包依赖传递等。但是对于分析器项目来说，这些都是不应该的，正常就不能让项目引用分析器项目的输出程序集。这就是为什么会额外添加 ReferenceOutputAssembly="false" 配置的原因

在这里，咱接触到了非常多次的 csproj 项目文件，如果大家对 csproj 项目文件格式感兴趣，请参阅理解 C# 项目 csproj 文件格式的本质和编译流程 - walterlv

以上的步骤完成之后，最简单的分析器项目和被分析的项目就搭建完成了。这也是分析器的基础，大部分的带分析器的代码都是如此方式搭建的。但也有其他部分是通过 NuGet 带出去的分析器，被 NuGet 带出去的分析器能够更好做到开箱即用，不需要让分析器尝试构建。在后文将会讲解如何将分析器通过 NuGet 带出去，即如何进行分发分析器

现在的分析器项目还没有任何源代码生成和分析的功能，接下来咱将编写简单的源代码生成的代码，让大家看到源代码生成器的效果

编写源代码生成器

在 DercelgefarKarhelchaye.Analyzer 项目中新建一个名为 IncrementalGenerator 的源代码生成器类。编辑 IncrementalGenerator 类，让其继承 IIncrementalGenerator 接口，实现 Initialize 方法，且标记 [Generator(LanguageNames.CSharp)] 特性。编辑之后的 IncrementalGenerator 类的内容如下

using Microsoft.CodeAnalysis;

namespace DercelgefarKarhelchaye.Analyzer;

[Generator(LanguageNames.CSharp)]
public class IncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        ... // 忽略其他代码
    }
}

本文这里直接就是和大家介绍 IIncrementalGenerator 增量 Source Generator 源代码生成器技术，不再介绍 ISourceGenerator 源代码生成器技术。其原因是在 2022 之后，官方大力推荐的是使用 IIncrementalGenerator 增量源代码生成器技术。从业务上讲，仅仅只是 IIncrementalGenerator 多了增量的功能，在进行源代码生成逻辑处理中没有太大的差别。功能上 IIncrementalGenerator 也能完全代替 ISourceGenerator 的功能。但是在性能上，IIncrementalGenerator 要比 ISourceGenerator 更加高效，更加快速，更加能够防止原本已经很卡的 Visual Studio 更加卡

整个 IIncrementalGenerator 的入口都在 Initialize 方法里面，从 IncrementalGeneratorInitializationContext 参数里可以点出来非常多有用的方法。咱这里先不展开讲解这些方法，先让大家看到一个简单的源代码生成器的效果

在 Initialize 方法里面，咱可以通过 context.RegisterPostInitializationOutput 方法注册一个源代码输出。如以下代码所示，将输出一个名为 GeneratedCode 的代码

    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        context.RegisterPostInitializationOutput(initializationContext =>
        {
            initializationContext.AddSource("GeneratedCode.cs",
                """
                using System;
                namespace DercelgefarKarhelchaye
                {
                    public static class GeneratedCode
                    {
                        public static void Print()
                        {
                            Console.WriteLine("Hello from generated code!");
                        }
                    }
                }
                """);
        });
    }

预期此时能够将生成的 GeneratedCode 类型注入到被分析的项目中。在被分析的项目中，可以通过 GeneratedCode.Print() 方法输出 Hello from generated code! 字符串

好的，进入到 DercelgefarKarhelchaye 项目中，编辑 Program 类，调用 GeneratedCode.Print() 方法。编辑之后的 Program 类的内容如下

using DercelgefarKarhelchaye;

GeneratedCode.Print();

尝试运行一下 DercelgefarKarhelchaye 项目，可以看到控制台输出了 Hello from generated code! 字符串。这就是源代码生成器的效果，通过源代码生成器生成的代码，注入到被分析的项目中，让被分析的项目能够使用生成的代码

如此证明了在 DercelgefarKarhelchaye.Analyzer 分析器项目中编写的源代码生成器生效了。这就是源代码生成器的基硋，通过源代码生成器生成的代码，注入到被分析的项目中，让被分析的项目能够使用生成的代码

以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 95c14524130238b2d6fbca97ca35b89dc921536b

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 95c14524130238b2d6fbca97ca35b89dc921536b

获取代码之后，进入 Roslyn/DercelgefarKarhelchaye 文件夹，即可获取到源代码

分析和生成入门

在上文中，和大家介绍了如何生成静态的固定的代码内容。在 RegisterPostInitializationOutput 方法里面，只允许传递静态固定的代码，不能依据当前项目状态或配置进行动态生成代码。这是因为 RegisterPostInitializationOutput 方法的定义上就是用于提供分析器开始分析工作之前的初始化代码。这部分代码由于可不用运行分析过程，可以非常快给到 IDE 层，一般用于提供一些类型定义，可以给到开发者直接快速使用，而不会在使用过程中飘红

上文的代码只是让大家粗略熟悉了一下 IIncrementalGenerator 的 API 调用方法。接下来我将带大家开始入门分析器的分析和生成功能

分析和生成很多时候都是不分离的，生成的代码需要依赖分析的结果。为了能让大家更好理解分析器的入门知识，我尝试布置一个任务，接下来让咱根据布置的任务来入门分析和生成功能

任务

咱来实现一个经典的需求任务，将项目里面的标记了某个 Attribute 特性的类型全收集起来，最后生成一个代码，让生成的代码输出有哪些类型标记了这个 Attribute 特性，将这些类型的名称输出到控制台

进一步分解任务需求，咱需要有一个源代码生成器。源代码生成器生成两部分代码，第一部分就是 FooAttribute 特性，第二部分就是收集所有标记了 FooAttribute 特性的类型，生成将这些类型的名称输出到控制台的代码。要求全程没有反射参与，全程都是通过 Roslyn 分析和生成完成

使用 ForAttributeWithMetadataName 快速分析代码

从工程上进行分析发现，非常大量的分析生成任务都有一个特点，这个特点就是需要找到标记了某个 Attribute 特性的类型或方法或属性等，然后再做某个事情。这个特点其实源自于 dotnet C# 对于 Attribute 特性的设计。Attribute 特性是一种元数据，可以标记在类型、方法、属性等上面，用于描述这个类型、方法、属性等的特性。也常常用于标记给 IDE 和编译器看的，用于告诉 IDE 和编译器这个类型、方法、属性等的特性。比如常用的 ObsoleteAttribute 、CallerMemberNameAttribute 、DebuggerDisplayAttribute 等等

在 IIncrementalGenerator 增量 Source Generator 源代码生成器中，提供了 ForAttributeWithMetadataName 工具方法。如此方法名所述，这个方法是用于找到标记了某个 Attribute 特性的类型、方法、属性等。这个方法的使用非常简单，只需要传递一个 Attribute 特性的完整名称，就可以找到标记了这个 Attribute 特性的类型、方法、属性等

在上文的任务中，咱需要找到标记了某个 Attribute 特性的类型，然后将这些类型的名称输出到控制台。这个任务非常适合使用 ForAttributeWithMetadataName 方法来实现。接下来咱就来实现这个任务

依然是新建两个项目，其中一个作为分析器项目，另一个作为被分析的项目。大家既可以在上文现有的项目中继续编写，也可以新建两个项目。这里我新建了一个名为 NinahajawhuLairfoheahurcee.Analyzer 的分析器项目，和一个名为 NinahajawhuLairfoheahurcee 的被分析项目。本文内容里面只给出关键代码片段，如需要全部的项目文件，可在下文找到所有代码的下载方法。如果自己编写的代码构建不通过或运行输出不符合预期，也推荐大家拉取本文的代码进行阅读

先来完成任务需求分解中的第一部分，编写 FooAttribute 特性代码的生成。由于 FooAttribute 特性的代码不依赖任何分析结果，因此可以使用 RegisterPostInitializationOutput 方法生成。修改上文的 RegisterPostInitializationOutput 注册 GeneratedCode.cs 的代码，将其替换为 FooAttribute.cs 的生成代码，如下所示

[Generator(LanguageNames.CSharp)]
public class IncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        // 先注册一个特性给到业务方使用
        context.RegisterPostInitializationOutput(initializationContext =>
        {
            initializationContext.AddSource("FooAttribute.cs",
                """
                namespace Lindexi;

                public class FooAttribute : Attribute
                {
                }
                """);
        });
    }
}

完成这一步之后，即可在业务端编写类型，将类型标记上 FooAttribute 特性。回到名为 NinahajawhuLairfoheahurcee 的被分析项目，在 NinahajawhuLairfoheahurcee 控制台项目里面添加两个类型，让这两个类型标记上 FooAttribute 特性，用于后续测试类型被收集

using Lindexi;

namespace NinahajawhuLairfoheahurcee;

[Foo]
public class F1
{
}

[Foo]
public class F2
{
}

在 IIncrementalGenerator 增量 Source Generator 源代码生成，可在 IncrementalGeneratorInitializationContext 里面的 SyntaxProvider 属性，通过 ForAttributeWithMetadataName 快速收集标记了某个特性的类型、属性、方法等等

基本写法格式如下

var provider =
    context.SyntaxProvider.ForAttributeWithMetadataName
    (
        "特性名",
        (SyntaxNode node, CancellationToken token) => 语法判断条件,
        (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken token) => 语义处理和获取返回值
    );

第一个参数是特性名，记得带上特性的命名空间，以及写明特性的全名。在正常的 C# 代码里面，都会忽略 Attribute 后缀，但是在这里需要带上 Attribute 后缀。第二个参数是语法判断条件，用于判断当前节点是否符合条件。第三个参数是语义处理和获取返回值，用于处理当前节点的语义，获取返回值

那什么是语法，什么是语义呢？在 Roslyn 里面，将初步的代码分析的语法层面内容称为 Syntax 语法。语法是非常贴近编写出来的代码直接的内存映射的样子，这个过程里面只做片面考虑，即不考虑代码之间的引用关系，只考虑代码语法本身。语法分析过程是最早的过程，也是损耗极小的过程，也是可以并行化执行的过程。一般来说，进行语法分析都可以将写出来的代码分为一个个 SyntaxTree 语法树，每个代码或代码片都可以转换为一个 SyntaxNode 语法节点

对应于 Syntax 语法的概念，语义 Semantic 则是包含了代码的含义，不仅仅只是语法层面上，语义 Semantic 包含了代码之间的引用关系，包含了各个符号的信息。语义分析过程是在语法分析之后的过程，执行过程中有所损耗，且存在多个代码文件和程序集之间的引用关联关系，这就是为什么在 IIncrementalGenerator 增量 Source Generator 源代码生成设计中是先做语法分析，判断结果通过，再做语义分析的原因

再简单理解可以是如 C# 里面有分部类的概念，进行语法分析的时候，只能一次一个文件一个文件的分析，难以或无法直接分部类的其他分部在哪。但是进行语义分析的时候，可以将所有分部类的信息都收集起来，然后再进行分析，这样就能够找到所有分部类的信息。且在语义分析过程中，能够非常明确知道某个符号的确切含义

语法和语义有比较庞大的知识，我将在后文的专门章节里面详细介绍。这里只是让大家粗略了解一下语法和语义的概念，以便大家能够更好理解后续的内容。本章内容也不会涉及多少的语法和语义知识，不需要对语法和语义有太多的了解，只需要知道这两个概念的存在即可

粗略了解了一点语法和语义的概念，接下来咱就来实现 ForAttributeWithMetadataName 方法的使用。在 NinahajawhuLairfoheahurcee.Analyzer 分析器项目中，修改 IncrementalGenerator 类的 Initialize 方法，添加 ForAttributeWithMetadataName 方法的使用，如下所示

        IncrementalValuesProvider<string> targetClassNameProvider = context.SyntaxProvider.ForAttributeWithMetadataName("Lindexi.FooAttribute",
            // 进一步判断
            (SyntaxNode node, CancellationToken token) => node.IsKind(SyntaxKind.ClassDeclaration),
            (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken token) => syntaxContext.TargetSymbol.Name);

如上面代码所示，第一个参数传入特性名，即 "Lindexi.FooAttribute" 字符串。此时将进入预设逻辑，增量的寻找所有标记了名为 "Lindexi.FooAttribute" 特性的类型或属性或方法等等代码。一旦找到了标记了 "Lindexi.FooAttribute" 特性的代码，将会进入第二个参数的语法判断条件，即 (SyntaxNode node, CancellationToken token) => node.IsKind(SyntaxKind.ClassDeclaration) 代码块。此时将进入进一步判断，只有当找到的代码是类声明的时候，才是符合咱的任务需求的代码，即满足感兴趣的条件。这里的 SyntaxNode.IsKind 方法是判断当前传入的 SyntaxNode 是什么。前面步骤只是找到了标记了 "Lindexi.FooAttribute" 特性的代码，这里进一步判断找到的代码是不是类声明。满足前两个步骤，则证明这是一个在类型上面标记了名为 "Lindexi.FooAttribute" 特性的代码，可以进入最后一个参数里面进行进一步的语义处理

进一步的语义处理是 (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken token) => syntaxContext.TargetSymbol.Name 代码块。这里的 GeneratorAttributeSyntaxContext.TargetSymbol 属性是当前找到的代码的符号，即当前找到的代码的语义信息。这里的 TargetSymbol.Name 属性是当前找到的代码的名称，即当前找到的代码的类型名称。这里的代码块返回的是当前找到的代码的类型名称，即当前找到的代码的名称

将其返回的内容是类似 Linq 的查询结果，即 IncrementalValuesProvider<string> 类型。这个类型是一个增量的值提供者，而不是立刻就返回一次所有满足条件的代码。在 Visual Studio 里面的执行逻辑上，大家可以认为是每更改、新增一次代码，就会执行一次这个查询逻辑，整个查询逻辑是源源不断执行的，不是一次性的，也不是瞬时全跑的，而是增量的逐步执行的

执行过程也是一级级执行的，先通过了第一个参数的特性名，快速判断是否满足参数条件，再经过第二个参数进行语法判断。经过前面两个参数判断就可以快速过滤掉大量的代码，如此的方式可以极大减少计算工作量

现在拿到了 IncrementalValuesProvider<string> 返回值，能够从这里源源不断取出一个个类型出来。但按照咱的任务需求，咱是需要一口气收集所有类型的，不能一个个慢慢取。为此咱需要将 IncrementalValuesProvider<string> 给收集起来，成为一个集合数组。这里可以使用 Collect 方法进行收集，如下所示

        IncrementalValueProvider<ImmutableArray<string>> targetClassNameArrayProvider = targetClassNameProvider
            .Collect();

可以看到此时返回值就从 IncrementalValuesProvider<string> 类型转换为 IncrementalValueProvider<ImmutableArray<string>> 类型。核心不同在于 string 和 ImmutableArray<string> 不可变数组的差异而已。在整个 Roslyn 设计里面，大量采用不可变思想，这里的返回值就是不可变思想的一个体现。细心的伙伴可以看到 IncrementalValuesProvider 和 IncrementalValueProvider 这两个单词的差别，没错，核心在于 Values 和 Value 的差别。在增量源代码生成器里面，使用 IncrementalValuesProvider 表示多值提供器，使用 IncrementalValueProvider 表示单值提供器，两者差异只是值提供器里面提供的数据是多项还是单项。使用 Collect 方法可以将一个多值提供器的内容收集起来，收集为一个不可变集合，从而转换为一个单值提供器，这个单值提供器里面只有一项，且这一项是一个不可变数组。这部分细节内容将在下文和大家详细介绍，在本章节里面就不过多描述

最后一步就是将 IncrementalValueProvider<ImmutableArray<string>> 返回值注册到输出源代码中。在 IncrementalGenerator 类的 Initialize 方法里面，使用 context.RegisterSourceOutput 方法注册输出源代码，如下所示

        context.RegisterSourceOutput(targetClassNameArrayProvider, (productionContext, classNameArray) =>
        {
            productionContext.AddSource("GeneratedCode.cs",
                $$"""
                using System;
                namespace NinahajawhuLairfoheahurcee
                {
                    public static class GeneratedCode
                    {
                        public static void Print()
                        {
                            Console.WriteLine("标记了 Foo 特性的类型有： ｛｛string.Join(",", classNameArray)｝｝");
                        }
                    }
                }
                """);
        });

尝试运行控制台项目，可见此时能够输出以下内容到控制台

标记了 Foo 特性的类型有： F1,F2

尝试展开 Visual Studio 的依赖项->分析器，如下图所示

可以看到生成的代码如下

using System;
namespace NinahajawhuLairfoheahurcee
{
    public static class GeneratedCode
    {
        public static void Print()
        {
            Console.WriteLine("标记了 Foo 特性的类型有： F2,F1");
        }
    }
}

如此以来，对比传统的反射的方法，源代码生成的方式可以将耗时完全放在开发编译过程，不会占用用户端的执行时间。且这个过程都是完完全全的直接代码，也方便运行时的 JIT 进行优化，大大提升了运行时间。完完全全的直接代码也带来了静态分析的友好，可以作为代码裁剪和 AOT 的底层支持

喜欢点点的伙伴也许在准备写 RegisterSourceOutput 的时候，就发现了还有一个名为 RegisterImplementationSourceOutput 方法，那 RegisterSourceOutput 和 RegisterImplementationSourceOutput 的差别是什么？这两个方法对最终生成的代码是没有影响的，核心差别是 RegisterImplementationSourceOutput 是用来注册具体实现生成的代码，这部分输入的代码会被 IDE 作为可选分析项。如 RegisterImplementationSourceOutput 命名所述，这是一个用来注册“具体实现”的代码，在代码里面，咱可以强行将代码分为“定义代码”和“实现代码”，比如说方法签名是定义代码，方法体是实现代码。从 IDE 的分析角度来看，只对“定义代码”而跳过“实现代码”，可以更大程度的减少分析压力，提升分析速度。通过 RegisterImplementationSourceOutput 方法注册的代码，会被 IDE 作为可选分析项，不会因为生成了大量代码导致 IDE 过于卡顿。但带来的问题是这部分生成代码可能不被加入 IDE 分析，导致业务方调用时飘红。因此通过 RegisterImplementationSourceOutput 生成的代码，基本要求是不会被业务方直接调用。常用的套路是先通过 RegisterSourceOutput 或甚至是 RegisterPostInitializationOutput 生成分部类或分部方法，然后再慢慢在 RegisterImplementationSourceOutput 里面填充实现代码。如果感觉对 RegisterSourceOutput 和 RegisterImplementationSourceOutput 的差别还是很混乱，没关系，咱将在后文通过实践来让大家更好地理解两者的差别

以上就是通过 ForAttributeWithMetadataName 开始入门编写分析和收集和生成的简单例子，如果对 ForAttributeWithMetadataName 使用方法感兴趣，扩展阅读部分请参阅使用 ForAttributeWithMetadataName 提高 IIncrementalGenerator 增量 Source Generator 源代码生成开发效率和性能

如果大家照着以上的例子编写不出来能构建通过的代码，或者是运行代码不符合预期，欢迎拉取我的示例代码进行阅读

同样的，以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin b8c036de9d9d7c4b1a3d329054086d6566d14dc4

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin b8c036de9d9d7c4b1a3d329054086d6566d14dc4

获取代码之后，进入 Roslyn/NinahajawhuLairfoheahurcee 文件夹，即可获取到源代码

更底层的收集分析和生成

阅读到这里，也许大家会感慨，使用 ForAttributeWithMetadataName 还是有很大的限制。比如我的需求任务是分析任意的继承了 IFoo 接口的代码，而没有任何的标记，那应该如何做呢？只通过 ForAttributeWithMetadataName 是无法实现的。这个时候就需要更底层的收集分析和生成技术

本文会和大家介绍 ForAttributeWithMetadataName 仅仅只是因为 ForAttributeWithMetadataName 方法使用简单，且使用频率高。不代表只能通过 ForAttributeWithMetadataName 方法进行分析和生成。实际上，ForAttributeWithMetadataName 方法只是对更底层的收集分析和生成技术的封装，更底层的收集分析和生成技术是可以实现更多的需求任务的

在 IIncrementalGenerator 增量 Source Generator 源代码生成里面提供了众多数据源入口，比如整个的配置、引用的程序集、源代码等等。最核心也是用最多的就是通过提供的源代码数据源进行收集分析

按照官方的设计，将会分为三个步骤完成增量代码生成：

告诉框架层需要关注哪些文件或内容或配置的变更
- 在有对应的文件等的变更情况下，才会触发后续步骤。如此就是增量代码生成的关键
告诉框架层从变更的文件里面感兴趣什么数据，对数据预先进行处理
- 预先处理过程中，是会不断进行过滤处理的，确保只有感兴趣的数据才会进入后续步骤
- 其中第一步和第二步可以合在一起
使用给出的数据进行处理源代码生成逻辑
- 这一步的逻辑和普通的 Source Generator 是相同的，只是输入的参数不同

按照以上的步骤，咱来开始重新实现上文的使用 ForAttributeWithMetadataName 实现的任务需求。这次咱将不使用 ForAttributeWithMetadataName 方法，而是使用更底层的收集分析和生成技术。在这个实现过程中，大家也能感受到使用 ForAttributeWithMetadataName 方法的便捷性

为了方便大家后续拉取代码方便，防止多个版本之间的代码误导。我这里重新新建了两个项目，分别是名为 BegalllalhereCilaywhonerdem.Analyzer 的分析器项目，和一个名为 BegalllalhereCilaywhonerdem 的被分析项目。本文内容里面只给出关键代码片段，如需要全部的项目文件，可在下文找到所有代码的下载方法。如果自己编写的代码构建不通过或运行输出不符合预期，也推荐大家拉取本文的代码进行阅读

先完全按照上文的方式进行项目组织，甚至是完全的代码拷贝。因为接下来咱简要替换的部分只是将原本的 ForAttributeWithMetadataName 相关代码进行替换而已，其他逻辑依然保持不变

删掉原本的 ForAttributeWithMetadataName 相关代码，即删掉如下代码

        IncrementalValuesProvider<string> targetClassNameProvider = context.SyntaxProvider.ForAttributeWithMetadataName("Lindexi.FooAttribute",
            // 进一步判断
            (SyntaxNode node, CancellationToken token) => node.IsKind(SyntaxKind.ClassDeclaration),
            (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken token) => syntaxContext.TargetSymbol.Name);
        IncrementalValueProvider<ImmutableArray<string>> targetClassNameArrayProvider = targetClassNameProvider
            .Collect();

接下来咱将使用更底层的收集分析和生成技术，即从 context.SyntaxProvider.CreateSyntaxProvider 方法开始

在 context.SyntaxProvider.CreateSyntaxProvider 方法里面包含两个参数，第一个参数是一个进行语法判断的过程，第二个参数是进行语义进一步判断和加工处理的逻辑。也就是说 CreateSyntaxProvider 方法就包含了上文所述的“告诉框架层需要关注哪些文件或内容或配置的变更”和“告诉框架层从变更的文件里面感兴趣什么数据，对数据预先进行处理”两个步骤

在 CreateSyntaxProvider 方法里面，第一步的语法判断是判断当前传入的是否类型定义。如果是类型定义，则读取其标记的特性，判断特性满足 Lindexi.FooAttribute 的特征时，则算语法判断通过，让数据走到下面的语义判断处理上。其代码大概如下

        IncrementalValueProvider<ImmutableArray<string>> targetClassNameArrayProvider = context.SyntaxProvider
            .CreateSyntaxProvider((node, _) =>
            {
                if (node is not ClassDeclarationSyntax classDeclarationSyntax)
                {
                    return false;
                }

                // 为什么这里是 Attribute List 的集合？原因是可以写出这样的语法
                // ```csharp
                // [A1Attribute, A2Attribute]
                // [A3Attribute]
                // private void Foo()
                // {
                // }
                // ```
                foreach (AttributeListSyntax attributeListSyntax in classDeclarationSyntax.AttributeLists)
                {
                    foreach (AttributeSyntax attributeSyntax in attributeListSyntax.Attributes)
                    {
                        NameSyntax name = attributeSyntax.Name;
                        string nameText = name.ToFullString();
                        if (nameText == "Foo")
                        {
                            return true;
                        }

                        if (nameText == "FooAttribute")
                        {
                            return true;
                        }

                        // 可能还有 global::Lindexi.FooAttribute 的情况
                        if (nameText.EndsWith("Lindexi.FooAttribute"))
                        {
                            return true;
                        }

                        if (nameText.EndsWith("Lindexi.Foo"))
                        {
                            return true;
                        }
                    }
                }

                return false;
            }, (syntaxContext, _) =>
            {
                // 先忽略语义处理过程代码
            }).Collect();

如上述的代码所示，首先是经过 if (node is not ClassDeclarationSyntax classDeclarationSyntax) 判断，过滤掉非类型定义部分的代码。此时就可以确保大量的代码都不会进入到后续分支。毕竟对于正常的代码逻辑来说，类型的定义还是少数哈。接着的逻辑编写就有些考大家对于 C# 的基础语法知识了，先获取特性列表。这里获取到的是列表的集合，为什么呢？因为在 C# 代码里面允许以下的写法，如上文代码注释所述

[A1Attribute, A2Attribute]
[A3Attribute]
private void Foo()
{
}

以上代码里面的 [A1Attribute, A2Attribute] 就是一个特性列表，而 [A1Attribute, A2Attribute] 和 A3Attribute 三个特性构成了特性列表的集合，如此才能保证能够获取到所有的特性且不丢失语法上的特征。即可能某些特性是和其他的特性写在一起的特征才不会被丢失。这就是为什么需要有两层的 foreach 循环才能遍历所有的特性的原因

在语法层面上，是不能完全判断一个特性是否真的是某个指定类型的特性的，比如说对以下代码的分析

[Foo]
public class F1
{
}

在语法层面上只能知道 F1 类型标记了 [Foo] 特性，但不知道这个 [Foo] 特性是否真的是 Lindexi.FooAttribute 特性。需要在语义分析过程中，进一步判断是否真的是 Lindexi.FooAttribute 特性。语法层面上只能知道写下去的是什么代码，完全字面量。这也就是为什么上面代码的判断逻辑会额外多了那么多判断的原因。当然了，如果大家图省事，那直接判断是否包含 Foo 字符串也可以的

上面代码使用了对 NameSyntax 调用 ToFullString 方法获取到所标记的名，再通过字符串判断逻辑，判断是否可能是标记了 Lindexi.FooAttribute 特性

                        NameSyntax name = attributeSyntax.Name;
                        string nameText = name.ToFullString();

                        if (nameText == "Foo")
                        {
                            return true;
                        }

                        if (nameText == "FooAttribute")
                        {
                            return true;
                        }

                        // 可能还有 global::Lindexi.FooAttribute 的情况
                        if (nameText.EndsWith("Lindexi.FooAttribute"))
                        {
                            return true;
                        }

                        if (nameText.EndsWith("Lindexi.Foo"))
                        {
                            return true;
                        }

如果大家对以上的 NameSyntax 的 ToFullString 感兴趣，请参阅 Roslyn NameSyntax 的 ToString 和 ToFullString 的区别

虽然上文判断逻辑看起来写的很多，但也不代表能通过语法判断逻辑的，就一定是标记了 Lindexi.FooAttribute 特性。在语义部分进行进一步处理，代码如下

          context.SyntaxProvider
            .CreateSyntaxProvider((node, _) =>
            {
                // 忽略语法处理部分代码
            }, (syntaxContext, _) =>
            {
                ISymbol declaredSymbol = syntaxContext.SemanticModel.GetDeclaredSymbol(syntaxContext.Node);
                if (declaredSymbol is not INamedTypeSymbol namedTypeSymbol)
                {
                    return (string) null;
                }

                ImmutableArray<AttributeData> attributeDataArray = namedTypeSymbol.GetAttributes();

                // 在通过语义判断一次，防止被骗了
                if (!attributeDataArray.Any(t =>
                        t.AttributeClass?.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat) ==
                        "global::Lindexi.FooAttribute"))
                {
                    return (string) null;
                }

                return namedTypeSymbol.Name;
            })

由于在语法分析过程中，只能知道标记了名为 Foo 的特性，不知道是否真的是特性。需要在语义分析过程中，进一步判断是否真的是特性。进一步判断的方法就是通过 GetAttributes 方法获取标记在类型上面的特性，此时和语法不同的是，可以拿到分部类上面标记的特性，不单单只是某个类型文件而已。接着使用 ToDisplayString 方法获取标记的特性的全名，判断全名是否为 global::Lindexi.FooAttribute 从而确保类型符合预期。当然了，这个过程里面，咱是省略了判断 global::Lindexi.FooAttribute 特性是属于哪个程序集的。正常的分析器项目里面也不会真的去判断某个全名的类型属于哪个程序集的。这个方法即是缺陷也是功能，方便很多开发者只要写出来“鸭子”类型即可的行为。这里说的“鸭子”行为就是只要一个类型的命名空间和名字符合约定即可，至于这个类型是放在哪个程序集和用什么方式的可访问描述都不重要。许多的 C# 高版本语法也是这么定义出来的，如 init 或 ValueTuple 等等。因为通过这样的设计，可以更好的让 C# 语言和具体的框架分离，这也是 C# dotnet 的设计基本原则

在通过了语义判断逻辑之后，即可决定返回值是 (string) null 还是 namedTypeSymbol.Name 的值。返回值这一步就对应着 “告诉框架层从变更的文件里面感兴趣什么数据，对数据预先进行处理”步骤

合起来的代码实现如下

        IncrementalValueProvider<ImmutableArray<string>> targetClassNameArrayProvider = context.SyntaxProvider
            .CreateSyntaxProvider((node, _) =>
            {
                if (node is not ClassDeclarationSyntax classDeclarationSyntax)
                {
                    return false;
                }

                // 为什么这里是 Attribute List 的集合？原因是可以写出这样的语法
                // ```csharp
                // [A1Attribute, A2Attribute]
                // [A3Attribute]
                // private void Foo()
                // {
                // }
                // ```
                foreach (AttributeListSyntax attributeListSyntax in classDeclarationSyntax.AttributeLists)
                {
                    foreach (AttributeSyntax attributeSyntax in attributeListSyntax.Attributes)
                    {
                        NameSyntax name = attributeSyntax.Name;
                        string nameText = name.ToFullString();
                        if (nameText == "Foo")
                        {
                            return true;
                        }

                        if (nameText == "FooAttribute")
                        {
                            return true;
                        }

                        // 可能还有 global::Lindexi.FooAttribute 的情况
                        if (nameText.EndsWith("Lindexi.FooAttribute"))
                        {
                            return true;
                        }

                        if (nameText.EndsWith("Lindexi.Foo"))
                        {
                            return true;
                        }
                    }
                }

                return false;
            }, (syntaxContext, _) =>
            {
                ISymbol declaredSymbol = syntaxContext.SemanticModel.GetDeclaredSymbol(syntaxContext.Node);
                if (declaredSymbol is not INamedTypeSymbol namedTypeSymbol)
                {
                    return (string) null;
                }

                ImmutableArray<AttributeData> attributeDataArray = namedTypeSymbol.GetAttributes();

                // 在通过语义判断一次，防止被骗了
                if (!attributeDataArray.Any(t =>
                        t.AttributeClass?.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat) ==
                        "global::Lindexi.FooAttribute"))
                {
                    return (string) null;
                }

                return namedTypeSymbol.Name;
            }).Collect();

依然和 使用 ForAttributeWithMetadataName 快速分析代码 章一样，将 targetClassNameArrayProvider 注册到输出源代码中，如下所示

        context.RegisterSourceOutput(targetClassNameArrayProvider, (productionContext, classNameArray) =>
        {
             ... // 一摸一样的生成代码
        });

这就是直接使用 CreateSyntaxProvider 方法进行语法语义分析代替 ForAttributeWithMetadataName 的方式

以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin cde8c2a0bd1da7a17467655ff1fc1d78ad28fbed

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin cde8c2a0bd1da7a17467655ff1fc1d78ad28fbed

获取代码之后，进入 Roslyn/BegalllalhereCilaywhonerdem 文件夹，即可获取到源代码

改用更底层的收集分析和生成之后，可以看到语法分析的过程的逻辑已经是比较复杂了。这个过程无论是为了提升可调试性也好，还是提升健壮性也好，其中一个重要手段就是为其编写单元测试。当可能存在的条件情况比较多的时候，编写单元测试可以让大家更好的快速模拟各种情况，也能固化行为，防止后续变更逻辑的时候破坏原有的逻辑。接下来我将和大家介绍如何为分析器编写单元测试

编写单元测试

为了方便大家获取到正确的代码，我这里依然还是再次新建两个新的项目，分别是名为 ChunecilarkenaLibeewhemke 的分析器项目，和名为 ChunecilarkenaLibeewhemke.Test 的单元测试项目。其中名为 ChunecilarkenaLibeewhemke 的分析器项目里面的内容和上一章提供的代码相同，在本章里面咱重点将放在单元测试项目上

先设置让 ChunecilarkenaLibeewhemke.Test 单元测试项目引用 ChunecilarkenaLibeewhemke 分析器项目。和前文提及的引用分析器项目不同的是，在单元测试里面就应该添加程序集应用，如此才能够让单元测试项目访问到分析器项目的公开成员，从而进行测试。以下是我设置了单元测试引用分析器项目之后的 ChunecilarkenaLibeewhemke.Test 单元测试项目的 csproj 项目文件代码片段

  <ItemGroup>
    <ProjectReference Include="..\ChunecilarkenaLibeewhemke\ChunecilarkenaLibeewhemke.csproj" ReferenceOutputAssembly="true" OutputItemType="Analyzer" />
  </ItemGroup>

以上代码里面的 OutputItemType="Analyzer" 是可选的，仅仅用在期望额外将单元测试项目也当成被分析项目时才添加。默认 ReferenceOutputAssembly 属性值就是 true 值，这里强行写 ReferenceOutputAssembly="true" 只是为了强调而已，默认不写即可。即默认情况下，只需使用 <ProjectReference Include="..\ChunecilarkenaLibeewhemke\ChunecilarkenaLibeewhemke.csproj" /> 代码引用即可，和其他单元测试项目没有什么差别

单元测试项目需要添加单元测试负载，这里需要额外添加针对分析器的负载。添加之后的 ChunecilarkenaLibeewhemke.Test 单元测试项目的 csproj 项目文件的代码如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />
    <PackageReference Include="MSTest.TestAdapter" Version="3.8.2" />
    <PackageReference Include="MSTest.TestFramework" Version="3.8.2" />

    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.12.0" />
    <PackageReference Include="Microsoft.CodeAnalysis.Common" Version="4.12.0" />

    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing.MSTest" Version="1.1.2" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.CodeFix.Testing.MSTest" Version="1.1.2" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.CodeRefactoring.Testing.MSTest" Version="1.1.2" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing.MSTest" Version="1.1.2" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\ChunecilarkenaLibeewhemke\ChunecilarkenaLibeewhemke.csproj" ReferenceOutputAssembly="true" OutputItemType="Analyzer" />
  </ItemGroup>

</Project>

单元测试项目可以是尽可能的高版本的 .NET 版本，只有分析器项目才在当前为了兼容 VisualStudio 才需要选用旧的 netstandard2.0 版本。单元测试项目是可以独立执行的，也不会被其他模块引用，尽可能高版本可以享用更新的技术

完成单元测试项目的基础准备之后，接下来咱开始新建名为 IncrementalGeneratorTest 的单元测试类。在对分析器，特别是源代码生成器的单元测试中，一般都会通过一个自己编写的 CreateCompilation 方法，这个方法的作用是将传入的源代码字符串封装为 CSharpCompilation 类型。接着使用 CSharpGeneratorDriver 执行指定的源代码生成器

常用的封装 CSharpCompilation 代码的 CreateCompilation 方法代码如下。可以简单将 CSharpCompilation 理解为一个虚拟的项目。一个虚拟的项目重要的部分只有两个，一个就是源代码本身，另一个就是所引用的程序集。在单元测试的源代码本身就是通过 CSharpSyntaxTree.ParseText 方法将源代码转换为 SyntaxTree 对象。引用程序集可能会复杂一些，在咱这个单元测试里面只需要带上 System.Runtime 程序集即可，带上的方法是通过某个 System.Runtime 程序集的类型，如 System.Reflection.Binder 类型，取其类型所在程序集的路径，再通过 MetadataReference.CreateFromFile 作为引用路径

    private static CSharpCompilation CreateCompilation(string source)
        => CSharpCompilation.Create("compilation",
            new[] { CSharpSyntaxTree.ParseText(source, path: "Foo.cs") },
            new[]
            {
                // 如果缺少引用，那将会导致单元测试有些符号无法寻找正确，从而导致解析失败
                MetadataReference.CreateFromFile(typeof(Binder).GetTypeInfo().Assembly.Location)
            },
            new CSharpCompilationOptions(OutputKind.ConsoleApplication));

大部分情况下的分析器单元测试项目的 CSharpCompilation 封装代码相对固定，会变更的只有某些引用逻辑而已

开始编写单元测试方法，如以下代码所示

[TestClass]
public class IncrementalGeneratorTest
{
    [TestMethod]
    public void Test()
    {
        ... // 在这里编写单元测试代码
    }
}

先添加用于测试输入的代码，即假装是项目的代码，我将其放在 testCode 变量里面，代码如下

    [TestMethod]
    public void Test()
    {
        var testCode =
            """
            using System;
            using Lindexi;

            namespace ChunecilarkenaLibeewhemke.Test
            {
                [Foo]
                public class F1
                {
                }
            
                [FooAttribute]
                public class F2
                {
                }
            }
            """;

        ... // 继续添加更多代码
    }

先调用刚才的 CreateCompilation 方法，将 testCode 封装为 CSharpCompilation 对象。再创建出期望测试的源代码生成器类型。在一个分析器里面里面可以包含非常多个源代码生成器，在单元测试里面可以非常方便取出期望进行测试的源代码生成器，进行非常特定的测试。这也是单元测试能够带来的多入口的优势。本文这里将测试自己项目里面的名为 IncrementalGenerator 的源代码生成器

        var generator = new IncrementalGenerator();

调用 CSharpGeneratorDriver.Create 创建出 GeneratorDriver 对象，用于在单元测试里面执行源代码生成器，从而获取其执行结果。这里需要说明的是整个 Roslyn 都在贯穿不可变设计。不例外，这个 GeneratorDriver 类型也是不可变对象，即在执行源代码生成器之后，是返回一个新的 GeneratorDriver 对象，原本的对象的状态是不改变的。这个设计上可能会让一些伙伴踩坑，让伙伴们发现在执行源代码生成器之后，调用 GeneratorDriver 的 GetRunResult 方法拿不到结果，这是因为调用的 GeneratorDriver 对象还是旧的对象，而是不执行源代码生成器之后的新的对象

为什么 Roslyn 要这么设计 GeneratorDriver 类型呢？除了不可变能够带来很大程度上的降低程序复杂度，方便出现问题快速重现问题和获取过程状态之外。另一个重要原因是可以让 IDE 从某个状态重复多次快速进入下一个状态，而不需要每次都创建新的对象。如咱在某个方法里面开始编写代码，从进入方法开始的状态就可以保留，不断编写代码，不断输入字符或单词的过程中，就可以不断后台调用 GeneratorDriver 对象进行执行源代码生成状态，而不需要每输入一次都创建一次新的对象。如此可以更好的提升 IDE 的性能

合起来的代码如下

        var generator = new IncrementalGenerator();
        GeneratorDriver driver = CSharpGeneratorDriver.Create(generator);

调用 CSharpGeneratorDriver 的 RunGenerators 执行源代码生成器，记得获取其方法返回值作为新的对象，代码如下

        var generator = new IncrementalGenerator();
        GeneratorDriver driver = CSharpGeneratorDriver.Create(generator);

        GeneratorDriver driver2 = driver.RunGenerators(compilation);

尝试获取 driver2 的结果，获取到源代码生成器输出的源代码内容，代码如下

        foreach (var generatedTree in driver2.GetRunResult().GeneratedTrees)
        {
            var generatedCode = generatedTree.ToString();
            Debug.WriteLine(generatedCode);
        }

这就是最简单的源代码生成器的单元测试的写法。如果大家对分析器的单元测试感兴趣，可以继续阅读此博客：为 IIncrementalGenerator 增量 Source Generator 源代码生成项目添加单元测试

在完成单元测试的搭建之后，自然咱可以添加更多测试逻辑。比如说上文提及的在语法层面上只能知道一个类型标记了名为 Foo 的特性，而不知此 Foo 具体的是什么样的类型。需要通过进一步的语义过程的判断处理。在这里，咱将通过单元测试构建出这样的情况，进行测试咱的源代码生成器逻辑

编辑放在 testCode 的代码，给其添加一些捣乱的代码，更改之后的代码如下

        var testCode =
            """
            using System;
            using Lindexi;

            namespace ChunecilarkenaLibeewhemke.Test
            {
                [Foo]
                public class F1
                {
                }
            
                [FooAttribute]
                public class F2
                {
                }
            }

            namespace FooChunecilarkenaLibeewhemke
            {
                public class FooAttribute : Attribute
                {
                }
                
                [Foo]
                public class F3
                {
                }
            }
            """;

如上面代码所示，添加了一个放在 FooChunecilarkenaLibeewhemke 命名空间下的用于捣乱的 F3 类型，这个 F3 类型实际上标记的是 FooChunecilarkenaLibeewhemke.FooAttribute 特性，而不是源代码生成器期望的标记了 Lindexi.FooAttribute 特性

尝试调试此单元测试代码，在语义判断处打上断点

此时可见在语义判断层面上进入了 if (!attributeDataArray.Any(t => t.AttributeClass?.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat) == "global::Lindexi.FooAttribute")) 判断分支，这就意味着前面的语法判断过程中是放过了 F3 类型这个情况，只有在语义过程中，获取其全名才拿到了真实的名为 global::FooChunecilarkenaLibeewhemke.FooAttribute 的全名，从而将其过滤掉。符合预期的就是只输出 F1 和 F2 类型，过滤掉 F3 类型。咱可以在单元测试里面，为生成的代码添加固定测试，确保在变更逻辑的时候，如果有生成代码逻辑变动可以进行拦截。如以下代码所示

        GeneratorDriver driver = CSharpGeneratorDriver.Create(generator);
        driver = driver.RunGenerators(compilation);

        foreach (var generatedTree in driver.GetRunResult().GeneratedTrees)
        {
            var generatedCode = generatedTree.ToString();
            Debug.WriteLine(generatedCode);

            if (generatedTree.FilePath.EndsWith("GeneratedCode.cs"))
            {
                var expected =
                    """
                     using System;
                     namespace ChunecilarkenaLibeewhemke
                     {
                         public static class GeneratedCode
                         {
                             public static void Print()
                             {
                                 Console.WriteLine("标记了 Foo 特性的类型有： F1,F2,");
                             }
                         }
                     }
                    """;
                // 防止拉取 git 时出现的 \r\n 不匹配问题。能够解决一些拉取 git 的奇怪的坑，也就是在我电脑上跑的好好的，但为什么在你电脑上就炸了
                expected = expected.Replace("\r\n", "\n");
                Assert.AreEqual(expected, generatedCode.Replace("\r\n", "\n"));
            }
        }

通过此单元测试也可以让大家更好地理解语法和语义上的差别，也能够让大家知道为什么尽管通过了语法判断，还需要语义进行兜底的原因。在 C# 语法上，是可以存在局部代码完全相同，每个字符都相同，但实际上其语义是不相同的情况，需要联系其上下文才能知道。语法过程中更加关注语法本身，语义过程中才能从全局角度了解代码的语义

本章的代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin abe3f751fe987a29d0b241501fade1d20c2dc74a

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin abe3f751fe987a29d0b241501fade1d20c2dc74a

获取代码之后，进入 Roslyn/ChunecilarkenaLibeewhemke 文件夹，即可获取到源代码

如果在单元测试中，需要测试到 AnalyzerConfigOptionsProvider 选项，请参阅 IIncrementalGenerator 如何在源代码生成器单元测试提供 AnalyzerConfigOptionsProvider 选项

直接调试项目

在上一章中，和大家介绍了如何编写单元测试。在此过程中，也许有些伙伴会感觉编写单元测试还是比较繁琐的。或者说在编写单元测试的过程里面会比较耗时，纯字符串方式也没有代码提示，不太适合很多伙伴的工作现状。在大型项目中，或比较正式的项目里面，添加单元测试来提升分析器的稳定性，以及通过更多单元测试测试更多分支。而在许多没有那么多资源可以投入的情况下，则可以追求简单的直接调试项目

简单的直接调试项目的方式指的是直接从分析器项目上，在 VisualStudio 里面一键 F5 就可以启动调试，调试入口和其他任何 dotnet 项目相同，非常方便。不需要去新建一个单元测试项目，可以直接对着目标项目，即被分析项目，进行调试。可以减少在单元测试里面搭建项目引用关系，搭建项目组织等的工作量

直接调试要求 Visual Studio 安装好了 .NET Compiler Platform SDK 负载组件，这个组件是用于支持 Roslyn 的调试环境。给 Visual Studio 打上 .NET Compiler Platform SDK 负载组件方法如下：

运行“Visual Studio 安装程序”
选择“修改”
检查“Visual Studio 扩展开发”工作负荷。
在摘要树中打开“Visual Studio 扩展开发”节点。
选中“.NET Compiler Platform SDK”框。将在可选组件最下面找到它

依然是为了让大家方便获取正确的代码起见，我这里继续新建两个项目，分别是名为 JehairqogefaKaiwuwhailallkihaiki.Analyzer 的分析器项目和名为 JehairqogefaKaiwuwhailallkihaiki 的被分析的控制台项目

这两个项目的代码不重要，大家可以使用上文 “更底层的收集分析和生成” 章节的代码。咱重点方在关注如何搭建调试上。大家可以开始对比一下本章介绍的直接调试项目的方法和上文介绍的搭建单元测试进行调试的方法，两个方法之间的便利性。在自己的项目里面选择合适的方式。或者是在项目刚开始的时候选用直接调试项目的方法，在项目成熟过程中再添加单元测试提升其稳定性

直接调试项目的方法的准备工作要求只有两点：

确保分析器项目正确标记了 IsRoslynComponent 属性。即在分析器项目的 csproj 项目文件的 PropertyGroup 里面存在 <IsRoslynComponent>true</IsRoslynComponent> 代码片段。这个属性是告诉 VisualStudio 这是一个 Roslyn 组件，从而可以在调试的时候启动 Roslyn 的调试环境
确保被调试项目正确添加了分析器项目引用，配置了 OutputItemType="Analyzer" 方式的引用

以下为分析器项目和被分析的控制台项目的 csproj 项目文件内容，大家可以对比一下自己的项目是否符合要求

分析器项目：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
    <IsRoslynComponent>true</IsRoslynComponent>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.11.0" />
  </ItemGroup>

</Project>

被分析的控制台项目：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\JehairqogefaKaiwuwhailallkihaiki.Analyzer\JehairqogefaKaiwuwhailallkihaiki.Analyzer.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false"/>
  </ItemGroup>

</Project>

准备工作完成之后，即可开始进入配置调试启动工作。我将会先告诉大家如何进行手工配置，再告诉大家如何进行图形化配置。以下是手工配置的部分

手工配置

在分析器项目上新建 Properties\launchSettings.json 调试启动配置文件。即在 Properties 文件夹里新建名为 launchSettings.json 的配置文件

在Properties\launchSettings.json 调试启动配置文件里面设置 DebugRoslynComponent 为 commandName 内容。将要被调试的 JehairqogefaKaiwuwhailallkihaiki 控制台项目相对路径设置到 targetProject 属性里面，其文件代码如下

{
  "profiles": 
  {
    "JehairqogefaKaiwuwhailallkihaiki.Analyzer": 
    {
      "commandName": "DebugRoslynComponent",
      "targetProject": "..\\JehairqogefaKaiwuwhailallkihaiki\\JehairqogefaKaiwuwhailallkihaiki.csproj"
    }
  }
}

完成这些步骤之后，手工配置部分就完成了，即可愉快的在分析器项目打上断点，设置分析器项目为启动项目，然后直接在 Visual Studio 使用 F5 一键运行启动调试分析器项目

如果大家发现自己的项目无法进行愉快的调试，可以尝试拉取我的代码用来测试和对比不同

以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin c0e948b2a3aab521f2d6d86593c385f4d406cfa5

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin c0e948b2a3aab521f2d6d86593c385f4d406cfa5

获取代码之后，进入 Roslyn/JehairqogefaKaiwuwhailallkihaiki 文件夹，即可获取到源代码

图形化的配置方式

有伙伴说每次都需要新建 launchSettings.json 文件，要写相对的项目路径，这一点都不工程化，期望能够有更加方便的做法。我接下来将和大家介绍更加 UI 图形化的配置方式

开始配置之前，请确保分析器项目正确配置了 IsRoslynComponent 属性，和被调试项目正确添加了分析器项目引用，配置了 OutputItemType="Analyzer" 属性。细节配置还请参考上文的准备工作部分

本文使用的 Visual Studio 为 Visual Studio 2022 17.12.4 版本。如果你的 Visual Studio 版本和我的差距过远，那可能以下图形界面或选项都有比较多的变更。这也就是为什么我选择先和大家介绍手工配置的原因

配置步骤如下：

先在解决方案资源管理器里面右击分析器项目，点击设为启动项目选项，将分析器项目设置为启动项目

再点击分析器项目的调试属性，如下图所示

在打开的启动配置文件窗口里面，找个命令行参数，随便写入点字符。这个过程仅仅只是为了让 VisualStudio 帮助咱快速创建 launchSettings.json 文件而已。我现在还没有找到比这个方法更加顺手便捷的方式哈

双击 Properties\launchSettings.json 文件进入编辑，现在可见的 launchSettings.json 文件的内容大概如下

{
  "profiles": 
  {
    "JehairqogefaKaiwuwhailallkihaiki.Analyzer": 
    {
      "commandName": "Project",
      "commandLineArgs": "123"
    }
  }
}

此时将 commandName 属性的 Project 内容换成 DebugRoslynComponent 内容，再删除 commandLineArgs 等其他属性。此时先不要写 targetProject 属性项，因为这个属性项要写相对路径，手写太烦了。编辑完成之后的 launchSettings.json 文件的内容大概如下

{
  "profiles": 
  {
    "JehairqogefaKaiwuwhailallkihaiki.Analyzer": 
    {
      "commandName": "DebugRoslynComponent"
    }
  }
}

继续点击分析器项目的调试属性，此时可见启动配置文件窗口界面如下

愉快点击下拉菜单，选择要调试项目即可，如下图所示

选中之后的效果如下图所示

完成之后，再次打开 launchSettings.json 文件，可以看到机智的 Visual Studio 已经帮咱填充了 targetProject 属性内容了。通过 Visual Studio 的填充，可以让咱不需要写繁琐的相对路径，也不用担心写错项目路径导致调试出错

{
  "profiles": 
  {
    "JehairqogefaKaiwuwhailallkihaiki.Analyzer": 
    {
      "commandName": "DebugRoslynComponent",
      "targetProject": "..\\JehairqogefaKaiwuwhailallkihaiki\\JehairqogefaKaiwuwhailallkihaiki.csproj"
    }
  }
}

如此就完成了配置工作

如配置完成运行失败，提示无法启动调试 0x80070057 错误，解决方法请参阅 dotnet 在 VisualStudio 一键 F5 启动调试 Roslyn 分析器项目

使用语法可视化窗格辅助了解语法

有些伙伴会感觉即使在有上文的调试方法辅助的情况下，编写语法分析还是太复杂了，不知道怎么写。自己对语法分析本身也不熟悉，不知道可以如何编写语法分析的代码。这个时候可以使用视觉辅助了解语法

在 Visual Studio 里面自带了语法可视化（Syntax Visualizer）功能，可以帮助大家更加直观的了解代码的语法树。在 Visual Studio 里面打开一个 C# 文件，然后在菜单栏里面点击 View（视图） -> Other Windows（其他窗口） -> Syntax Visualizer 打开语法可视化窗格，如下图所示

其界面大概如下

如果没有从视图里面找到 Syntax Visualizer 语法可视化窗格，则需要给 Visual Studio 打上 .NET Compiler Platform SDK 负载。正常来说，根据上文的步骤一步步来的伙伴，都在前面准备直接调试的过程里面已经安装好了这个负载。安装方法如下：

运行“Visual Studio 安装程序”
选择“修改”
检查“Visual Studio 扩展开发”工作负荷。
在摘要树中打开“Visual Studio 扩展开发”节点。
选中“.NET Compiler Platform SDK”框。将在可选组件最下面找到它

详细安装方法请参阅使用 Visual Studio 中的 Roslyn 语法可视化工具浏览代码 - C# - Microsoft Learn 官方文档

回顾语法可视化窗格界面，可以看到有多个颜色标注出来不同的语法节点，如下图所示

蓝色：SyntaxNode，表示声明、语句、子句和表达式等语法构造。
绿色：SyntaxToken，表示关键字、标识符、运算符等标点。
红色：SyntaxTrivia，代表语法上不重要的信息，例如标记、预处理指令和注释之间的空格。

通过对照语法可视化窗格，可以更加直观的了解代码的语法树结构，从而更好的编写语法分析代码。在编写语法分析代码的时候，可以通过语法可视化窗格辅助了解语法，更加直观的了解代码的语法树结构，根据语法树结构编写语法分析代码

更多关于使用 Visual Studio 的语法可视化（Syntax Visualizer）窗格方法，请参阅： Roslyn 入门：使用 Visual Studio 的语法可视化（Syntax Visualizer）窗格查看和了解代码的语法树 - walterlv

演练：写一个类型收集器

学习了这么多，可以试试进行一些实践演练。在本次演练里面我将会告诉大家更多基础知识，以及分析器的一些设计思想

演练任务

在上文里面和大家介绍了如何进行类型的收集，在本次演练中，将继续加一点需求：让收集到的类型可以同时生成创建器，创建器里面要求传入上下文参数。这是一个很典型的容器注入的需求，不熟悉容器的伙伴也没关系，我用具体的代码来更具体地说明的任务需求

假定有 F1 和 F2 和 F3 三个类型，其定义代码分别如下

public interface IFoo
{
}

public class F1: IFoo
{
    public F1(IContext context)
    {
        // 忽略其他代码
    }
}

public class F2 : IFoo
{
    public F2(IContext context)
    {
        // 忽略其他代码
    }
}

public class F3 : IFoo
{
    public F3(IContext context)
    {
        // 忽略其他代码
    }
}

public interface IContext
{
    // 忽略其他代码
}

预期能够通过源代码生成器生成收集器的代码，其代码预期内容大概如下

public static partial class FooCollection
{
    [Collection]
    public static partial IEnumerable<Func<IContext, IFoo>> GetFooCreatorList()
    {
        yield return context => new F1(context);
        yield return context => new F2(context);
        yield return context => new F3(context);
    }
}

以上的 FooCollection 的 GetFooCreatorList 方法就是咱源代码生成器的生成任务内容。这是一个知识内容比较综合的演练。我将在这个演练里面和大家演示源代码生成器的日常食用方法

假定现在用户已经定义好了 F1 和 F2 和 F3 三个类型，被其继承的 IFoo 接口和用作参数的 IContext 接口，以及如下代码所示的 FooCollection 的分部 GetFooCreatorList 方法。源代码生成器需要生成 CollectionAttribute 特性类型的代码，以及 FooCollection 的 GetFooCreatorList 分部方法的具体实现代码

public static partial class FooCollection
{
    [Collection]
    public static partial IEnumerable<Func<IContext, IFoo>> GetFooCreatorList();
}

咱需要做的就是源代码生成器部分的逻辑，这个过程中再加点更多需求，那就是尽可能让 Visual Studio 用的开森，以及在遇到不符合预期的代码时给调皮的开发者报告一些警告信息

演练步骤

整体的步骤可以分为以下几个步骤：

生成 CollectionAttribute 特性类型的代码
分析使用了 CollectionAttribute 特性的分部方法，且找到方法的返回值参数
根据返回值参数的类型，遍历收集项目的类型，找到感兴趣的类型，生成创建器代码

依然是为了方便大家获取到正确的源代码，我这里重新创建两个项目，分别是名为 KawhawnahemCanalllearlerwhu 的控制台项目，以及名为 KawhawnahemCanalllearlerwhu.Analyzer 的分析器项目。这两个项目的初始化搭建和上文的章节一样，不再赘述。大家可以直接使用上文的章节的代码进行初始化搭建

完成项目搭建之后，就可以开始进入本次演练的步骤了

演练内容里面只给出关键代码片段，如需要全部的项目文件，可到本章末尾找到所有代码的拉取下载方法

生成特性类型的代码

生成 CollectionAttribute 特性类型的代码部分，可以参考上文的章节，这里不再赘述。直接使用 RegisterPostInitializationOutput 方法注册生成 CollectionAttribute 特性类型的代码

using System;
using System.Buffers;
using System.Collections.Generic;
using System.Collections.Immutable;
using System.Diagnostics;
using System.Linq;
using System.Text;
using System.Threading;

using KawhawnahemCanalllearlerwhu.Analyzer.Properties;

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;

namespace KawhawnahemCanalllearlerwhu.Analyzer;

[Generator(LanguageNames.CSharp)]
public class FooIncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        context.RegisterPostInitializationOutput(initializationContext =>
        {
            initializationContext.AddSource("CollectionAttribute.cs",
                """
                namespace Lindexi;

                internal class CollectionAttribute : Attribute
                {
                }
                """);
        });

        ... // 忽略其他代码
    }
}

以上代码唯一的细节是设置 CollectionAttribute 为 internal 类型，这样就可以保证 CollectionAttribute 只能在当前项目内部使用，不会被外部项目引用到。如此能够规避多个相互引用的项目同时使用了此分析器，导致生成了多个相同命名空间的 CollectionAttribute 类型的问题

分析使用了 CollectionAttribute 特性的分部方法

使用上文章节的 ForAttributeWithMetadataName 方法找到标记了 CollectionAttribute 特性的方法。这里需要说明的是 ForAttributeWithMetadataName 方法不仅可以用来找类型，还可以用来找其他可以标记特性的成员，自然也包括方法

            context.SyntaxProvider.ForAttributeWithMetadataName
            (
                "Lindexi.CollectionAttribute", static (SyntaxNode node, CancellationToken _) =>
                {
                    if (node is MethodDeclarationSyntax methodDeclarationSyntax)
                    {
                        // 判断是否是 partial 分部方法
                        return methodDeclarationSyntax.Modifiers.Any(t => t.IsKind(SyntaxKind.PartialKeyword));
                    }

                    return false;
                },
                (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken _) =>
                {
                    ... // 忽略其他代码
                }
            );

在 C# dotnet 里面的分部方法的设计上，可以让源代码生成器和 IDE 都非常开森。其原因是在 IDE 的视角上，分部方法已经完成了整个方法的对外定义。对于其他外部的引用来说，已经满足了基础的符号关系。毕竟对于外部引用来说，具体方法里面的实现是完全不关心的。只要有方法定义，就可以完全建立符号关系。这就意味着具体分部方法的实现代码，可以慢慢让源代码生成器来生成，在源代码生成器生成的过程中，IDE 也不会有任何的报错飘红。对源代码生成器来说，分部方法是一个非常好的锚点，特别是加上标记了特性的分部方法。这就是为什么现在很多 dotnet 基础支持上，都推荐写分部方法标记特性来实现很多功能的原因，比如以下代码演示的 GeneratedRegex 正则表达式源生成器方法

[GeneratedRegex("abc|def", RegexOptions.IgnoreCase, "en-US")]
private static partial Regex AbcOrDefGeneratedRegex();

private static void EvaluateText(string text)
{
    if (AbcOrDefGeneratedRegex().IsMatch(text))
    {
        // Take action with matching text
    }
}

以上代码为 dotnet 内建机制，可以有效生成高速的 Regex 代码，极大提升整体性能，避免运行时编正则带来的损耗，如对此细节感兴趣，请参阅 .NET 正则表达式源生成器 - .NET - Microsoft Learn

以上举例的 AbcOrDefGeneratedRegex 仅仅只是歪楼告诉大家，分部方法配合特性，让源代码生成器填充具体实现内容是现在 dotnet 的惯用方法而已。举例的 AbcOrDefGeneratedRegex 以及正则内容和本文内容没有直接关联

在 ForAttributeWithMetadataName 的语义转换步骤里面，将获取其分部方法的返回值类型，以及在此同时生成部分代码

获取分部方法的返回值类型，可以通过以下代码获取

                context.SyntaxProvider.ForAttributeWithMetadataName
                (
                    "Lindexi.CollectionAttribute", static (SyntaxNode node, CancellationToken _) =>
                    {
                        ... // 忽略其他代码
                    },
                    (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken _) =>
                    {
                        var methodSymbol = (IMethodSymbol)syntaxContext.TargetSymbol;
                        if (!methodSymbol.IsPartialDefinition)
                        {
                            return null;
                        }

                        ITypeSymbol returnType = methodSymbol.ReturnType;
                        // 这是一个泛型类型，我们需要获取泛型参数
                        // 预期是 IEnumerable<Func<IContext, IFoo>> 这样的类型
                        if (returnType is not INamedTypeSymbol methodSymbolReturnType)
                        {
                            return null;
                        }

                        ... // 忽略其他代码
                    });

在获取到返回值类型之后，需要进一步判断返回值类型是否符合预期，代码如下

 ITypeSymbol returnType = methodSymbol.ReturnType;
 // 这是一个泛型类型，我们需要获取泛型参数
 // 预期是 IEnumerable<Func<IContext, IFoo>> 这样的类型
 if (returnType is not INamedTypeSymbol methodSymbolReturnType)
 {
     return null;
 }

 var fullNameDisplayFormat = new SymbolDisplayFormat
 (
     // 带上命名空间和类型名
     SymbolDisplayGlobalNamespaceStyle.Included,
     // 命名空间之前加上 global 防止冲突
     SymbolDisplayTypeQualificationStyle
         .NameAndContainingTypesAndNamespaces
 );
 var returnTypeName = methodSymbolReturnType.ToDisplayString(fullNameDisplayFormat);

 // 预期的返回值类型
 const string exceptedReturnTypeName = "global::System.Collections.Generic.IEnumerable";

 if (!string.Equals(returnTypeName, exceptedReturnTypeName, StringComparison.InvariantCulture))
 {
     return null;
 }

以上代码使用的是让返回值类型输出为全名的方式进行判断，这样的判断方式可以避免存在重名的情况。在判断返回值类型符合预期之后，继续取出其泛型里面的类型

 if (methodSymbolReturnType.TypeArguments.Length != 1)
 {
     // 预期是 IEnumerable<Func> 这样的类型，在 IEnumerable 里面只有一个泛型参数
     return null;
 }

 // 取出 IEnumerable<Func<IContext, IFoo>> 中的 Func<IContext, IFoo> 部分
 if (methodSymbolReturnType.TypeArguments[0] is not INamedTypeSymbol funcTypeSymbol)
 {
     return null;
 }

同理，拿到了 funcTypeSymbol 变量也要判断一下是否 System.Func 类型，以及判断其参数是否符合预期

// 取出 IEnumerable<Func<IContext, IFoo>> 中的 Func<IContext, IFoo> 部分
if (methodSymbolReturnType.TypeArguments[0] is not INamedTypeSymbol funcTypeSymbol)
{
    return null;
}

const string exceptedFuncTypeName = "global::System.Func";
var funcTypeName = funcTypeSymbol.ToDisplayString(fullNameDisplayFormat);

if (!string.Equals(funcTypeName, exceptedFuncTypeName, StringComparison.InvariantCulture))
{
    // 如果不是 Func 类型的，则不是预期的
    return null;
}

// 继续取出 Func<IContext, IFoo> 中的 IContext 和 IFoo 部分
if (funcTypeSymbol.TypeArguments.Length != 2)
{
    return null;
}

写了这么长的判断，其实只是为了判断是否 IEnumerable<Func<IContext, IFoo>> 类型返回值，以及取出 IContext 作为参数类型和 IFoo 作为返回值类型。虽然代码看起来很长，但相信大家能够很快理解

以下为取出 IContext 作为参数类型和 IFoo 作为返回值类型的代码，后续逻辑将需要用到这两个类型的语义

 // 取出 Func<IContext, IFoo> 中的 IContext 部分
 ITypeSymbol constructorArgumentType = funcTypeSymbol.TypeArguments[0];
 string constructorArgumentTypeName = constructorArgumentType.ToDisplayString(fullNameDisplayFormat);
 // 取出 Func<IContext, IFoo> 中的 IFoo 部分
 ITypeSymbol collectionType = funcTypeSymbol.TypeArguments[1];
 var collectionTypeName = collectionType.ToDisplayString(fullNameDisplayFormat);

以上代码在取出的过程中，顺带也获取类型的全名，这在后续的代码生成过程中会用到。在这个步骤里面就立刻生成了部分的代码。这是因为在这里进行生成，可以省去将当前的 IMethodSymbol 传递到后续的代码生成过程中，提升不到一分钱的性能

在 ForAttributeWithMetadataName 的 transform 过程中，作为返回值的内容，都会参与到缓存的计算中。在增量源代码生成设计里面，通过大量的缓存换取减少计算的时间。但缓存本身会涉及很多相等判断逻辑，传递 IMethodSymbol 等符号对象在判断中会比传递字符串更加昂贵，这就是为什么即刻在此进行消费的原因。但这里需要取得一个平衡点，更多发出转换器的代码，而不要在一个转换器里面写太多逻辑，减少变更代码过程中的无效逻辑处理，防止跑了一大堆逻辑但最终因为代码文件内容变更而无效的情况

在本演练例子里面，只是进行部分代码生成，这个过程还是不到一分钱的

在这里期望生成的代码的示例内容

// 生成的代码的示例内容
namespace KawhawnahemCanalllearlerwhu;

public static partial class FooCollection
{
    public static partial IEnumerable<Func<IContext, IFoo>> GetFooCreatorList()
    {
        yield return context => new F1(context);
        yield return context => new F2(context);
        yield return context => new F3(context);
    }
}

当然了，其中间的 yield return context => new F1(context); 等代码，现在还不能生成，因为还没进行项目的类型收集。这个过程将在下一步进行。在这里只生成这个空壳的方法代码框架

生成这个空壳框架代码需要获取到分部方法所在的类型、类型所在的命名空间，分部方法的名称、访问修饰符、是否静态等信息，准备工作如下代码所示

 INamedTypeSymbol containingType = methodSymbol.ContainingType;
 string classNamespace = containingType.ContainingNamespace.Name;
 string className = containingType.Name;

 // Modifiers
 Accessibility declaredAccessibility = containingType.DeclaredAccessibility;
 var modifier = AccessibilityToString(declaredAccessibility);

      static string AccessibilityToString(Accessibility accessibility)
        => accessibility switch
        {
            Accessibility.Public => "public",
            Accessibility.Protected => "protected",
            // 不写了，省略。大家有空自己补充
            _ => string.Empty,
        };

其拼接的生成的空壳方法框架的代码如下

var generatedCode =
        $$"""
          namespace ｛｛classNamespace｝｝;

          ｛｛modifier｝｝｛｛(containingType.IsStatic ? " static" : "")｝｝ partial class ｛｛className｝｝
          {
              ｛｛AccessibilityToString(methodSymbol.DeclaredAccessibility)｝｝｛｛(methodSymbol.IsStatic ? " static" : "")｝｝ partial ｛｛exceptedReturnTypeName｝｝<｛｛exceptedFuncTypeName｝｝<｛｛constructorArgumentTypeName｝｝, ｛｛collectionTypeName｝｝>>
          ｛｛methodSymbol.Name｝｝()
              {
                  yield return context => new F1(context);
              }
          }
          """
    ;

注：为了让我的博客引擎开森，以上代码部分花括号被我替换为了全角花括号。大家在使用的时候需要将全角花括号替换为半角花括号

以上空壳框架代码的 yield return context => new F1(context); 将在后续用作替换字符串的占位符，当前生成的代码内容，即 generatedCode 变量的字符串内容如下

namespace KawhawnahemCanalllearlerwhu;

public static partial class FooCollection
{
    public static partial global::System.Collections.Generic.IEnumerable<global::System.Func<global::KawhawnahemCanalllearlerwhu.IContext, global::KawhawnahemCanalllearlerwhu.IFoo>>
GetFooCreatorList()
    {
        yield return context => new F1(context);
    }
}

在源代码生成器的套路里面，就是尽量使用全命名空间，即带上 global:: 前缀，这样可以避免引用冲突。在这里的代码生成过程中，也是使用了全命名空间的方式，以保证生成的代码可以在任何地方使用。虽然这个方式会让生成的代码比较繁琐，但毕竟是机器生成的代码，不需要人工去编写，只是会添加一些阅读的心智负担

如果感觉确实阅读不方便，那就在 using 处写明别名，带上全命名空间，如 using Xxx = global::Xx.Fxxx 之类的写法

为了在 ForAttributeWithMetadataName 的 transform 进行返回，这里定义一个名为 CollectionExportMethodInfo 的类型，用于存储过程信息，其代码如下

record CollectionExportMethodInfo
(
    ITypeSymbol ConstructorArgumentType,
    ITypeSymbol CollectionType,
    GeneratedCodeInfo GeneratedCodeInfo,
    Location Location
);

readonly record struct GeneratedCodeInfo(string GeneratedCode, string Name);

在源代码生成器里面使用 record 或 readonly record struct 是非常舒坦的，因为记录类型自带了相等判断比较器，可以省去很多工作量。但在这里需要额外说明的是，默认的相等比较器对符号类型来说是不够准确的，有心的源代码生成器开发者可以对以上的 CollectionExportMethodInfo 类型进行更加准确的相等比较器的重写，使用 SymbolEqualityComparer 比较器代替默认的相等比较器。这里的核心原因是 Roslyn 在设计之初时， C# 代码还没有可空的概念。于是设计上对类型只有一个概念，后续 NRT (Nullable Reference Types) 引入之后，导致了一个类型还有另一个可空概念，进而导致了判断逻辑上存在两个选项，分别是 SymbolEqualityComparer.Default 和 SymbolEqualityComparer.IncludeNullability 这两个选项。为了明确起见，于是 Roslyn 团队决定引入 SymbolEqualityComparer 比较器，从而可以让分析器开发者明确知道自己在做什么

SymbolEqualityComparer.Default 比较器是不包含可空性的比较器，即不区分可空性的比较器。对 string 和 string? 进行相等比较，返回的结果是相等的。这个比较器是默认的比较器，与默认会调用的相等比较器行为相同。这就是为什么上述代码即使不重写相等比较器，在业务上也是正确的原因
SymbolEqualityComparer.IncludeNullability 比较器是包含可空性的比较器，即区分可空性的比较器。对 string 和 string? 进行相等比较，返回的结果是不相等的。这个比较器是为了让开发者明确知道自己在做什么，以及在需要区分可空性的情况下使用的比较器

ISymbol? x = ...
ISymbol? y = ...

var defaultAreEquals = x.Equals(y); // Warn: RS1024 Symbols should be compared for equality

var areEquals = SymbolEqualityComparer.Default.Equals(x, y); // string == string?
// 或：
var areEquals = SymbolEqualityComparer.IncludeNullability.Equals(x, y); // string != string?

注：更多关于 SymbolEqualityComparer 比较器与默认比较器的差别，请参阅此帖子： https://github.com/dotnet/roslyn-analyzers/issues/3427

完成 CollectionExportMethodInfo 的定义之后，将其作为返回值返回

// 获取代码的位置，用于生成警告和错误。即告诉 Visual Studio 应该在哪里飘红
var location = syntaxContext.TargetNode.GetLocation();
// 使用 record 类型自带的相等判断，能够省心很多
return new CollectionExportMethodInfo(constructorArgumentType, collectionType,
    new GeneratedCodeInfo(generatedCode, $"{className}.{methodSymbol.Name}"), location);

返回时，从 TargetNode 里面调用 GetLocation 获取到 Location 位置信息。此 Location 信息可用于后续生成警告和错误信息，即告诉 Visual Studio 应该在哪里飘红。拿到的 Location 就是对应的代码的位置信息，如是哪个文件，哪个行号，从哪列到哪列等信息

由于在 ForAttributeWithMetadataName 语义分析过程中，还包含了一些过滤条件，将不满足条件的，都使用 null 进行返回。于是在 ForAttributeWithMetadataName 方法完成返回时，再叠加 Where 条件，用于过滤掉不符合条件的情况。其代码如下

            var provider = context
            .SyntaxProvider.ForAttributeWithMetadataName
            (
                "Lindexi.CollectionAttribute", static (SyntaxNode node, CancellationToken _) =>
                {
                    ... // 忽略其他代码
                },
                (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken _) =>
                {
                    ... // 忽略其他代码
                }
            )
            // 过滤掉不符合条件的情况
            .Where(t => t != null);

回顾本次演练的任务，在当前步骤里面收集到的是一个个的标记了 CollectionAttribute 特性的分部方法，以及这些方法的返回值类型。敲黑板，这里收集到的是一个个的。这就意味着如果直接拿这一个个去与后续的全项目所有类型进行处理，则其处理次数会是 m * n 的量，这里的 m 是标记了 CollectionAttribute 特性的分部方法的数量，n 是全项目所有类型的数量。且这个触发不止一次，而是每次有代码变更都会触发。在 Roslyn 源代码生成器里面禁止此行为，只允许将 IncrementalValuesProvider 多值提供器与 IncrementalValueProvider 单值提供器进行 Combine 组合。禁止将 IncrementalValuesProvider 多值提供器与 IncrementalValuesProvider 多值提供器进行组合

这里有一个容易混淆的点，多值提供器与单值提供器，其类型分别如下：

IncrementalValuesProvider<T> 多值提供器
IncrementalValueProvider<T> 单值提供器

两者差异只是一个是 Values 而另一个是 Value 而已，即多了 s 的差别而已，两个单词比较好混哦

为了能够和后续的全项目类型收集进行 Combine 合并组合处理，这里在 Where 之后，再调用 Collect 方法，将其收集起来，成为 IncrementalValueProvider<ImmutableArray<CollectionExportMethodInfo>> 单值提供器，代码如下

        IncrementalValueProvider<ImmutableArray<CollectionExportMethodInfo>> collectionMethodInfoProvider = context
            .SyntaxProvider.ForAttributeWithMetadataName(
                "Lindexi.CollectionAttribute", static (SyntaxNode node, CancellationToken _) =>
                {
                    ... // 忽略其他代码
                },
                (GeneratorAttributeSyntaxContext syntaxContext, CancellationToken _) =>
                {
                    ... // 忽略其他代码
                })
            // 过滤掉不符合条件的情况
            .Where(t => t != null)
            .Collect()!;

大家是否好奇，似乎这里的 IncrementalValueProvider<ImmutableArray<T>> 单值提供器也是骗人的，里面明明就是一个不可变数组，也就是里面就是一个集合。为什么这样也能称为单值提供器？因为多值和单值是从源代码生成器的缓存角度来说的。即数据提供器里面提供的是多个值还是单个值。这里的 IncrementalValueProvider<ImmutableArray<T>> 单值提供器，其提供的是一个集合，即一个值，所以称为单值提供器。核心差异在于如代码变更的时候，应该刷新的范围是多大。对于 IncrementalValueProvider<ImmutableArray<T>> 来说，只要有一个标记了 CollectionAttribute 的符合条件的分部方法发生了变更，就会触发整个集合的刷新，即 collectionMethodInfoProvider 将会重新提供值

但对于 IncrementalValuesProvider<T> 多值提供器来说，里面的每一项都是独立的，其中一项的变更，只有触发其对应的一次，而不会影响其他项的触发。这也就是为什么 Collect 的设计上不允许多值提供器与多值提供器进行组合的原因。因为多值提供器与多值提供器组合，将会在某一项值变更的时候，其触发条件是比较震荡的，复杂度比较高，不仅人类程序猿顶不住，机器也顶不住

换句话说就是只要任意一个标记了 CollectionAttribute 的符合条件的分部方法发生了变更，就会触发整个 ImmutableArray 集合的刷新。但任意一个标记了 CollectionAttribute 的符合条件的分部方法发生了变更，走到 Where 处的变更也就只有这一个分部方法而已，只不过后续的 ImmutableArray 集合的刷新是靠 Collect 触发的。因为到 Where 处还是多值提供器，只有到 Collect 处才会变成单值提供器

以上代码就完成了对标记了 CollectionAttribute 特性的分部方法的收集，分析使用了 CollectionAttribute 特性的分部方法，且找到方法的返回值参数，生成 CollectionAttribute 特性类型的代码。接下来将会在下一步根据返回值参数的类型，遍历收集全项目的类型，找到感兴趣的类型，生成创建器代码

遍历收集全项目的类型，生成创建器代码

全项目类型收集过程里面将不能使用 ForAttributeWithMetadataName 方法，而是需要使用上文介绍的高度定制支持的更底层的收集分析的 CreateSyntaxProvider 方法。在语法层面，先判断是类型即可通过，本身就需要遍历全项目的类型的，自然判断语法是类型即可

        IncrementalValuesProvider<INamedTypeSymbol> wholeAssemblyClassTypeProvider = context.SyntaxProvider.CreateSyntaxProvider(
            static (SyntaxNode node, CancellationToken _) => node.IsKind(SyntaxKind.ClassDeclaration),
            (GeneratorSyntaxContext syntaxContext, CancellationToken _) =>
            {
                ... // 忽略其他代码
            });

语义层面上，由于现在还没有和对标记了 CollectionAttribute 特性的分部方法的收集的合并，在语义层面上也就没啥好判断的。最多只判断要求类型不能是抽象的，毕竟按照咱的需求任务来说，要的就是创建出对象，抽象类型就不能被直接创建啦，自然就可以被过滤掉

        // 全项目里面的类型
        IncrementalValuesProvider<INamedTypeSymbol> wholeAssemblyClassTypeProvider
            = context.SyntaxProvider
                .CreateSyntaxProvider(
                    static (SyntaxNode node, CancellationToken _) => node.IsKind(SyntaxKind.ClassDeclaration),
                    static (GeneratorSyntaxContext generatorSyntaxContext, CancellationToken token) =>
                    {
                        var classDeclarationSyntax = (ClassDeclarationSyntax) generatorSyntaxContext.Node;
                        INamedTypeSymbol? assemblyClassTypeSymbol =
                            generatorSyntaxContext.SemanticModel.GetDeclaredSymbol(classDeclarationSyntax, token);

                        if (assemblyClassTypeSymbol is not null && !assemblyClassTypeSymbol.IsAbstract)
                        {
                            return assemblyClassTypeSymbol;
                        }

                        return null;
                    })
                .Where(t => t != null)!;

完成了全项目类型的收集之后，就可以和收集了标记了 CollectionAttribute 特性的分部方法的 collectionMethodInfoProvider 进行合并，其代码如下

 wholeAssemblyClassTypeProvider
    .Combine(collectionMethodInfoProvider)

调用 Combine 之后返回的类型是一个元组，为 IncrementalValuesProvider<(INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right)> 类型。即左边 Left 是多值提供器里面的每一个值，即项目里面的每个类型，右边是单值提供器里面的值

继续处理，带上 Select 方法，判断各自类型是否满足标记了 CollectionAttribute 特性的分部方法的感兴趣条件

               wholeAssemblyClassTypeProvider
                .Combine(collectionMethodInfoProvider)
                .Select(static ((INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right) tuple,
                    CancellationToken token) =>
                {
                    INamedTypeSymbol assemblyClassTypeSymbol = tuple.Left;
                    var exportMethodReturnTypeCollectionResultArray = tuple.Right;

                    ... // 忽略其他代码
                })

在这一步里面，咱可以激进一些，直接就干到生成了对应的项的代码里面，即生成如 ` yield return context => new Foo(context);` 的代码。为了表示此返回类型，这里再次定义一个名为 ItemGeneratedCodeResult 的新的类型

readonly record struct ItemGeneratedCodeResult
(
    string ItemGeneratedCode,
    GeneratedCodeInfo ExportMethodGeneratedCodeInfo
)
{
    public Diagnostic? Diagnostic { get; init; }
}

这个新的 ItemGeneratedCodeResult 类型采用的是 readonly record struct 的设计，这会让分析器更加开森。我感觉 readonly record struct 是非常舒坦的设计，不会担心这样的类型在大量使用中，会造成大量的堆对象分配，也不会担心其分配成本和 GC 压力。使用值类型的设计是在分析器官方里面所推荐的，如以下的官方文档所示

Use value types where possible: Value types are more amenable to caching and usually have well defined and easy to understand comparison semantics.

以上的 ItemGeneratedCodeResult 类型包含了 Diagnostic 类型的 Diagnostic 属性，这是用于在进行源代码生成过程中，发现某些代码不符合预期，进行的分析警告或错误信息。从这里也可以看出来源代码生成器本身也带有分析器的功能，这部分的具体使用将在下文介绍

由于 Right 是 ImmutableArray<CollectionExportMethodInfo> 类型，表示的所有的标记了 CollectionAttribute 的分部方法收集信息。因此这里咱也需要对应的创建一个列表，用于建立多对多的关系，即一个类型可能存在对应多个分部方法的关系

                .Select(static ((INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right) tuple,
                    CancellationToken token) =>
                {
                    INamedTypeSymbol assemblyClassTypeSymbol = tuple.Left;
                    var exportMethodReturnTypeCollectionResultArray = tuple.Right;

                    // 慢点创建列表，因为这里是每个类型都会进入一次的，进入次数很多。但大部分类型都不满足条件。因此不提前创建列表能减少很多对象的创建
                    List<ItemGeneratedCodeResult>? result = null;

                    ... // 忽略其他代码
                 })

这里的 List<ItemGeneratedCodeResult>? result 我选择不要一开始就创建，因为现在收集到的类型不一定会满足任何一个分部方法的要求，即这将是一个被忽略的类型。慢点创建可以减少浪费

遍历分部方法收集 ImmutableArray<CollectionExportMethodInfo> 数组，判断类型是否落在某个分部方法感兴趣条件里面，代码如下

                .Select(static ((INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right) tuple,
                    CancellationToken token) =>
                {
                    INamedTypeSymbol assemblyClassTypeSymbol = tuple.Left;
                    var exportMethodReturnTypeCollectionResultArray = tuple.Right;

                    // 慢点创建列表，因为这里是每个类型都会进入一次的，进入次数很多。但大部分类型都不满足条件。因此不提前创建列表能减少很多对象的创建
                    List<ItemGeneratedCodeResult>? result = null;

                    foreach (CollectionExportMethodInfo exportMethodInfo in exportMethodReturnTypeCollectionResultArray)
                    {
                        // 一般进入循环的时候，都会加上这个判断。这个判断逻辑的作用是如开发者在 IDE 里面进行编辑文件的时候，那此文件对应的类型就需要重新处理，即类型对应的 token 将会被激活。此时在循环跑的逻辑就是浪费的，逻辑需要重跑，因此需要判断 token 是否被取消，减少循环里面的不必要的逻辑损耗
                        // check for cancellation so we don't hang the host
                        token.ThrowIfCancellationRequested();

                         ... // 忽略其他代码

                     }
                 })

按照 Roslyn 的设计，在进入大循环等逻辑时，应该多判断一下令牌。这个原因是开发者可能不断在 IDE 里面进行编辑文件，源代码生成器执行过程中对应的文件已经被更改了，本次处理是无效的，此时对此文件涉及的相关类型的处理就应该无效掉，等待重新进入。预先多加令牌判断，可以减少无用处理，减少损耗，避免原本就很卡的 Visual Studio 更加卡顿

在 foreach 里面判断当前的 assemblyClassTypeSymbol 类型是否继承自分部方法要求的返回类型，如以下代码所示

                    foreach (CollectionExportMethodInfo exportMethodInfo in exportMethodReturnTypeCollectionResultArray)
                    {
                        token.ThrowIfCancellationRequested();

                        // 判断当前的类型是否是我们需要的类型
                        if (!IsInherit(assemblyClassTypeSymbol, exportMethodInfo.CollectionType))
                        {
                            continue;
                        }

                         ... // 忽略其他代码
                     }

以上的 IsInherit 方法的实现如下

    /// <summary>
    /// 判断类型继承关系
    /// </summary>
    /// <param name="currentType">当前的类型</param>
    /// <param name="requiredType">需要继承的类型</param>
    /// <returns></returns>
    public static bool IsInherit(ITypeSymbol currentType, ITypeSymbol requiredType)
    {
        var baseType = currentType.BaseType;
        while (baseType is not null)
        {
            if (SymbolEqualityComparer.Default.Equals(baseType, requiredType))
            {
                // 如果基类型是的话
                return true;
            }

            // 否则继续找基类型
            baseType = baseType.BaseType;
        }

        foreach (var currentInheritInterfaceType in currentType.AllInterfaces)
        {
            if (SymbolEqualityComparer.Default.Equals(currentInheritInterfaceType, requiredType))
            {
                // 如果继承的类型是的话
                return true;
            }
        }

        return false;
    }

继承条件判断里面是无视引用对象可空情况的，直接使用 SymbolEqualityComparer.Default 判断即可，不用或不该用 SymbolEqualityComparer.IncludeNullability 进行判断。以上的 IsInherit 是一个我常写的工具方法，可以用来判断给定类型是否被继承，包括基类型和接口类型

在真实项目里面，通过 IsInherit 即可过滤大量类型，毕竟能够满足条件的，预期还是少数。再下一步就是寻找构造函数了。在 C# 语法里面，只能做到 new T() 泛型，做不到构造函数里面带参数的情况。源代码生成器里面可以轻易做到这一点，通过这个演练也能让大家看到源代码生成器的威力。在很多通用创建器、工厂模式等，可以打破泛型 T 只能创建无参构造函数的限制，过程中也不用任何反射，都是最直接的代码，对裁剪和 AOT 友好

如果类型满足继承条件，则继续寻找构造函数。感兴趣的构造函数的特征是有且只有一个参数，参数类型等于分部方法传入的 context 类型。我这里就完全限定参数类型相等，而不是说其 context 的基类型也可以，这仅仅只是为了简单演示而已

// 判断当前的类型是否是我们需要的类型
if (!IsInherit(assemblyClassTypeSymbol, exportMethodInfo.CollectionType))
{
    continue;
}

// 遍历其构造函数，找到感兴趣的构造函数
IMethodSymbol? candidateConstructorMethodSymbol = null;
foreach (IMethodSymbol constructorMethodSymbol in ssemblyClassTypeSymbol.Constructors)
{
    if (constructorMethodSymbol.Parameters.Length != 1)
    {
        // 根据需求任务可知，感兴趣的构造函数的特征是有且只有一个参数
        // 如果参数数量不等于 1 则不满足条件
        continue;
    }

    // 判断参数的类型是否符合预期
    IParameterSymbol parameterSymbol = constructorMethodSymbol.Parameters[0]; // 前面判断限定有且只有一个参数，这里可以放心使用下标访问获取首个参数
    var parameterType = parameterSymbol.Type;

    // 以下忽略是否可空的判断，因此业务上传入时都是有值的，因此无视可空情况。直接使用 SymbolEqualityComparer.Default 判断即可
    if (SymbolEqualityComparer.Default.Equals(parameterType,
            exportMethodInfo.ConstructorArgumentType))
    {
        // 如果参数类型满足条件，则这就是感兴趣的构造函数
        candidateConstructorMethodSymbol = constructorMethodSymbol;
        // 为什么直接 Break 了，不继续找找？继续找找也找不到的，因为不可能存在两个构造函数有相同的参数签名，即不存在两个构造函数的参数数量只有一个且参数类型相同的情况。不信的话，自己写写看就明白了，写任意类型包含两个构造函数，这两个构造函数的参数数量只有一个且参数类型相同
        // 当然，如果前面判断条件开放为判断满足 `exportMethodInfo.ConstructorArgumentType` 的基类型条件，那自然这里也许就可能会有多个构造函数的情况，也就需要排优先级了哈。不排也可以，毕竟生成出来的代码都是一样的，但不排的话，语义层面则是不正确的。为了简单演示，这里就直接限制要求类型相同而不是判断继承关系
        break;
    }
}

能够进入到这一步的，才开始创建列表用于作为返回值

    result ??= new List<ItemGeneratedCodeResult>();

判断是否存在满足条件的构造函数，如满足条件，则开始生成代码

result ??= new List<ItemGeneratedCodeResult>();

if (candidateConstructorMethodSymbol is not null)
{
    var fullNameDisplayFormat = new SymbolDisplayFormat
    (
        // 带上命名空间和类型名
        SymbolDisplayGlobalNamespaceStyle.Included,
        // 命名空间之前加上 global 防止冲突
        SymbolDisplayTypeQualificationStyle
            .NameAndContainingTypesAndNamespaces
    );
    var className = assemblyClassTypeSymbol.ToDisplayString(fullNameDisplayFormat);

    // context => new F1(context)
    var generatedCode = $"context => new {className}(context)";

    result.Add(new ItemGeneratedCodeResult(generatedCode, exportMethodInfo.GeneratedCodeInfo));
}

那如果没有存在满足条件的构造函数呢？此时就可以报告一条分析报告信息了

 if (candidateConstructorMethodSymbol is not null)
 {
     ... // 忽略其他代码
 }
 else
 {
     // 找不到满足条件的构造函数，给出分析警告
     Diagnostic diagnostic = ... 
 
     result.Add(default(ItemGeneratedCodeResult) with
     {
         Diagnostic = diagnostic,
     });
 }

分析警告警告内容也有点知识量，也比较独立，我准备在下文独立和大家介绍，这里就一笔略过。大家在这里只需知道在源代码生成器过程中，如果分析到某些代码难以开展后续的生成工作，可以在此创建分析警告或错误，用于提示开发者

最后，将 result 列表返回即可

return result?.ToImmutableArray() ?? ImmutableArray<ItemGeneratedCodeResult>.Empty;

以上代码将 ` List` 转换为不可变的数组进行返回，如此可以更好的符合分析器的设计。整个寻找整个项目的感兴趣的类型和生成部分代码的过程的代码如下

        IncrementalValuesProvider<ImmutableArray<ItemGeneratedCodeResult>> itemGeneratedCodeResultProvider =
            wholeAssemblyClassTypeProvider
                .Combine(collectionMethodInfoProvider)
                .Select(static ((INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right) tuple,
                    CancellationToken token) =>
                {
                    INamedTypeSymbol assemblyClassTypeSymbol = tuple.Left;
                    var exportMethodReturnTypeCollectionResultArray = tuple.Right;

                    // 慢点创建列表，因为这里是每个类型都会进入一次的，进入次数很多。但大部分类型都不满足条件。因此不提前创建列表能减少很多对象的创建
                    List<ItemGeneratedCodeResult>? result = null;

                    foreach (CollectionExportMethodInfo exportMethodInfo in exportMethodReturnTypeCollectionResultArray)
                    {
                        // 一般进入循环的时候，都会加上这个判断。这个判断逻辑的作用是如开发者在 IDE 里面进行编辑文件的时候，那此文件对应的类型就需要重新处理，即类型对应的 token 将会被激活。此时在循环跑的逻辑就是浪费的，逻辑需要重跑，因此需要判断 token 是否被取消，减少循环里面的不必要的逻辑损耗
                        // check for cancellation so we don't hang the host
                        token.ThrowIfCancellationRequested();

                        // 判断当前的类型是否是我们需要的类型
                        if (!IsInherit(assemblyClassTypeSymbol, exportMethodInfo.CollectionType))
                        {
                            continue;
                        }

                        // 遍历其构造函数，找到感兴趣的构造函数
                        IMethodSymbol? candidateConstructorMethodSymbol = null;
                        foreach (IMethodSymbol constructorMethodSymbol in assemblyClassTypeSymbol.Constructors)
                        {
                            if (constructorMethodSymbol.Parameters.Length != 1)
                            {
                                continue;
                            }

                            // 判断参数的类型是否符合预期
                            IParameterSymbol parameterSymbol = constructorMethodSymbol.Parameters[0];
                            var parameterType = parameterSymbol.Type;

                            if (SymbolEqualityComparer.Default.Equals(parameterType,
                                    exportMethodInfo.ConstructorArgumentType))
                            {
                                candidateConstructorMethodSymbol = constructorMethodSymbol;
                                break;
                            }
                        }

                        result ??= new List<ItemGeneratedCodeResult>();
                        var fullNameDisplayFormat = new SymbolDisplayFormat
                        (
                            // 带上命名空间和类型名
                            SymbolDisplayGlobalNamespaceStyle.Included,
                            // 命名空间之前加上 global 防止冲突
                            SymbolDisplayTypeQualificationStyle
                                .NameAndContainingTypesAndNamespaces
                        );
                        var className = assemblyClassTypeSymbol.ToDisplayString(fullNameDisplayFormat);

                        if (candidateConstructorMethodSymbol is not null)
                        {
                            // context => new F1(context)
                            var generatedCode = $"context => new {className}(context)";

                            result.Add(new ItemGeneratedCodeResult(generatedCode, exportMethodInfo.GeneratedCodeInfo));
                        }
                        else
                        {
                            // 找不到满足条件的构造函数，给出分析警告
                            Diagnostic diagnostic = ... 
 
                            result.Add(default(ItemGeneratedCodeResult) with
                            {
                                Diagnostic = diagnostic,
                            });
                        }
                    }

                    return result?.ToImmutableArray() ?? ImmutableArray<ItemGeneratedCodeResult>.Empty;
                });

为了能够在后续步骤更好地聚焦处理，这里也同样在 itemGeneratedCodeResultProvider 叠加一个 Where 进行过滤，去掉空集，代码如下

        IncrementalValuesProvider<ImmutableArray<ItemGeneratedCodeResult>> itemGeneratedCodeResultProvider =
            wholeAssemblyClassTypeProvider
                .Combine(collectionMethodInfoProvider)
                .Select(static ((INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right) tuple,
                    CancellationToken token) =>
                {
                    ... // 忽略其他代码
                })
                .Where(t => t != ImmutableArray<ItemGeneratedCodeResult>.Empty);

如此即可确保后续步骤拿到的 itemGeneratedCodeResultProvider 提供的值都不会是空集

在这里，大家看到了很多熟悉的类似 Linq 里面的 Where 和 Select 方法。这些方法只是命名上和 Linq 相同，实际上不是原来的 Linq 的方法。但从方法的用途上和设计上，可以看到在 IIncrementalGenerator 这部分设计里面是非常靠近 Linq 的设计的。在更底层的设计上，所期望的就是让数据可以和 Linq 的数据流设计一样，能够一级级传递，且过程中是 Lazy 的和带缓存的。核心目的就是减少计算压力，充分利用 Roslyn 的不可变性带来的缓存机制，减少分析过程的计算压力，不让原本就很卡的 Visual Studio 更加卡。我将在下文基础知识部分和大家详细解析 Where 和 Select 和 Combine 等这几个基础 IIncrementalGenerator 增量源代码生成器的专有方法

通过以上的步骤，就完成了收集各个感兴趣类型的构造函数的过程，且生成了对应的创建器委托代码。接下来就可以进行组装最终的代码了

以上是逐个类型跑出来的，需要将其组装起来，生成最终的代码。这里采用的方法是先用 Collect 将其聚合为一个大数组，再使用 SelectMany 将其散开。为什么需要做合分的处理？原因是 itemGeneratedCodeResultProvider 提供的数组是一个类型对应在多个分部方法里面的生成代码，而最终需要生成的是单个分部方法包含多个类型的代码，且期望各个分部方法独立生成。于是就需要先调用 Collect 将其聚合为一个大数组，如此才能让各个分部方法拿到所有感兴趣的类型的生成代码，再调用 SelectMany 方法让每个分部方法独立输出，代码如下

itemGeneratedCodeResultProvider
 .Collect()
 .SelectMany((ImmutableArray<ImmutableArray<ItemGeneratedCodeResult>> array, CancellationToken oken) =>
 {
     ... // 忽略其他代码
 });

原本 itemGeneratedCodeResultProvider 就是一个多值提供器，提供的每个值都是 ImmutableArray<ItemGeneratedCodeResult> 类型。调用 Collect 之后，就转换成了 ImmutableArray<ImmutableArray<ItemGeneratedCodeResult>> 类型，套了两层数组。在 SelectMany 里面，需要先将其拆散，按照 ItemGeneratedCodeResult 里面的 ExportMethodGeneratedCodeInfo 进行分组。这时候采用 Linq 来写就非常简单，代码如下

itemGeneratedCodeResultProvider
 .Collect()
 .SelectMany((ImmutableArray<ImmutableArray<ItemGeneratedCodeResult>> array, CancellationTokentoken) =>
 {
     IEnumerable<IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult>> group = array
         .SelectMany(t => t)
         // 如果 Diagnostic 不是空，则证明这条是用来报告的，忽略
         .Where(t => t.Diagnostic is null)
         .GroupBy(t => t.ExportMethodGeneratedCodeInfo);

     ... // 忽略其他代码
 });

这里拿到的 IEnumerable<IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult>> group 看似很长，其实含义非常明了，表示的是多个组。每个组的领导就是 GeneratedCodeInfo 类型，实际含义是分部方法。简单来说可以看成 IEnumerable<分部方法组> 类型，细分 分部方法组 就包含了分部方法的信息本身，以及各个满足条件的类型和其生成代码。每个 分部方法组 就可以组成一个最终生成代码

将 IEnumerable<IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult>> group 进行遍历，每一项都可生成一个独立的分部方法的实现代码

  IEnumerable<IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult>> group = array
      .SelectMany(t => t)
      // 这条是用来报告的，忽略
      .Where(t => t.Diagnostic is null)
      .GroupBy(t => t.ExportMethodGeneratedCodeInfo);

  var generatedCodeList = new List<GeneratedCodeInfo>();
  foreach (IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult> temp in group)
  {
      // 在这里就是可以组装出各个标记了 CollectionAttribute 特性的分部方法的实现代码
      ... // 忽略其他代码
  }

以下就是组装标记了 CollectionAttribute 特性的分部方法的实现代码，先将各个满足条件的类型的生成代码放入到 StringBuilder 里面，转换为方法体核心内容，代码如下

var generatedCodeList = new List<GeneratedCodeInfo>();
foreach (IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult> temp in group)
{
    // 进行组装生成代码。在 Select 系列方法组装会比在 RegisterSourceOutput 更好，在这里更加便被打断
    var stringBuilder = new StringBuilder();
    foreach (ItemGeneratedCodeResult itemGeneratedCodeResult in temp)
    {
        token.ThrowIfCancellationRequested();
        //         yield return context => new F1(context);
        stringBuilder.AppendLine($"         yield return itemGeneratedCodeResult.ItemGeneratedCode};");
    }

    // 严谨一些，添加 break 语句。顺带解决收集不到任何一个类型的情况
    stringBuilder.AppendLine("         yield break;");
}

在以上生成代码里面，还在最后添加了 ` yield break;` 代码，如此可以顺带解决收集不到任何一个类型的情况，即使收集不到一个类型，也能返回空集，而不会让构建炸掉

再根据上文提供的 yield return context => new F1(context); 用于被替换的预置内容，将其进行替换，即可完成分部方法实现方法体的内容

// 这是用来替换的代码
var replacedCode = "        yield return context => new F1(context);";

GeneratedCodeInfo generatedCodeInfo = temp.Key;
var generatedCode = generatedCodeInfo.GeneratedCode.Replace(replacedCode, stringBuilder.ToString());

当前的 generatedCode 变量的内容大概如下，即以下代码内容就是最终的分部方法生成的方法体内容示例

namespace KawhawnahemCanalllearlerwhu;

public static partial class FooCollection
{
    public static partial global::System.Collections.Generic.IEnumerable<global::System.Func<global::KawhawnahemCanalllearlerwhu.IContext, global::KawhawnahemCanalllearlerwhu.IFoo>>
GetFooCreatorList()
    {
         yield return context => new global::KawhawnahemCanalllearlerwhu.F1(context);
         yield return context => new global::KawhawnahemCanalllearlerwhu.F2(context);
         yield break;
    }
}

生成最终代码之后，将其加入到 generatedCodeList 列表里面，如以下代码所示

generatedCodeList.Add(new GeneratedCodeInfo(generatedCode, generatedCodeInfo.Name));

最后，将 generatedCodeList 列表返回即可

        IncrementalValuesProvider<GeneratedCodeInfo> generatedCodeInfoProvider = itemGeneratedCodeResultProvider
            .Collect()
            .SelectMany((ImmutableArray<ImmutableArray<ItemGeneratedCodeResult>> array, CancellationToken token) =>
            {
                IEnumerable<IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult>> group = array
                    .SelectMany(t => t)
                    // 这条是用来报告的，忽略
                    .Where(t => t.Diagnostic is null)
                    .GroupBy(t => t.ExportMethodGeneratedCodeInfo);

                var generatedCodeList = new List<GeneratedCodeInfo>();
                foreach (IGrouping<GeneratedCodeInfo, ItemGeneratedCodeResult> temp in group)
                {
                    var generatedCode = ... // 最终生成的分部方法的方法体
                    generatedCodeList.Add(new GeneratedCodeInfo(generatedCode, generatedCodeInfo.Name));
                }

                return generatedCodeList;
            });

是否大家好奇为什么 generatedCodeInfoProvider 是 IncrementalValuesProvider<GeneratedCodeInfo> 类型？明明最后返回的是 List<GeneratedCodeInfo> generatedCodeList 列表？这是因为当前调用的就是 SelectMany 方法，其功能和 Linq 的 SelectMany 方法一样，都是将返回的列表进行拆散

最后一步就是将生成的代码进行注入，这里调用的是 RegisterImplementationSourceOutput 方法。回顾一下几个注入生成代码的方法的差别，其中 RegisterImplementationSourceOutput 的作用是注册具体的实现部分的生成代码。这个方法的调用可以让 IDE 进行充分的优化，因为具体的实现的内容不影响外部的语法语义分析，外部的语法语义分析靠定义部分即可完成，因此对于实现的内容部分可以尽量慢点调用和减少调用频次。刚好在本演练里面，生成的代码就是具体的实现部分，调用 RegisterImplementationSourceOutput 方法是非常合适的

        context.RegisterImplementationSourceOutput(generatedCodeInfoProvider,
            (SourceProductionContext productionContext, GeneratedCodeInfo generatedCodeInfo) =>
            {
                productionContext.AddSource($"{generatedCodeInfo.Name}.cs", generatedCodeInfo.GeneratedCode);
            });

按照源代码生成器的最佳实践来说，在 RegisterImplementationSourceOutput 等注册代码步骤里面，应该接近没有逻辑。即在值提供器步骤时，就将代码生成完成，到 RegisterXxx 方法里面只做注册而已。这样就比较方便在前面步骤进行打断，以及缓存复用

报告 Diagnostic 信息

认真阅读文章的伙伴也许还记得上文部分提到了 Diagnostic 信息。在源代码生成器的过程中，如果发现某些代码不符合预期，可以通过报告 Diagnostic 信息，用于提示开发者。在上文的代码里面，如果找不到满足条件的构造函数，就会报告一条分析警告。这里就来详细介绍如何报告 Diagnostic 信息

回到 itemGeneratedCodeResultProvider 变量的赋值部分代码，即使对全项目的类型 wholeAssemblyClassTypeProvider 进行“遍历”的时候，如果一个类型满足分部方法收集条件，但不存在任何一个满足条件的构造函数时，应该给出分析警告。如本演练给出的 F3 测试类型的定义如下

public class F3 : IFoo
{
    public F3()
    {
        // 忽略其他代码
    }
}

对应的分部方法的定义如下

public static partial class FooCollection
{
    [Collection]
    public static partial IEnumerable<Func<IContext, IFoo>> GetFooCreatorList();
}

可以明显看出给出的 F3 测试类型是歪楼的，没有构造函数满足 GetFooCreatorList 收集条件。于是在 wholeAssemblyClassTypeProvider 进行遍历的过程中，应该对这些歪楼的类型给出警告

IncrementalValuesProvider<INamedTypeSymbol> wholeAssemblyClassTypeProvider = ...

wholeAssemblyClassTypeProvider
    .Combine(collectionMethodInfoProvider)
    .Select(static ((INamedTypeSymbol Left, ImmutableArray<CollectionExportMethodInfo> Right) tuple,
        CancellationToken token) =>
    {
        INamedTypeSymbol assemblyClassTypeSymbol = tuple.Left;
        var exportMethodReturnTypeCollectionResultArray = tuple.Right;

        List<ItemGeneratedCodeResult>? result = null;

        foreach (CollectionExportMethodInfo exportMethodInfo inexportMethodReturnTypeCollectionResultArray)
        {
            ... // 忽略其他代码

            // 遍历其构造函数，找到感兴趣的构造函数
            IMethodSymbol? candidateConstructorMethodSymbol = null;

            ... // 尝试获取满足条件的构造函数

            if (candidateConstructorMethodSymbol is not null)
            {
                
            }
            else
            {
                Diagnostic diagnostic = ...

                result.Add(default(ItemGeneratedCodeResult) with
                {
                    Diagnostic = diagnostic,
                });
            }
        }

        return result?.ToImmutableArray() ?? ImmutableArray<ItemGeneratedCodeResult>.Empty;
    })

现在咱来开始填补 Diagnostic diagnostic = ... 这句代码的具体内容。首先需要创建一个 DiagnosticDescriptor 对象，用于描述这个 Diagnostic 信息的基本信息，如 ID、Title、MessageFormat、Category 等。这是因为大部分的 Diagnostic 基本信息都是固定的，唯一不同的就是具体的 Message 提示消息内容的一些参数不同，以及代码 Location 的不同而已。再加上为了让分析器能够提供给全球的开发者使用，自然要照顾多语言问题，这部分就可以独立出来定义，不用每次报告都重复生成。当然了，为了演示方便，我这里就在每次循环里面，每找到一次不满足条件的构造函数就创建一个 DiagnosticDescriptor 对象，实际项目中应该是提前定义好的，不用每次循环都创建，甚至作为静态的字段都是合理的

// 找不到满足条件的构造函数，给出分析警告
var diagnosticDescriptor = new DiagnosticDescriptor
(
    id: nameof(Resources.Kaw001),
    title: Localize(nameof(Resources.Kaw001)),
    messageFormat: Localize(nameof(Resources.Kaw001_Message)),
    category: "FooCompiler",
    DiagnosticSeverity.Warning,
    isEnabledByDefault: true
);

大家可以发现，以上代码写了 Resources.Kaw001 资源定义，这部分是依靠在分析器项目里面建立 Resources.resx 资源而被生成的属性。通过建立 Resources.resx 文件，可以复用原本 dotnet 内建的多语言机制，生成多语言程序集等方式提供多语言包。本文这里不过多介绍多语言的创建方式，大家感兴趣还请自行了解

具体做法就是创建 Resources.resx 文件，确保在 csproj 项目里面里面设置为 ResXFileCodeGenerator 生成方式或其他的生成方式

  <ItemGroup>
    <Compile Update="Properties\Resources.Designer.cs">
      <DesignTime>True</DesignTime>
      <AutoGen>True</AutoGen>
      <DependentUpon>Resources.resx</DependentUpon>
    </Compile>
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Update="Properties\Resources.resx">
      <Generator>ResXFileCodeGenerator</Generator>
      <LastGenOutput>Resources.Designer.cs</LastGenOutput>
    </EmbeddedResource>
  </ItemGroup>

在 Resources.resx 文件里面添加两项，内容分别如下

Kaw001 : 找不到符合预期的构造函数
Kaw001_Message : 无法从 {0} 类型中找到构造函数，期望构造函数的只有一个参数，且参数为 {1} 类型

如上文代码，可见 Kaw001 将被当成标题，而 Kaw001_Message 被作为具体警告内容。其中 Kaw001_Message 添加了 {0} 和 {1} 内容，用于分别替换为具体警告信息内容的具体类型

为了作为警告内容，在 DiagnosticDescriptor 需要将 DiagnosticSeverity 设置为 Warning 等级。如期望作为错误，则需要设置为 Error 才可以。可用选项如下所示

  /// <summary>Describes how severe a diagnostic is.</summary>
  public enum DiagnosticSeverity
  {
    /// <summary>
    /// Something that is an issue, as determined by some authority,
    /// but is not surfaced through normal means.
    /// There may be different mechanisms that act on these issues.
    /// </summary>
    Hidden,
    /// <summary>
    /// Information that does not indicate a problem (i.e. not prescriptive).
    /// </summary>
    Info,
    /// <summary>Something suspicious but allowed.</summary>
    Warning,
    /// <summary>
    /// Something not allowed by the rules of the language or other authority.
    /// </summary>
    Error,
  }

以上 category 分类是自己分析器内自定义的，这部分没有做要求，只要自己分类好就可以了。在我所在的团队的 https://github.com/dotnet-campus/dotnetCampus.MSBuildUtils 开源项目里面就内建了一些常用的分类，大家如果没有思路可以参考

上文代码中的 DiagnosticDescriptor 构造函数参数的 Localize 方法的实现如下，其作用是返回支持语言文化的 LocalizableString 类型而不是具体字符串

    public static LocalizableString Localize(string key) =>
        new LocalizableResourceString(key, Resources.ResourceManager, typeof(Resources));

上文代码里面选用的 Kaw001 也是有约束的，即这是一个 C# 的标识符，使用前缀加数字形式，长度小于 15 个字符，确保唯一性。详细约束请参阅 https://learn.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/choosing-diagnostic-ids

完成了对 DiagnosticDescriptor 的定义之后，接下来就可以开始创建 Diagnostic 对象。也如 DiagnosticDescriptor 的构造函数可以看到，其实基本信息都全了，剩下的就是填充具体警告信息的参数内容，即 {0} 和 {1} 参数内容，以及可选的警告的代码 Location 在哪信息而已

var fullNameDisplayFormat = new SymbolDisplayFormat
(
    // 带上命名空间和类型名
    SymbolDisplayGlobalNamespaceStyle.Included,
    // 命名空间之前加上 global 防止冲突
    SymbolDisplayTypeQualificationStyle
        .NameAndContainingTypesAndNamespaces
);
var className = assemblyClassTypeSymbol.ToDisplayString(fullNameDisplayFormat);

// 无法从 {0} 类型中找到构造函数，期望构造函数的只有一个参数，且参数类型为 {1}
Diagnostic diagnostic = Diagnostic.Create(diagnosticDescriptor, exportMethodInfo.Location,
    messageArgs:
    [
        className,
        exportMethodInfo.ConstructorArgumentType.ToDisplayString(fullNameDisplayFormat)
    ]);

如以上代码，可见警告飘红就在分部方法的定义上，内容就是当前的类型和分部方法构成的警告信息。按照本演练的例子，输出信息大概如下

C:\lindexi\Code\Roslyn\KawhawnahemCanalllearlerwhu\KawhawnahemCanalllearlerwhu\Foo.cs(40,5,41,81): warning Kaw001: 无法从 global::KawhawnahemCanalllearlerwhu.F3 类型中找到构造函数，期望构造函数的只有一个参数，且参数为 global::KawhawnahemCanalllearlerwhu.IContext 类型

这个过程中可以看到似乎有分析器的影子在里面了，报告 Diagnostic 过程本身也就是分析器的一个部分，大部分分析器的功能都是和源代码生成器相互重叠的，比如都需要进行语法语义的分析。不同点只是源代码生成器多了一个生成代码的过程

不过这里演示的还不是专用分析器的功能，在下文将会告诉大家如何写一个专用分析器。专用的分析器有更多好用的方法，其核心在于分析要尽量不影响用户编写代码，有各个时机可以选。但源代码生成器是如果没有生成，可能就影响到了用户写代码了，可选时机少了很多

以上就是本演练的全部实现内容。期望能够让大家了解到一个比较全面的源代码生成器的各个方面内容。大家也不要被此吓到，这是我专门找到的能够覆盖源代码生成器所用大部分技术的例子。大部分源代码生成器都不会用到涉及这么全面的技术内容的。以上的例子是我按照我所在的团队的可产品化的开源项目简化的内容，更多细节和产品化处理逻辑，可以去参考开源项目

使用了本演练介绍的技术的可产品化使用的开源项目： https://github.com/dotnet-campus/Telescope

代码

本章的代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 7799af7403b6408b1e30151e144b2273c86433c7

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 7799af7403b6408b1e30151e144b2273c86433c7

获取代码之后，进入 Roslyn/KawhawnahemCanalllearlerwhu 文件夹，即可获取到源代码

生成的源代码保存到本地文件

在本演练里面生成的代码还算简单，也不知道大家是否在一开始就在好奇生成的代码是什么样子的。接下来我将告诉大家如何将生成的源代码保存到本地文件

对于比较复杂的生成代码而言，有时候会导致项目构建不通过。这个技术在实际开发中非常有用，默认的生成代码只能在 VisualStudio 里面的分析器里面一项项展开查看，没有具体的文件路径，对于源代码生成器作者的调试分析不够友好，也不方便将生成的代码发送给其他开发者辅助调试。将生成的源代码保存到本地文件，可以更好的辅助大家进行阅读和调试，以及采用第三方工具辅助分析生成的代码内容

将生成的源代码保存到本地文件只需在 csproj 项目文件里面设置 EmitCompilerGeneratedFiles 属性即可，设置完成之后，默认的生成源代码将会存放到 $(IntermediateOutputPath)\generated 文件夹里面，这里的 $(IntermediateOutputPath) 由 obj\$(Configuration)\$(TargetFramework.ToLowerInvariant())\ 构成，调试下的输出大概是 obj\Debug\net9.0\ 等类似的文件夹里

  <PropertyGroup>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  </PropertyGroup>

如果期望自己指定保存的文件夹，可以自行设置 EmitCompilerGeneratedFiles 属性，如以下代码

  <PropertyGroup>
    <CompilerGeneratedFilesOutputPath>Generated\$(TargetFramework)</CompilerGeneratedFilesOutputPath>
  </PropertyGroup>

以上代码之所以拼接上 TargetFramework 是因为期望默认处理多框架的文件冲突问题，源代码生成器会在多框架下分别执行，为每个框架生成独立的代码。如果在多框架项目下没有配置加上 TargetFramework 将会造成生成的源代码存放的文件冲突

更多请参阅将 Source Generator 生成的源代码保存到本地文件

基础知识

在上文介绍了基础 IIncrementalGenerator 增量源代码生成器的专有方法，如 Where 和 Select 和 Combine 等，这里将详细介绍这几个方法的用法和设计

开始之前重新介绍两个类型的值提供器，分别是 IncrementalValuesProvider 多值提供器和 IncrementalValueProvider 单值提供器。这两个类型的值提供器是源代码生成器的核心，用于提供源代码生成器的输入源

对于 IncrementalValuesProvider 多值提供器来说，里面的每一项都是独立的。比如以下代码

IncrementalValuesProvider<Foo> provider = ...
var t = provider.Select(...);

当某个 Foo 项变更的时候，那么 Select 方法里面的代码就会重新执行，且只执行一次。其他没有变更的 Foo 项则不会触发 Select 方法里面的委托执行。通过类似的方式可以应用缓存，减少计算工作量

有些伙伴会感觉增量源代码生成器这部分 API 比较复杂。确实是比较复杂。但大家需要明确的是，咱现在正在编写的是和编译器相关的代码，所有和编译器沾边的，其难度都不低。在 Roslyn 以及其周边的设施的设计上，都追求性能、编写的复杂度、可维护性等多方面的平衡。如果没有源代码生成的 API 封装，直接面对最裸的编译器相关实现逻辑，那其开发难度和入门门槛可想而知的高

在性能追求方面上，性能优化常用套路里面就是减少计算量。除了语言层面能够提升之外，减少计算工作量能达到算法级的优化，这才是真正的优化。尽管 Roslyn 在发布之初就强调了性能，但即使单次构建足够快，架不住次数多。比如一个代码文件压到 1 毫秒，但我的项目有 2000 个文件，我假设无时不刻都在修改代码，那么每次构建就是 2000 毫秒，也就是 2 秒。这个时间对于一个大型项目来说，还是比较可观的。但事实上，绝大部分的代码我都没有动到，只有少部分的代码在修改。这时候就需要增量构建，只处理修改的代码，这样就能大大减少构建时间。这就是增量构建的优势所在

为了达成增量构建，就需要引入缓存不可变机制。引入缓存不可变机制，在一定程度上能够降低整体逻辑复杂度，不需要让程序猿去内耗对象是否被变更等问题。也方便底层设施搭建者进行复现问题，即方便重现问题，各个部件都是不可变的，方法都是无副作用的，自然重现步骤就简单了

在多方平衡之下，就有了现在大家所看到的 IIncrementalGenerator 增量源代码生成器的各个方法了。虽然看起来复杂，但只要想想原本的开发难度和复杂度，能够被降低到这个程度，就不会觉得这个 API 复杂了

对于 IncrementalValueProvider 单值提供器来说，里面只提供一个值，有时候这个值是一个数组集合，有时候里面就真的是一个值，比如下文会和大家介绍到的配置内容。在 IIncrementalGenerator 增量源代码生成器里面就充满了聚合和散开的逻辑，也推荐这么干，这样的逻辑更底层的思想是实现细颗粒度管控，能够更好地利用缓存，减少计算工作量

无论是 IncrementalValuesProvider 多值提供器还是 IncrementalValueProvider 单值提供器，整体设计都是采用管线方式，走数据流的方式，让数据一步步往下走。在每一步的输出里面都进行缓存检查，如果命中缓存，即没有更改，则不会触发后续的计算。这也就是 IIncrementalGenerator 增量源代码生成器命名的由来，即增量构建，只处理变更的部分。而 Linq 刚好就是数据流的一个现有实践，在增量源代码生成器里面复用了这部分的设计思想，只是 API 实现和行为略微不同，接下来我将逐一和大家介绍这几个方法的用法和设计

本章以下的介绍顺序保持和 https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md 官方文档相同的顺序，对应的代码附图来源于此官方文档

Select

方法签名：

public static partial class IncrementalValueSourceExtensions
{
    // 1 => 1 transform 
    // 1 对 1 的转换，从 TSource 转换为 TResult 类型的输出
    // 为了简单表述，我使用 `IncrementalValue[s]Provider` 代表 `IncrementalValuesProvider` 和 `IncrementalValueProvider` 两个类型的值提供器都适用的情况
    public static IncrementalValue[s]Provider<TResult> Select<TSource, TResult>(this IncrementalValue[s]Provider<TSource> source, Func<TSource, CancellationToken, TResult> selector);
}

这是一个最常用的转换逻辑，用于从当前提供的数据转换为新的数据进行输出，可同时在 IncrementalValuesProvider 多值提供器和 IncrementalValueProvider 单值提供器

为了简单表述，我使用 IncrementalValue[s]Provider 代表 IncrementalValuesProvider 和 IncrementalValueProvider 两个类型的值提供器都适用的情况

如以下代码所示，从 FooInfo1 数据转换为 FooInfo2 数据

        IncrementalValuesProvider<FooInfo1> foo1ValuesProvider = ...

        IncrementalValuesProvider<FooInfo2> foo2ValuesProvider = foo1ValuesProvider.Select((FooInfo1 info1, CancellationToken token) => new FooInfo2());

转换过程中，支持分叉和链式转换。分叉转换，即从一个 IncrementalValue[s]Provider 分叉为多条不同的转换分支，如下面代码所示

        IncrementalValuesProvider<FooInfo1> foo1ValuesProvider = ...

        IncrementalValuesProvider<FooInfo2> foo2ValuesProvider = foo1ValuesProvider.Select((FooInfo1 info1, CancellationToken token) => new FooInfo2());

        IncrementalValuesProvider<FooInfo3> foo3ValuesProvider = foo1ValuesProvider.Select((FooInfo1 info1, CancellationToken token) => new FooInfo3());

可见 foo2ValuesProvider 和 foo3ValuesProvider 来源于共同的 foo1ValuesProvider 数据源。这在多个不同的业务逻辑存在共有转换时非常有用，可以更多程度地进行复用计算

链式转换即一级级进行转换

        IncrementalValuesProvider<FooInfo1> foo1ValuesProvider = ...

        IncrementalValuesProvider<FooInfo2> foo2ValuesProvider = foo1ValuesProvider.Select((FooInfo1 info1, CancellationToken token) => new FooInfo2());

        IncrementalValuesProvider<FooInfo3> foo3ValuesProvider = foo2ValuesProvider.Select((FooInfo2 info2, CancellationToken token) => new FooInfo3());

Select Many

方法签名：

// 1 转 多
// 多 转 多
public static IncrementalValuesProvider<TResult> SelectMany<TSource, TResult>(this IncrementalValue[s]Provider<TSource> source, Func<TSource, CancellationToken, IEnumerable<TResult>> selector);

如以下代码所示，先从 IncrementalValueProvider<FooInfo1> 单值提供器，调用 SelectMany 进行单转多，获取到 IncrementalValuesProvider<FooInfo2> 多值提供器。再继续对 IncrementalValuesProvider<FooInfo2> 多值提供器调用 SelectMany 进行多转多获取到 IncrementalValuesProvider<FooInfo3> 多值提供器

        IncrementalValueProvider<FooInfo1> foo1ValueProvider = ...

        IncrementalValuesProvider<FooInfo2> foo2ValuesProvider = foo1ValueProvider.SelectMany
        (
            (FooInfo1 info1, CancellationToken token) =>
            {
                var n = info1.Number;
                var list = new List<FooInfo2>();
                for (int i = 0; i < n; i++)
                {
                    list.Add(new FooInfo2());
                }

                return list;
            }
        );

        IncrementalValuesProvider<FooInfo3> foo3ValuesProvider = foo2ValuesProvider.SelectMany
        (
            (FooInfo2 info2, CancellationToken token) =>
            {
                var list = new List<FooInfo3>();
                for (int i = 0; i < info2.Count; i++)
                {
                    list.Add(new FooInfo3());
                }

                return list;
            }
        );

假定 FooInfo1 的 Number 的是 3 的值。每个 FooInfo2 的 Count 也是 3 的值，则经过以上转换之后，可获取带有 3x3=9 个元素的 IncrementalValuesProvider<FooInfo3> 多值提供器

从 IncrementalValueProvider<FooInfo1> 单值提供器，调用 SelectMany 进行单转多，获取到 IncrementalValuesProvider<FooInfo2> 多值提供器的过程是 1 转多的过程，相对来说很是清晰

对 IncrementalValuesProvider<FooInfo2> 多值提供器调用 SelectMany 进行多转多获取到 IncrementalValuesProvider<FooInfo3> 多值提供器的过程，相对来说就比较复杂，如以下的官方附图，每项都可转换为不定数量集合输出

敲黑板，使用 SelectMany 的过程中，也可以附带过滤的作用。如上文所述，每项都可转换为不定数量集合输出，不定数量就意味着也可以返回 0 项。在 SelectMany 执行过滤作用的做法就是将不满足条件的直接过滤掉，甚至返回空集合。因此比较少见 SelectMany(...).Where(...) 的组合，直接就是在 SelectMany 里面内置了 Where 的活了

常见于将 SelectMany 和下文介绍的 Collect 混用，达成合和分的效果

Where

方法签名：

public static IncrementalValuesProvider<TSource> Where<TSource>(this IncrementalValuesProvider<TSource> source, Func<TSource, bool> predicate);

没错，只有多值提供器才有 Where 方法。通过 Where 方法可用来过滤输入源里面符合条件的元素，将符合条件的元素作为输出源内容

如上图官方附图所示，假定输入源有三个，中间一个不满足条件，也就是上面打了叉叉的 Item2 项，则最终只有 Item1 和 Item3 才能流向输出源里

正如大家所熟悉的 Linq 里面的 Select 和 Where 配合一样，在增量源代码生成器这里对这两个的用法和设计实现也都和 Linq 的相同

Collect

方法签名：

IncrementalValueProvider<ImmutableArray<TSource>> Collect<TSource>(this IncrementalValuesProvider<TSource> source);

这是一个不用附带任何条件和转换器的方法。用于将一个多值提供器的内容，转换为单值提供器。这个过程中，一旦输入源有任何一项变动，则会重新输出整个新的不可变集合

如以上官方附图所示，通过 Collect 方法将一个多值提供器转换为一个单值提供器，且这个单值提供器提供的单个值就是一个集合

这个 Collect 过程可以认为和 SelectMany 是互逆的过程，即可以从 Collect 由多值提供器转换为一个单值提供器，再从 SelectMany 由单值提供器转换为多值提供器。如以下代码所示

        IncrementalValuesProvider<FooInfo1> foo1ValuesProvider = ...;

        IncrementalValueProvider<ImmutableArray<FooInfo1>> foo1ArrayValueProvider = foo1ValuesProvider.Collect();

        IncrementalValuesProvider<FooInfo1> backToValuesProvider = foo1ArrayValueProvider.SelectMany((ImmutableArray<FooInfo1> array, CancellationToken token) => array);

        foo1ValuesProvider = backToValuesProvider;

以上代码先使用 Collect 方法，从 IncrementalValuesProvider<FooInfo1> 多值提供器，转换为带不可变集合的 IncrementalValueProvider<ImmutableArray<FooInfo1>> 单值提供器

再调用 SelectMany 方法，重新将 IncrementalValueProvider<ImmutableArray<FooInfo1>> 单值提供器转换为原来的 IncrementalValuesProvider<FooInfo1> 多值提供器。从以上代码最后一行可以看到，经过 SelectMany 转换回来的 backToValuesProvider 的类型是完全和 foo1ValuesProvider 一样的，相互赋值都能通过构建

Split

准确来说这只是一个用法，不是一个 API 方法。表示的就是分叉调用，多分支调用。如在 Select 一节中和大家介绍，允许进行分叉转换。事实上，在以上介绍的每个内容里面，每个值提供器，无论是多值提供器还是单值提供器，都可以被多次调用各个方法作为输入源进行消费。这和 Linq 里面的固有印象有所不同，在 Linq 里面，枚举 IEnumerable<TSource> 是不支持多次重复消费的，多次消费将获取不可控结果。但在源代码生成器这里面，数据源的提供依靠的是缓存失效来驱动，或者称为数据变更驱动。一旦有数据变更，缓存失效，则会一条链路进行传递

咱所编写的对各个值提供器的各种转换逻辑，只是用于写入记录转换链路而已。当数据变更的时候，将会重新开始跑整个链路。在跑的过程中，引入了大量缓存判定，从而最大程度减少执行逻辑量

在演练中，咱也用到了 Split 的功能，即在拿到 IncrementalValuesProvider<ImmutableArray<ItemGeneratedCodeResult>> itemGeneratedCodeResultProvider 数据源时，一路作为 Diagnostic 报告输出，一路作为最终源代码生成的输出

Combine

方法签名：

// 1 对 1 合并
IncrementalValueProvider<(TLeft Left, TRight Right)> Combine<TLeft, TRight>(this IncrementalValueProvider<TLeft> provider1, IncrementalValueProvider<TRight> provider2);

// 多对 1 合并
IncrementalValuesProvider<(TLeft Left, TRight Right)> Combine<TLeft, TRight>(this IncrementalValuesProvider<TLeft> provider1, IncrementalValueProvider<TRight> provider2);

和以上的分叉相对，以上的 Split 分叉是将一条值提供器作为多个数据提供源，将一个数据链路拆分为多个数据链路。而 Combine 则是将两个数据链路合并到一个链路。能够支持的合并方式是两个单值提供器的合并，以及一个多值提供器和一个单值提供器的合并

两个单值提供器的合并：

如以上的官方附图，将两个单值提供器的合并，返回结果依然是一个单值提供器。只是返回的输出源里面包含的是一个元组，其中左右值就是所 Combine 顺序的左右值。如以下代码所示

IncrementalValueProvider<FooInfo1> foo1ValueProvider = ...;

IncrementalValueProvider<FooInfo2> foo2ValueProvider = ...;

IncrementalValueProvider<(FooInfo1 Left, FooInfo2 Right)> foo1AndFoo2CombineValueProvider = foo1ValueProvider.Combine(foo2ValueProvider);

以上代码分别将 IncrementalValueProvider<FooInfo1> 和 IncrementalValueProvider<FooInfo2> 两个单值提供器进行合并。合并之后获得了 IncrementalValueProvider<(FooInfo1 Left, FooInfo2 Right)> 的单值提供器

一个多值提供器和一个单值提供器的合并：

如以上的官方附图，最终输出源里面是多值提供器里面的每一项都带着单值提供器里面的内容。即输出源里面的元组的左侧是多值提供器里面的每一项，右侧都是相同的单值提供器里面的元素

那两个多值提供器的合并呢？

敲黑板，在 Combine 方法里面不支持两个多值提供器的合并。因为一旦两个多值提供器进行合并，则一旦出现任何一方某个元素的缓存失效问题，将会有笛卡尔积次的执行风险。只提供一个多值提供器和一个单值提供器的合并，则可以明确让源代码生成器开发者决定其优化方向，即将哪方作为单值提供器

那假定我的业务上就是有两个多值提供器，我确实下一步的逻辑就需要两个多值提供器提供的数据才能完成工作。那此时应该如何开展呢？相信会灵活运用所学知识的伙伴已经想到了方法了。没错，就是将其中一个多值提供器调用 Collect 方法，将其转换为单值提供器，于是就可以继续愉快地调用 Combine 进行一个多值提供器和一个单值提供器的合并。这个过程中，源代码生成器开发者可选用两个多值提供器中量小、变化次数少的一方调用 Collect 转换为单值提供器，从而提供更多的优化效果

以上就是增量源代码生成器的专有基础知识，合理运用好以上的几个数据源处理方法，即可实现对复杂的数据处理的同时，减少计算量

演练：源代码专有 Interceptor 技术

经过了上文的介绍，大家是否对源代码生成器的基础知识有了一定的了解。是否会存在一个错觉，认为源代码生成器最多只是减轻人类程序猿的工作量，但并不能轻易突破人类程序猿难以做到的事情？接下来我将介绍源代码生成器的专有技术 Interceptor 拦截器技术，这是一种源代码生成器专有的技术，可以在构建过程中执行额外的逻辑实现拦截现有代码的功能

或许换个叫法大家会更熟悉这一类型的技术，即 AOP 面向切面编程。核心差别在于源代码生成器方式的 AOP 是发生在编译阶段，可以做到零反射。且过程中是可以实现到完全的调用转发。即大家进行静态代码阅读的时候，看到的是调用了 A 方法，然而实际构建出来的代码是调用了 B 方法。这种技术在实际开发中非常有用，比如在构建过程中进行日志记录、性能监控、权限控制等等

现在直接使用 Interceptor 技术的就有 ASP.NET Core 的配置和部分日志的等模块功能，详细请参阅 Compile-time configuration source generation - .NET - Microsoft Learn

在本演练中，我将和大家介绍如何在源代码生成器里面使用 Interceptor 技术，实现对现有代码的拦截调用转发。将原本调用 Foo 类型的 WriteLine 方法，转发到调用源代码新生成的代码里面。比如有以下的代码，大家猜猜在本演练里面，执行代码将会输出什么内容

class Program
{
    static void Main()
    {
        var c = new Foo();
        c.WriteLine(1);
        c.WriteLine(2);
        c.WriteLine(3);
    }
}

class Foo
{
    public void WriteLine(int message)
    {
        Console.WriteLine($"Foo: {message}");
    }
}

想必大家一看就知道，执行代码将会输出以下内容

Foo: 1
Foo: 2
Foo: 3

然而我告诉大家，以上代码执行的输出将会看我在源代码生成器里面的生成代码怎么写，静态阅读代码是看不出来的。接下来我将和大家介绍如何实现这个功能

为了方便大家拉取代码，我依然是新建两个项目，分别是名为 JuqawhicaqarLairciwholeni 的控制台项目，和名为 JuqawhicaqarLairciwholeni.Analyzer 的分析器项目。项目搭建方式和上文介绍的一样，不再赘述

在本演练任务里面，咱需要拦截所有对 Foo 类型的 WriteLine 方法的调用，将其转换为源代码生成器所生成的新的代码

开始之前先介绍一下 C# 12 引入的 Interceptor 拦截器技术，拦截器技术的核心是通过一个 InterceptsLocationAttribute 特性标记一个方法。被标记的方法可以拦截在 InterceptsLocationAttribute 特性上所设置的所要拦截的代码的调用。如以下代码所示，在名为 FooInterceptor 类型的 InterceptorMethod1 方法上，标记了 InterceptsLocationAttribute 特性，注明了拦截 Program.cs 文件上的某行代码

    static partial class FooInterceptor
    {
        // C:\lindexi\Code\JuqawhicaqarLairciwholeni\JuqawhicaqarLairciwholeni\Program.cs(8,11)
        [InterceptsLocation(version: 1, data: "PSnZx2mpBdT444AVZJmMJX8AAABQcm9ncmFtLmNz")]
        public static void InterceptorMethod1(this global::JuqawhicaqarLairciwholeni.Foo foo, int param)
        {
            Console.WriteLine($"Interceptor1: lindexi is doubi");
        }
    }

这里能够看到的是在 InterceptsLocationAttribute 特性上标记了人类难懂的 PSnZx2mpBdT444AVZJmMJX8AAABQcm9ncmFtLmNz 字符串内容。这其实是对 C:\lindexi\Code\JuqawhicaqarLairciwholeni\JuqawhicaqarLairciwholeni\Program.cs(8,11) 的一个标识，这个标识是由源代码生成器里面的 SemanticModel 的 GetInterceptableLocation 方法提供的

假定 C:\lindexi\Code\JuqawhicaqarLairciwholeni\JuqawhicaqarLairciwholeni\Program.cs(8,11) 对应的代码就是 c.WriteLine(1); 这一行代码。那么在执行代码的时候，将会输出以下内容

Interceptor1: lindexi is doubi

而不是原本预期的 Foo: 1 的输出内容。这就是 Interceptor 拦截器技术的核心，通过拦截器技术，可以在构建过程中执行额外的逻辑实现拦截现有代码的功能

简单了解了 Interceptor 拦截器技术的核心，在本演练中将开始和大家介绍如何实现这个功能，将原本调用 Foo 类型的 WriteLine 方法，转发到调用源代码新生成的代码里面。以下是我的实现效果，将原本代码里面对 Foo 类型的 WriteLine 方法的三个调用，分别转发到源代码生成器所生成的三个不同的方法里面，如下图所示

通过本演练的源代码生成器所处理之后，通过 ILSpy 工具查看生成的 dll 文件，可见最终的生成代码是调用了 FooInterceptor 的三个生成的方法，完全不是静态代码所见的调用 Foo 类型的 WriteLine 方法

即在这个过程里面，所发生的所有科技都在构建之中完成，不会在运行时发生任何额外的调用

在 JuqawhicaqarLairciwholeni.Analyzer 项目里面新建名为 FooIncrementalGenerator 的继承 IIncrementalGenerator 的类型，其代码如下

[Generator(LanguageNames.CSharp)]
public class FooIncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        ...
    }
}

为了分析所有对 Foo 类型的 WriteLine 方法的调用，需要找到所有 InvocationExpressionSyntax 类型的语法点。这些语法点就是各个代码里面调用方法等的地方了，再进一步判断调用的是不是名为 WriteLine 的方法，语法判断部分的工作就完成了。也许有伙伴读到这里会有疑问，为什么只是判断调用的是不是名为 WriteLine 的方法，而不再继续判断是不是 Foo 类型的 WriteLine 方法。这是因为在语法判断里面，我们是无法直接访问到调用的具体类型的，语法层面上只能猜，而猜不如放到语义过程进行准确判断

[Generator(LanguageNames.CSharp)]
public class FooIncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
            context.SyntaxProvider.CreateSyntaxProvider(
            (node, _) =>
            {
                if (node is InvocationExpressionSyntax invocationExpressionSyntax)
                {
                    if (invocationExpressionSyntax.Expression is MemberAccessExpressionSyntax memberAccessExpressionSyntax)
                    {
                        // 这是一个调用名为 WriteLine 的方法代码，但就不知道具体是谁的 WriteLine 了。语法过程中是无法知道具体的类型是哪个的
                        // 比如 Foo a = ...; a.WriteLine(...);
                        // 或 Foo b = ...; b.WriteLine(...);
                        // 此时最多在语法层面只判断出是 WriteLine 方法，进一步判断就交给语义过程了
                        return memberAccessExpressionSyntax.Name.Identifier.Text == "WriteLine";
                    }
                }

                return false;
            },
            (syntaxContext, _) =>
            {
                ...
            });
        ...
    }
}

在语义转换里面，进一步判断所调用的是不是 Foo 类型的 WriteLine 方法，即判断当前调用的 WriteLine 方法是不是在 Foo 类型上面定义的。这里使用 SemanticModel 的 GetSymbolInfo 方法获取到调用的方法的符号信息，接着判断方法符号所在的类型是不是 Foo 类型

            context.SyntaxProvider.CreateSyntaxProvider(
            (node, _) =>
            {
                ...
            },
            (syntaxContext, _) =>
            {
                var symbolInfo = syntaxContext.SemanticModel.GetSymbolInfo(syntaxContext.Node);

                if (symbolInfo.Symbol is not IMethodSymbol methodSymbol
                    // 以下这句判断纯属多余，因为语法过程中已经判断了是 WriteLine 方法
                    || methodSymbol.Name != "WriteLine")
                {
                    return default;
                }

                // 语义过程继续判断具体是否 Foo 类型的 WriteLine 方法
                var className = methodSymbol.ContainingType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
                if (className != "global::JuqawhicaqarLairciwholeni.Foo")
                {
                    return default;
                }

                ...
            })

以上代码判断逻辑里，判断是否为 Foo 类型采用的是字符串判断。除了此实现方式外，还可以使用明确的符号判断方法。通常来说，使用字符串判断能够满足绝大部分情况，且能够适应一定程度的模糊处理，符号判断能够实现更加精准。可根据自身业务需求或喜好选用判断方式。在本文末尾常用方法处，我给出了通过符号进行判断的方法，如感兴趣，还请翻到后文了解实现细节

为了调用 SemanticModel 的 GetInterceptableLocation 方法获取传入到 InterceptsLocationAttribute 特性的必要参数，这里通过 syntaxContext.Node 属性拿到当前正在发起方法调用的 InvocationExpressionSyntax 语法节点。接着调用 GetInterceptableLocation 方法获取到拦截器的位置信息

                ...
                var invocationExpressionSyntax = (InvocationExpressionSyntax) syntaxContext.Node;
                ...

现在 SemanticModel 的 GetInterceptableLocation 方法还被标记了实验性，调用此方法之前需要使用 #pragma warning disable RSEXPERIMENTAL002 开启实验性功能

  var invocationExpressionSyntax = (InvocationExpressionSyntax) syntaxContext.Node;

#pragma warning disable RSEXPERIMENTAL002 // 实验性警告，忽略即可
  InterceptableLocation interceptableLocation = syntaxContext.SemanticModel.GetInterceptableLocation(invocationExpressionSyntax)!;

此时拿到的 InterceptableLocation 对象就是包含了将要拦截的代码的具体信息，包括具体是哪个文件的哪行哪列代码，且这个过程里面还包含了代码文件的摘要信息，确保将要拦截替换的代码是符合源代码生成器在生成过程中所预期的。如以下代码尝试拿到 DisplayLocation 字符串信息内容

  var displayLocation = interceptableLocation.DisplayLocation;

这里的 displayLocation 字符串的大概内容是对应的代码的路径和所在行列信息，如以下代码所示

C:\lindexi\Code\JuqawhicaqarLairciwholeni\JuqawhicaqarLairciwholeni\Program.cs(9,11)

为了演示效果，我这里还尝试使用语法语义方式读取在 Program.cs 里面调用 WriteLine 方法的参数值，即调用 WriteLine 方法的参数值是多少。这里使用 invocationExpressionSyntax.ArgumentList.Arguments 属性获取到所有的参数列表，再取其首个参数。最后配合语义获取传入的常量值

ArgumentSyntax argumentSyntax = invocationExpressionSyntax.ArgumentList.Arguments.First();
var argument = (int)syntaxContext.SemanticModel.GetConstantValue(argumentSyntax.Expression).Value!;

以上代码仅仅用于演示哈，因为这要求原本的代码里面传入参数确实就是常量值。在实际的代码里面，传入的参数可能是变量、表达式等等，不能像本演练里面这样直接获取到常量值

完成准备工作之后，就可以开始来生成代码啦

依然是为了让我的博客引擎开森，我将以下代码的两个连在一起的花括号替换为全角的花括号

var generatedCode =
    $$"""
      using System.Runtime.CompilerServices;
      
      namespace Foo_JuqawhicaqarLairciwholeni
      {
          static partial class FooInterceptor
          {
              // ｛｛displayLocation｝｝
              [InterceptsLocation(version: ｛｛interceptableLocation.Version｝｝, data: "｛｛interceptableLocation.Data｝｝")]
              public static void InterceptorMethod｛｛argument｝｝(this ｛｛className｝｝ foo, int param)
              {
                  Console.WriteLine($"Interceptor｛｛argument｝｝: lindexi is doubi");
              }
          }
      }

      namespace System.Runtime.CompilerServices
      {
          [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
          file sealed class InterceptsLocationAttribute : Attribute
          {
              public InterceptsLocationAttribute(int version, string data)
              {
                  _ = version;
                  _ = data;
              }
          }
      }
      """;

如以上代码所示，可以看到将 displayLocation 作为注释放在拦截方法上方，如此即可在阅读源代码生成器所生成的代码的时候，可以看到被拦截的代码的位置信息。接着再将读取到的传入参数信息拼接成为拦截方法的方法名以及作为拦截方法的输出内容

由于 InterceptsLocationAttribute 本身也只是一个给编译器看的特性，不在 Runtime 里面定义，且编译器也不关心这个类型的可见性，编译器只关心特性的全名，即命名空间和类型名符合要求即可。那就直接开森地使用 file 关键字进行修饰，放入到对应的生成的代码所在文件里面。这样也可以防止定义的 InterceptsLocationAttribute 特性去污染其他源代码生成器或项目里面的代码

完成了生成代码的拼接，为了将其进行返回，这里再定义一个名为 GeneratedCodeInfo 的结构体，代码如下

readonly record struct GeneratedCodeInfo(string GeneratedCode, string Name);

将其作为返回值返回，且再叠加一个 Where 方法过滤掉不符合条件的情况

        IncrementalValuesProvider<GeneratedCodeInfo> sourceProvider = context.SyntaxProvider.CreateSyntaxProvider(
            (node, _) =>
            {
                ...
            },
            (syntaxContext, _) =>
            {
                var invocationExpressionSyntax = (InvocationExpressionSyntax) syntaxContext.Node;
                ArgumentSyntax argumentSyntax = invocationExpressionSyntax.ArgumentList.Arguments.First();
                var argument = (int) syntaxContext.SemanticModel.GetConstantValue(argumentSyntax.Expression).Value!;

                var generatedCode = ...

                return new GeneratedCodeInfo(generatedCode, $"FooInterceptor{argument}.cs");
            })
            .Where(t => t != default);

最后将 sourceProvider 值提供器注册到 RegisterImplementationSourceOutput 方法上即可。为什么是注册到 RegisterImplementationSourceOutput 方法上呢？因为这里面只是包含了具体的实现逻辑，没有任何可以参与语法分析的定义部分，也不会被外部所访问，放入到 RegisterImplementationSourceOutput 方法上十分合适

        context.RegisterImplementationSourceOutput(sourceProvider,
           (productionContext, provider) =>
           {
               productionContext.AddSource(provider.Name, provider.GeneratedCode);
           });

通过以上的源代码生成器的代码，即可实现本演练中的拦截效果。最后尝试运行一下 JuqawhicaqarLairciwholeni 控制台项目，可看到输出内容是

Interceptor1: lindexi is doubi
Interceptor2: lindexi is doubi
Interceptor3: lindexi is doubi

这项 Interceptor 拦截器技术的介绍就到这里，拦截器技术现在还是有很多争议的，核心一点是破坏原本的静态代码阅读能力。静态阅读代码，不运行不构建时，所见的代码认为的运行效果不等于最终执行效果。这将会给很多开发者带来困惑，甚至可能被用于恶意代码的隐藏。但是在某些场景下，拦截器技术是非常有用的，比如在构建过程中进行日志记录、性能监控、权限控制等等，将原本影响性能的代码使用拦截器重新实现生成，不破坏原本代码结构等等

整个使用 Interceptor 拦截器的源代码生成器的代码如下，同样是为了让我的博客引擎开森，我将以下代码的两个连在一起的花括号替换为全角的花括号

[Generator(LanguageNames.CSharp)]
public class FooIncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        IncrementalValuesProvider<GeneratedCodeInfo> sourceProvider = context.SyntaxProvider.CreateSyntaxProvider(
            (node, _) =>
            {
                if (node is InvocationExpressionSyntax invocationExpressionSyntax)
                {
                    if (invocationExpressionSyntax.Expression is MemberAccessExpressionSyntax memberAccessExpressionSyntax)
                    {
                        // 这是一个调用名为 WriteLine 的方法代码，但就不知道具体是谁的 WriteLine 了。语法过程中是无法知道具体的类型是哪个的
                        // 比如 Foo a = ...; a.WriteLine(...);
                        // 或 Foo b = ...; b.WriteLine(...);
                        // 此时最多在语法层面只判断出是 WriteLine 方法，进一步判断就交给语义过程了
                        return memberAccessExpressionSyntax.Name.Identifier.Text == "WriteLine";
                    }
                }

                return false;
            },
            (syntaxContext, _) =>
            {
                var symbolInfo = syntaxContext.SemanticModel.GetSymbolInfo(syntaxContext.Node);

                if (symbolInfo.Symbol is not IMethodSymbol methodSymbol
                    // 以下这句判断纯属多余，因为语法过程中已经判断了是 WriteLine 方法
                    || methodSymbol.Name != "WriteLine")
                {
                    return default(GeneratedCodeInfo);
                }

                // 语义过程继续判断具体是否 Foo 类型的 WriteLine 方法
                var className = methodSymbol.ContainingType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
                if (className != "global::JuqawhicaqarLairciwholeni.Foo")
                {
                    return default(GeneratedCodeInfo);
                }

                /*
                   class Foo
                   {
                       public void WriteLine(int message)
                       {
                           Console.WriteLine($"Foo: {message}");
                       }
                   }
                 */

                var invocationExpressionSyntax = (InvocationExpressionSyntax) syntaxContext.Node;
                ArgumentSyntax argumentSyntax = invocationExpressionSyntax.ArgumentList.Arguments.First();
                var argument = (int)syntaxContext.SemanticModel.GetConstantValue(argumentSyntax.Expression).Value!;

#pragma warning disable RSEXPERIMENTAL002 // 实验性警告，忽略即可
                var interceptableLocation = syntaxContext.SemanticModel.GetInterceptableLocation(invocationExpressionSyntax)!;

                var displayLocation = interceptableLocation.GetDisplayLocation();

                var generatedCode =
                    $$"""
                      using System.Runtime.CompilerServices;
                      
                      namespace Foo_JuqawhicaqarLairciwholeni
                      {
                          static partial class FooInterceptor
                          {
                              // ｛｛displayLocation｝｝
                              [InterceptsLocation(version: ｛｛interceptableLocation.Version｝｝, data: "｛｛interceptableLocation.Data｝｝")]
                              public static void InterceptorMethod｛｛argument｝｝(this ｛｛className｝｝ foo, int param)
                              {
                                  Console.WriteLine($"Interceptor｛｛argument｝｝: lindexi is doubi");
                              }
                          }
                      }

                      namespace System.Runtime.CompilerServices
                      {
                          [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
                          file sealed class InterceptsLocationAttribute : Attribute
                          {
                              public InterceptsLocationAttribute(int version, string data)
                              {
                                  _ = version;
                                  _ = data;
                              }
                          }
                      }
                      """;

                return new GeneratedCodeInfo(generatedCode, $"FooInterceptor{argument}.cs");
            })
            .Where(t => t != default);

        context.RegisterImplementationSourceOutput(sourceProvider,
           (productionContext, provider) =>
           {
               productionContext.AddSource(provider.Name, provider.GeneratedCode);
           });
    }
}

readonly record struct GeneratedCodeInfo(string GeneratedCode, string Name);

更多拦截器技术的介绍请参阅： Interceptors document

本演练代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin f242a711c0f2fb65a01406a36042d87fc314cb51

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin f242a711c0f2fb65a01406a36042d87fc314cb51

获取代码之后，进入 Roslyn/JuqawhicaqarLairciwholeni 文件夹，即可获取到源代码

以上介绍的都是从代码入手，通过对现有的代码进行分析而生成新的代码。大家是否好奇其输入源还有没有其他方式。接下来将通过演练的方式和大家分别介绍从 csproj 等项目属性配置以及通过其他非代码文件的方式进行源代码生成

演练：将构建时间和自定义配置写入源代码

本次演练的任务是将构建时间和自定义配置写入源代码。这个任务的背景是，有时候我们想要直接从代码里面读取一些构建时的信息，比如构建时间呀、一些自定义配置呀等等。这个任务的目的是让大家了解如何从 csproj 项目文件里面读取属性配置，以及如何将这些属性配置写入源代码

再细化一下，我期望的是能够在源代码里面写出以下代码

Console.WriteLine($"BuildAt={BuildInformation.BuildAt}");
Console.WriteLine($"Platform={BuildInformation.Platform}");
Console.WriteLine($"Configuration={BuildInformation.Configuration}");

运行的输出内容大概如下

BuildAt=2025/3/9 13:41:29
Platform=AnyCpu
Configuration=Release

以上的 BuildInformation 类型就是一个由源代码生成器生成的类，里面包含了构建时间、平台和配置信息

在源代码生成器里面，不需要直接碰触 csproj 项目文件的读取，取而代之的是从 CompilationProvider 值提供器里面获取到项目的编译信息

这里也能和大家证明的是，作为源代码生成器的输入源，不仅仅是代码，还可以是其他的一些信息。这里的信息是编译信息，也可以是其他的一些信息，比如额外的文件等等信息

此演练的核心实现方法如下，首先是从 CompilationProvider 值提供器里面获取到项目的编译信息，接着就可以愉快地写入生成的代码啦，非常简单。这里我就跳过了项目创建的步骤，直接到核心代码的实现

    [Generator(LanguageNames.CSharp)]
    public class FooGenerator : IIncrementalGenerator
    {
        public void Initialize(IncrementalGeneratorInitializationContext context)
        {
            var compilerOptions = context.CompilationProvider.Select((s, _) => s.Options);
        }
    }

以上的 compilerOptions 就包含了构建配置信息，如 Platform 和 Configuration 等信息。当然了以上的这句 Select 纯属卖萌，没有挑拣出任何有用信息，也没有做转换，不符合最佳实践，只能作为演示

接下来就直接将 compilerOptions 放入到 RegisterSourceOutput 方法里面，进行生成源代码，如以下代码

            context.RegisterSourceOutput(compilerOptions, static (productionContext, options) =>
            {
                var code = $@"
using System;
using System.Globalization;

public static class BuildInformation
｛｛
    /// <summary>
    /// Returns the build date (UTC).
    /// </summary>
    public static readonly DateTime BuildAt = DateTime.ParseExact(""{DateTime.UtcNow:O}"", ""O"", CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind);
    /// <summary>
    /// Returns the platform.
    /// </summary>
    public const string Platform = ""{options.Platform}"";
    /// <summary>
    /// Returns the configuration.
    /// </summary>
    public const string Configuration = ""{options.OptimizationLevel}"";
｝｝
";

                productionContext.AddSource("LinkDotNet.BuildInformation.g", code);
            });

同样地，为了让我的博客引擎开森，以上代码部分花括号被我替换为了全角花括号。大家在使用的时候需要将全角花括号替换为半角花括号

这就完成了生成了一个名为 BuildInformation 的静态类，且此静态类还没有包含在任何的命名空间里面

大家如果对更多细节感兴趣，还请参阅 IIncrementalGenerator 增量 Source Generator 生成代码应用将构建时间写入源代码

以上就是采用 CompilationProvider 间接读取 csproj 项目文件的属性配置，将自定义配置内容写入源代码的过程。接下来将继续通过演练的方式，告诉大家如何在分析器项目里面读取其他非代码文件的内容

演练：写一个禁用API调用分析器

前面介绍的都是围绕着编写源代码生成器展开的，本章将介绍使用专用分析器技术编写一个纯分析器。这个过程中也会介绍如何读取其他非代码文件的内容作为输入源的方式

在前面的章节有和大家演示过调用 ReportDiagnostic 给出分析报告的方法。在源代码生成器里面给出的分析报告的步骤是进行语法和语义的分析，判断符合某个条件，则给出分析报告的结果。整个过程是非常公式化的。只不过在源代码生成器步骤里面更加侧重如何进行生成代码，从而需要许多细节的分析语法和语义的过程。专用的分析器则可以更大程度地省略掉这些琐碎的步骤，让大家可以使用根据方便的高级的 API 进行快速的分析语法语义

为了能够更好地介绍专用分析器，在本章演练过程中，咱将带着这样的一个任务开始：编写一个禁用API调用分析器

具体的任务需求细节是根据配置的禁用 API 调用文件里面记录的禁用列表，扫描整个项目里面，如果有哪个代码访问了在禁用 API 调用文件记录的禁用方法列表，则给出错误提示

这个需求任务可以强行拆分为两步，第一步是获取到禁用 API 调用文件里面记录的禁用列表，第二步的扫描分析代码调用关系

先不着急建立分析器项目，为了能够让大家更好地理解本演练的内容，这里选择先搭建好一个用于测试的项目，我这里创建名为 NelbecarballReanallyerhohe 的控制台项目，在控制台项目里面存放一个名为 BanList.txt 的文件。这个文件只是一个默认的文本文件，里面存放了一条禁用 API 调用的记录，如以下内容，禁用的是控制台输出的 WriteLine 方法

System.Console.WriteLine

其含义就是如果在当前项目里面，一旦有代码调用了 System.Console.WriteLine 方法，就会给出错误提示

在 Program.cs 里面保持原样的 Console.WriteLine("Hello, World!"); 输出。尝试构建项目，要求给出错误提示，告诉开发者不能调用被禁用的 System.Console.WriteLine 方法，如输出以下错误内容

error Ban01: 不能调用禁用的 API 哦，WriteLine 被 BanList.txt 标记禁用

以上就是整个演练的任务需求，这是一个非常经典的分析器任务。也适用于在真实项目里面做 API 约束。比如现在咱正在编写的分析器项目的 EnforceExtendedAnalyzerRules 限制属性，其实现原理也和本章将要介绍的具体技术十分接近。如果大家忘了 EnforceExtendedAnalyzerRules 属性，还请向前翻翻，或参阅 Roslyn 分析器 EnforceExtendedAnalyzerRules 属性的作用

开始编写专用分析器。搭建项目的方式和上文介绍的源代码生成器一样，也如上文所述，源代码生成器和分析器本身就一体的。在一个项目里面同时存在专用分析器和源代码生成器是完全被允许的，也是被推荐的做法。这里就不再详细展开项目的创建方法了，如需整个项目代码，可在本章末尾找到本章所有代码的下载拉取方法

在分析器项目里面创建一个名为 BanAPIAnalyzer 的类型，让其继承自 Microsoft.CodeAnalysis.Diagnostics.DiagnosticAnalyzer 类型。如此即可让 BanAPIAnalyzer 成为专用分析器。继承之后，就需要实现 DiagnosticAnalyzer 抽象类型的 SupportedDiagnostics 属性和 Initialize 方法

在专用分析器的设计里面，要求实现 SupportedDiagnostics 属性，告诉框架层当前这个专用分析器类型支持哪些 Diagnostic 内容。一旦 IDE 等配置某些 Diagnostic 被禁用时，如果当前的这个专用分析器的所有 Diagnostic 内容都被禁用，则此专用分析器将不会被启用。另一个作用则是可以在 VisualStudio 的分析器列表里面枚举查看信息，方便配置。比如通过 .editorconfig 文件，将原本是错误等级的 Diagnostic 设置为警告等级

# 演示在 .editorconfig 文件将原本是 error 等级的 Ban01 设置为 warning 等级
dotnet_diagnostic.Ban01.severity = warning

在本演练这里，只添加一个 DiagnosticDescriptor 到 SupportedDiagnostics 属性。如任务需求所述，本演练这里只有一个禁用 API 调用的分析。创建 DiagnosticDescriptor 的方法在上文已经有详细介绍了，上文介绍的是支持多语言的创建方式，相对来说比较繁琐，但也正式。我在这里和大家介绍另一个方式，就是只有单个语言的固定字符串方式，当然了，这样的方式适用范围肯定更小了，难以全球化使用

[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class BanAPIAnalyzer : DiagnosticAnalyzer
{

    ... // 忽略其他代码

    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = new[]
    {
        new DiagnosticDescriptor("Ban01", "CallBanAPI", "不能调用禁用的 API 哦，{0} 被 {1} 标记禁用", category: "Error",
            DiagnosticSeverity.Error, isEnabledByDefault: true)
    }.ToImmutableArray();
}

和源代码生成器一样，核心的代码实现放在 Initialize 方法里面。这两个 Initialize 不同点在于其方法参数上，以下是专用分析器的 Initialize 方法的签名

public override void Initialize(AnalysisContext context)
{
    ... // 忽略其他代码
}

通常的专用分析器在 Initialize 的第一句话是调用 AnalysisContext 的 EnableConcurrentExecution 方法。这句话的作用是告诉框架层，当前的专用分析器是线程安全的，可以多线程并发执行。这样可以提高分析器的执行效率，但也要求开发者在编写专用分析器的时候要保证线程安全。不过在调试过程中，却通常将其注释掉，防止多线程进入让调试困难

[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class BanAPIAnalyzer : DiagnosticAnalyzer
{
    public override void Initialize(AnalysisContext context)
    {
        context.EnableConcurrentExecution();

        ... // 忽略其他代码
    }

    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = new[]
    {
        new DiagnosticDescriptor("Ban01", "CallBanAPI", "不能调用禁用的 API 哦，{0} 被 {1} 标记禁用", category: "Error",
            DiagnosticSeverity.Error, isEnabledByDefault: false)
    }.ToImmutableArray();
}

在 Initialize 的第二句话通常是配置是否对源代码生成器生成的源代码进行分析，默认咱选 None 即可，如以下代码

    public override void Initialize(AnalysisContext context)
    {
        context.EnableConcurrentExecution();
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);

        ... // 忽略其他代码
    }

这两句话的调用时机没有约束，换句话说就是顺序倒过来也毫无影响

喜欢点点点的伙伴也许看到了在 AnalysisContext 类型里面充满了各种 RegisterXxxAction 的方法。这些方法的作用都是寻找一个注入点，即在什么时机进行分析、在什么范围内进行分析。越是靠后的时机，能够拿到的信息越多，但其分析提示可能就不够及时。具体选用什么时机进行分析，如果把握不准的话，大家可以先选一个比较靠后的时机，调试成功之后再逐渐选择比较靠前的时机。这里的靠前和靠后相对的是构建时机。在本演练里面，为了演示方便，就选用了很是靠后的 RegisterCompilationStartAction 时机，在这里能够拿到完全的 AdditionalFile 附加文件，即 BanList.txt 文件

现在开始这个专用分析器实现的第一步，获取到禁用 API 调用文件里面记录的禁用列表。在咱这个专用分析器里面，比较灵活，允许开发者设置哪个文件记录的就是禁用 API 列表的文件。如在控制台项目（敲黑板，非分析器项目，是那个被分析的项目）里面的 csproj 项目文件通过如下代码指定 BanList.txt 就是记录禁用 API 列表的文件

  <PropertyGroup>
    <BanAPIFileName>BanList.txt</BanAPIFileName>
  </PropertyGroup>

一般的分析器项目都在分发的时候带上 $(PackageId).targets 和 $(PackageId).props 文件。但咱这里没有通过 NuGet 进行分发，因此一些可以放在 $(PackageId).targets 和 $(PackageId).props 文件的杂活就需要放入到被分析的项目里面。详细关于如何打包 NuGet 进行分发，我将在下文详细和大家介绍

为什么会提到 $(PackageId).targets 和 $(PackageId).props 文件的杂活呢？这是因为咱在被分析的控制台项目的 csproj 项目文件配置的 BanAPIFileName 属性内容，默认情况下是无法直接被分析器项目感知到的，添加的 BanList.txt 文件也无法被分析器直接感知到。为了让分析器能够拿到配置的 BanAPIFileName 属性，以及 BanList.txt 文件，就需要在被分析的控制台项目的 csproj 项目文件里面添加额外的配置

CompilerVisibleProperty ：用于标记有哪些 Property 可以被分析器感知到
AdditionalFiles ：添加用于让分析器项目使用的附加文件，官方翻译为 分析器其他文件 或 C# 分析器其他文件

按照以上描述可以了解到，咱需要通过 CompilerVisibleProperty 标记 BanAPIFileName 属性，使用 AdditionalFiles 添加 BanList.txt 文件，即让 BanList.txt 使用 C# 分析器其他文件 生成方式，如下图所示

修改之后的被分析的控制台项目的 csproj 项目文件内容大概如下

  <PropertyGroup>
    <BanAPIFileName>BanList.txt</BanAPIFileName>
  </PropertyGroup>

  <ItemGroup>
    <CompilerVisibleProperty Include="BanAPIFileName" />
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles Include="BanList.txt" />
  </ItemGroup>

对于一个通过 NuGet 分发的分析器项目，则是会在 $(PackageId).props 文件里面存放 <CompilerVisibleProperty Include="BanAPIFileName" /> 和 <AdditionalFiles Include="BanList.txt" /> 这两个配置，而不需要被分析项目添加这些杂活

以上介绍的 CompilerVisibleProperty 和 AdditionalFiles 是对整个分析器生效，即无论是专用分析器还是源代码生成器，这部分知识内容都完全相同

如对在分析器项目里面读取 PropertyGroup 里面的 Property 感兴趣，还请参阅读取 csproj 项目文件的属性配置方法

完成被分析的控制台项目的 csproj 项目文件配置之后，就可以在 RegisterCompilationStartAction 方法内通过 BanAPIFileName 属性了解到哪个 AdditionalFiles 就是标记禁用列表的文件，其代码如下

    public override void Initialize(AnalysisContext context)
    {
        context.EnableConcurrentExecution();
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);

        context.RegisterCompilationStartAction((CompilationStartAnalysisContext analysisContext) =>
        {
            if (analysisContext.Options.AnalyzerConfigOptionsProvider.GlobalOptions.TryGetValue(
                    "build_property.BanAPIFileName", out var fileName))
            {
                ... // 忽略其他代码
            }
        });
    }

再遍历 AdditionalFiles 找到记录禁用 API 列表的文件，代码如下

        context.RegisterCompilationStartAction(analysisContext =>
        {
            if (analysisContext.Options.AnalyzerConfigOptionsProvider.GlobalOptions.TryGetValue(
                    "build_property.BanAPIFileName", out var fileName))
            {
                AdditionalText? file = analysisContext.Options.AdditionalFiles.FirstOrDefault(t =>
                    Path.GetFileName(t.Path) == fileName);
                if (file != null)
                {
                    ... // 忽略其他代码
                }
            }
        });

也许有伙伴表示，这样的实现方法需要两步，第一步是读取 Property 属性，第二步是遍历 AdditionalFiles 文件，相对来说比较麻烦。能否直接在 AdditionalFiles 里面标记配置呢？即如以下的写法

  <PropertyGroup>
    <!-- 不要 BanAPIFileName 属性，直接在文件标记 -->
    <!-- <BanAPIFileName>BanList.txt</BanAPIFileName> -->
  </PropertyGroup>

  <ItemGroup>
    <!-- 不要 BanAPIFileName 属性，自然也就不要 CompilerVisibleProperty 配置 -->
    <!-- <CompilerVisibleProperty Include="BanAPIFileName" /> -->
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles Include="BanList.txt" IsBanAPIFileName="True"/>
  </ItemGroup>

这当然是完全可以的啦，只不过其读取方法需要更改一下，按照 Roslyn 分析器读取 csproj 项目文件的 AdditionalFiles Item 的 Metadata 配置进行更改。一般情况下不会这么写的，因为在有 NuGet 分发的帮助下，将杂活放入到 props 文件里面，整个实际的被分析项目只有编写 <BanAPIFileName>BanList.txt</BanAPIFileName> 这一句配置，相对来说会比写 <AdditionalFiles Include="BanList.txt" IsBanAPIFileName="True"/> 更加方便

获取到了配置禁用 API 列表的文件之后，即可通过 AdditionalText.GetText 方法获取到文件内容，代码如下

AdditionalText file = ...;
SourceText sourceText = file.GetText(analysisContext.CancellationToken);

这里依然和源代码生成器一样，将令牌传入到调用 AdditionalText.GetText 方法里面，避免读取文件过程中被分析的内容变更导致白白读取内容进行空等

进一步的，直接获取 SourceText 的 Lines 属性，即可拿到一行一个禁用 API 的列表。为了后续判断方便，咱将其转换为哈希集合，合起来的代码如下

var file = analysisContext.Options.AdditionalFiles.FirstOrDefault(t =>
    Path.GetFileName(t.Path) == fileName);
if (file != null)
{
    ImmutableHashSet<string> banSet =
        file.GetText()?.Lines.Select(t => t.ToString()).ToImmutableHashSet) ??
        ImmutableHashSet<string>.Empty;

    ... // 忽略其他代码
}

以上代码就是获取到了禁用 API 列表的文件内容，接下来就是扫描分析代码调用关系，进入到这个专用分析器实现的第二步。这个过程和源代码生成器的分析过程类似，只不过这里不需要生成代码，而是给出分析报告。只是给出分析结果，咱有更多便捷的方法可用，不再和源代码生成器的分析一样逐个爬语法树或者语义树的节点，而是直接使用 RegisterSyntaxNodeAction 方法，给定感兴趣的分析内容点

在咱本次演练内容里面，核心就是判断调用的方法是否在禁用列表里面。即感兴趣的分析内容点就是代码里面方法调用，即 SyntaxKind.InvocationExpression 内容。于是在调用 RegisterSyntaxNodeAction 方法过程，将 SyntaxKind.InvocationExpression 作为第二个参数传入，代码如下

ImmutableHashSet<string> banSet =
    file.GetText()?.Lines.Select(t => t.ToString()).ToImmutableHashSet() ??
    ImmutableHashSet<string>.Empty;

analysisContext.RegisterSyntaxNodeAction((SyntaxNodeAnalysisContext nodeAnalysisContext) =>
{
    ... // 忽略其他代码
}, SyntaxKind.InvocationExpression);

由于在 RegisterSyntaxNodeAction 参数要求了是 InvocationExpression 类型，在 RegisterSyntaxNodeAction 的委托里面，就可以使用强转方式将 nodeAnalysisContext.Node 转换为 InvocationExpressionSyntax 类型，代码如下

analysisContext.RegisterSyntaxNodeAction(nodeAnalysisContext =>
{
    var invocationExpression = (InvocationExpressionSyntax) nodeAnalysisContext.Node;

    ... // 忽略其他代码
}, SyntaxKind.InvocationExpression);

分析调用的 API 离不开语义的辅助，从全语法层面是难以或无法知道具体调用的 API 是哪个的。通过 SemanticModel 获取语义符号，即可知道调用的 API 是哪个

analysisContext.RegisterSyntaxNodeAction(nodeAnalysisContext =>
{
    var invocationExpression = (InvocationExpressionSyntax) nodeAnalysisContext.Node;

    var symbolInfo = nodeAnalysisContext.SemanticModel.GetSymbolInfo(invocationExpression);
    if (symbolInfo.Symbol is not IMethodSymbol symbol)
    {
        return;
    }

    ... // 忽略其他代码
}, SyntaxKind.InvocationExpression);

理论上这里拿到的 Symbol 必然是 IMethodSymbol 且不是空的

拿到方法符号之后，再获取这个方法所在的类型是哪一个，代码如下

analysisContext.RegisterSyntaxNodeAction(nodeAnalysisContext =>
{
    var invocationExpression = (InvocationExpressionSyntax) nodeAnalysisContext.Node;

    var symbolInfo = nodeAnalysisContext.SemanticModel.GetSymbolInfo(invocationExpression);
    if (symbolInfo.Symbol is not IMethodSymbol symbol)
    {
        return;
    }

    var containingType = symbol.ContainingType;

    ... // 忽略其他代码
}, SyntaxKind.InvocationExpression);

既然已经拿到被调用的方法和被调用的方法所在的类型，那就可以简单使用字符串匹配的方式判断方法是否在禁用列表里面。即先取出其带命名空间的全名，拼接带命名空间的类型名和方法名即可用于判断，代码如下

var containingType = symbol.ContainingType;

var symbolDisplayFormat = new SymbolDisplayFormat
(
    // 带上命名空间和类型名
    SymbolDisplayGlobalNamespaceStyle.Omitted,
    // 命名空间之前加上 global 防止冲突
    SymbolDisplayTypeQualificationStyle
        .NameAndContainingTypesAndNamespaces
);

var containingTypeName = containingType.ToDisplayString(symbolDisplayFormat);
var name = symbol.Name;
var methodName = $"{containingTypeName}.{name}";

如此即可拿到方法全名，即 命名空间.类型.方法名 的格式。再进入 banSet 集合判断一下即可了解当前的调用方法是否在禁用了集合中

var methodName = $"{containingTypeName}.{name}";

if (banSet.Contains(methodName))
{
    ... // 当前调用的方法在禁用列表中
}

一旦判断当前调用的方法在禁用集合内，则给出错误信息。给出错误信息时，可选列出代码所在的文件、第几行第几列的 Location 信息。从 SyntaxNodeAnalysisContext.Node 创建出 Location 对象，代码如下

var location = Location.Create(nodeAnalysisContext.Node.SyntaxTree, nodeAnalysisContext.Node.FullSpan);

再将符号名，即方法名，和记录禁用 API 列表的文件名传入到方法列表里面，用于填充错误详细信息的 "不能调用禁用的 API 哦，{0} 被 {1} 标记禁用" 里面的 {0} 和 {1} 内容，代码如下

nodeAnalysisContext.ReportDiagnostic(Diagnostic.Create(SupportedDiagnostics[0],
    location,
    messageArgs: new object[] { symbol.Name, fileName }));

如此即可完成本演练的禁止调用禁用列表的 API 的分析器，整个 BanAPIAnalyzer 类的代码如下，可以看到使用很少的代码量就能实现此功能

[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class BanAPIAnalyzer : DiagnosticAnalyzer
{
    public override void Initialize(AnalysisContext context)
    {
        context.EnableConcurrentExecution();
        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);

        context.RegisterCompilationStartAction(analysisContext =>
        {
            if (analysisContext.Options.AnalyzerConfigOptionsProvider.GlobalOptions.TryGetValue(
                    "build_property.BanAPIFileName", out var fileName))
            {
                var file = analysisContext.Options.AdditionalFiles.FirstOrDefault(t =>
                    Path.GetFileName(t.Path) == fileName);
                if (file != null)
                {
                    ImmutableHashSet<string> banSet =
                        file.GetText()?.Lines.Select(t => t.ToString()).ToImmutableHashSet() ??
                        ImmutableHashSet<string>.Empty;

                    analysisContext.RegisterSyntaxNodeAction(nodeAnalysisContext =>
                    {
                        var invocationExpression = (InvocationExpressionSyntax) nodeAnalysisContext.Node;
                        var symbolInfo = nodeAnalysisContext.SemanticModel.GetSymbolInfo(invocationExpression);
                        if (symbolInfo.Symbol is not IMethodSymbol symbol)
                        {
                            return;
                        }

                        var containingType = symbol.ContainingType;

                        var symbolDisplayFormat = new SymbolDisplayFormat
                        (
                            // 带上命名空间和类型名
                            SymbolDisplayGlobalNamespaceStyle.Omitted,
                            // 命名空间之前加上 global 防止冲突
                            SymbolDisplayTypeQualificationStyle
                                .NameAndContainingTypesAndNamespaces
                        );

                        var containingTypeName = containingType.ToDisplayString(symbolDisplayFormat);
                        var name = symbol.Name;
                        var methodName = $"{containingTypeName}.{name}";

                        if (banSet.Contains(methodName))
                        {
                            var location = Location.Create(nodeAnalysisContext.Node.SyntaxTree, nodeAnalysisContext.Node.FullSpan);

                            nodeAnalysisContext.ReportDiagnostic(Diagnostic.Create(SupportedDiagnostics[0],
                                location,
                                messageArgs: new object[] { symbol.Name, fileName }));
                        }
                    }, SyntaxKind.InvocationExpression);
                }
            }
        });
    }

    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = new[]
    {
        new DiagnosticDescriptor("Ban01", "CallBanAPI", "不能调用禁用的 API 哦，{0} 被 {1} 标记禁用", "Error",
            DiagnosticSeverity.Error, true)
    }.ToImmutableArray();
}

以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin ed27dcda954d4baed58c74b9c1e355468c7135fc

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin ed27dcda954d4baed58c74b9c1e355468c7135fc

获取代码之后，进入 Roslyn/NelbecarballReanallyerhohe 文件夹，即可获取到源代码

既然有了分析器，可以给开发者报告出一些警告或错误信息，那是否还能自动帮助开发者修复这些问题呢？这就需要用到超过本文范围的代码修改器知识了。编写代码修改器是另外的故事了，这里就不展开了，如果大家对此感兴趣，可以参阅使用 Roslyn 分析代码注释，给 TODO 类型的注释添加负责人、截止日期和 issue 链接跟踪 - walterlv

演练：用源代码生成技术实现中文编程语言

自然而然，大家了解到了从任意的其他非代码文件也能作为输入源，那么是不是可以实现中文编程语言呢？也就是说能否实现从一个包含中文编程语言的文件里面，读取其内容，根据其内容生成对应的代码，通过此方式实现中文编程语言

开始之前，先给大家看看效果

如果大家感觉这个效果很酷，那请参阅 dotnet 用 SourceGenerator 源代码生成技术实现中文编程语言文章，里面详细介绍了如何通过源代码生成技术实现中文编程语言

打包 NuGet 包进行分发

学习了很多源代码生成器和分析器的知识，相信此时大家也很想编写和发布一个自己的源代码生成器或分析器。按照 dotnet 里面的惯例，各种产物都会通过 NuGet 的形式进行发布，自然也包括源代码生成器和分析器。接下来我将和大家介绍如何将自己编写的源代码生成器分析器打包成 NuGet 包进行分发

和其他基础库的打包过程非常先进，单独分析器项目本身就可以打出 NuGet 包，只不过需要一些额外的配置。核心配置如下

    <!-- 
      配置为无依赖。即避免带上 TargetFramework=netstandard2.0 的限制
      配合 IncludeBuildOutput=false 即可让任意项目引用，无视目标框架
    -->
    <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>

    <!-- 不要将输出文件放入到 nuget 的 lib 文件夹下 -->
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <!-- 不要警告 lib 下没内容 -->
    <NoPackageAnalysis>true</NoPackageAnalysis>

其中核心为 IncludeBuildOutput 属性，表示不要将分析器输出程序集放入到 NuGet 包的 lib 文件夹下。一旦被放入到 NuGet 包的 lib 文件夹下，将会让安装了此 NuGet 包的项目引用了分析器程序集，而不会将分析器程序集作为分析器运行

现在如果就直接打出来 NuGet 包，则会看到 NuGet 包是一个空包，什么有用的内容都没有包含。这是因为分析器项目的输出程序集还没被作为分析器内容打入到 NuGet 包里面。再添加以下代码，将分析器项目的输出程序集放入到 NuGet 包的 analyzers/dotnet/cs 文件夹下，这样就可以让其他项目在安装到本 NuGet 包的时候，按照 NuGet 的约定，从 analyzers/dotnet/cs 文件夹里加载上分析器

  <Target Name="AddOutputDllToNuGetAnalyzerFolder" BeforeTargets="_GetPackageFiles">
    <!-- 
      以下这句 ItemGroup 不能放在 Target 外面。否则首次构建之前 $(OutputPath)\$(AssemblyName).dll 是不存在的
      这里需要选用在 _GetPackageFiles 之前，确保在 NuGet 收集文件之前，标记将输出的 dll 放入到 NuGet 的 analyzers 文件夹下
    -->
    <ItemGroup>
      <None Include="$(OutputPath)\$(AssemblyName).dll"
            Pack="true"
            PackagePath="analyzers/dotnet/cs"
            Visible="false" />
    </ItemGroup>
  </Target>

大家可以看到，这里使用了 BeforeTargets="_GetPackageFiles" 属性，表示在 NuGet 收集文件之前，将输出的 dll 放入到 NuGet 的 analyzers 文件夹下。为什么不能直接在 Project 下的一级 ItemGroup 里面添加呢？这是因为首次构建之前 $(OutputPath)\$(AssemblyName).dll 是不存在的，直接打包将会输出空包。于是选定在 Build 构建之后，收集文件之前的时机，此最佳时机就是在 _GetPackageFiles 之前

如果选用直接在 Project 下的一级 ItemGroup 里面添加 $(OutputPath)\$(AssemblyName).dll 则不能一次构建出包，此时最推荐的是先做一次 dotnet build 再做一次 dotnet pack --no-build 打包。由于这个命令过程需要拆分为两步，可能会漏掉导致行为不符合预期，因此我在本文里面就特意使用了 Target 的方式进行收集

如果大家对于在 csproj 里面编写 Target 等逻辑不熟悉，还请参阅如何编写基于 Microsoft.NET.Sdk 的跨平台的 MSBuild Target（附各种自带的 Task） - walterlv

整体修改之后的分析器项目的 csproj 项目文件内容大概如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
    <IsRoslynComponent>true</IsRoslynComponent>
    <Nullable>enable</Nullable>

    <Version>1.0.0</Version>
  </PropertyGroup>

  <PropertyGroup>
    <!-- [dotnet 打包 NuGet 的配置属性大全整理](/post/dotnet-%E6%89%93%E5%8C%85-NuGet-%E7%9A%84%E9%85%8D%E7%BD%AE%E5%B1%9E%E6%80%A7%E5%A4%A7%E5%85%A8%E6%95%B4%E7%90%86.html ) -->
    <Copyright>Copyright (c) lindexi 2020-$([System.DateTime]::Now.ToString(`yyyy`))</Copyright>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <Description>这里填写描述信息</Description>

    <!-- 
      配置为无依赖。即避免带上 TargetFramework=netstandard2.0 的限制
      配合 IncludeBuildOutput=false 即可让任意项目引用，无视目标框架
    -->
    <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>

    <!-- 不要将输出文件放入到 nuget 的 lib 文件夹下 -->
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <!-- 不要警告 lib 下没内容 -->
    <NoPackageAnalysis>true</NoPackageAnalysis>
  </PropertyGroup>
  <ItemGroup>
    <None Include="..\..\..\README.md" Link="README.md" Pack="True" PackagePath="\"/>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="dotnetCampus.LatestCSharpFeatures" Version="12.0.1" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.11.0" PrivateAssets="all" />
  </ItemGroup>

  <ItemGroup>
    <Compile Update="Properties\Resources.Designer.cs">
      <DesignTime>True</DesignTime>
      <AutoGen>True</AutoGen>
      <DependentUpon>Resources.resx</DependentUpon>
    </Compile>
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Update="Properties\Resources.resx">
      <Generator>ResXFileCodeGenerator</Generator>
      <LastGenOutput>Resources.Designer.cs</LastGenOutput>
    </EmbeddedResource>
  </ItemGroup>

  <Target Name="AddOutputDllToNuGetAnalyzerFolder" BeforeTargets="_GetPackageFiles">
    <!-- 
      以下这句 ItemGroup 不能放在 Target 外面。否则首次构建之前 $(OutputPath)\$(AssemblyName).dll 是不存在的
      这里需要选用在 _GetPackageFiles 之前，确保在 NuGet 收集文件之前，标记将输出的 dll 放入到 NuGet 的 analyzers 文件夹下
    -->
    <ItemGroup>
      <None Include="$(OutputPath)\$(AssemblyName).dll"
            Pack="true"
            PackagePath="analyzers/dotnet/cs"
            Visible="false" />
    </ItemGroup>
  </Target>
</Project>

第一个 PropertyGroup 块为分析器固有信息，其中的 <Version>1.0.0</Version> 版本号被程序集和 NuGet 包版本号所共用。如果只为指定 NuGet 的包版本号而不影响程序集的版本号，可使用专用的 PackageVersion 属性

第二个 PropertyGroup 块为 NuGet 包的信息。其中的 <Description>这里填写描述信息</Description> 为 NuGet 包的描述信息，这个描述信息可以在 NuGet Package Explorer 里面直接看到，如下图所示，直接使用 NuGet Package Explorer 打开 NuGet 包，即可看到描述信息

而 ReadMe 文件记录则是需要与下方的 <None Include="..\..\..\README.md" Link="README.md" Pack="True" PackagePath="\"/> 配合才能完成，用于放入识别的 README.md 文件，帮助开发者入门使用此分析器 NuGet 包

版权 Copyright 信息里面，我使用了 $([System.DateTime]::Now.ToString(yyyy)) 语法，用于获取当前年份。这样可以保证每年都会更新版权信息，不需要手动修改，只需要在新年的时候重新打包即可

再往下是 SuppressDependenciesWhenPacking 配置无依赖和 IncludeBuildOutput 配置不要将输出文件放入到 nuget 的 lib 文件夹等信息，这部分上文有描述，这里就不再赘述

以上内容里面用到了很多 NuGet 打包相关属性，如对此感兴趣，还请参阅 dotnet 打包 NuGet 的配置属性大全整理

如果大家打不出来正确的 NuGet 包，可以拉取我的代码进行对比参考

本章以上的代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 7ee17551c750a643593f6f5e4a0d03f89456b393

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 7ee17551c750a643593f6f5e4a0d03f89456b393

获取代码之后，进入 Roslyn/NayijainawNerkanekajawi 文件夹，即可获取到源代码

以上是十分简单地将分析器打成 NuGet 包。如编写一个禁用API调用的分析器演练章节中所述，在制作 NuGet 包的过程可以附带 props 文件和 targets 文件，用于在安装 NuGet 包的时候，自动添加一些配置。这样就可以让分析器的使用更加方便，不需要安装了分析器的项目手动添加配置

回顾一下原本在禁用API调用的分析器章节中的引用分析器的 NelbecarballReanallyerhohe 控制台项目的 csproj 文件内容

  <PropertyGroup>
    <BanAPIFileName>BanList.txt</BanAPIFileName>
  </PropertyGroup>

  <ItemGroup>
    <CompilerVisibleProperty Include="BanAPIFileName" />
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles Include="BanList.txt" />
  </ItemGroup>

以上内容里面的 <CompilerVisibleProperty Include="BanAPIFileName" /> 和 <AdditionalFiles Include="BanList.txt" /> 都是固定配置内容。完全可以放入到分析器 NuGet 包里面，不需要每个安装了分析器的项目都手动添加这些重复的配置内容

在分析器的 NuGet 包里面存放 props 文件和 targets 文件，将分析器所需配置放入到这两个文件里面，即可在安装完 NuGet 包之后，应用这两个文件里面的配置，避免安装分析器的项目需要添加固定配置内容

依然是为了方便大家获取源代码，我这里重新拷贝禁用API调用的分析器演练章节的项目里面的代码，重新新建了名为 JabeehuharKekajerlurlaw.Analyzer 的分析器项目和名为 JabeehuharKekajerlurlaw 控制台项目

首先在分析器项目里面新建一个名为 Assets 的文件夹。这个 Assets 文件夹名仅仅只是我的喜好，大家可以根据自己的喜好换成其他的文件夹名。再在 Assets 文件夹里面新建两个文件，分别是 Package.props 和 Package.targets 文件。这两个文件的内容如下

Package.props 文件内容如下

<Project>

</Project>

Package.targets 文件内容如下

<Project>

  <ItemGroup>
    <CompilerVisibleProperty Include="BanAPIFileName" />
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles Include="$(BanAPIFileName)" />
  </ItemGroup>
</Project>

针对上文的禁用API调用的分析器演练的需求，完全将配置的信息写入到 Package.targets 文件里面，确保顺序足够靠后，在对应的安装了分析器的项目里面完成配置之后，再设置加入到 AdditionalFiles 文件里面

完成 Package.props 和 Package.targets 文件的创建之后，将这两个文件按照 Roslyn 打包自定义的文件到 NuGet 包博客的方法，将这两个文件打包到 NuGet 包的 build 文件夹下

  <ItemGroup>
    <None Include="Assets\Package.targets" Pack="True" PackagePath="\build\$(PackageId).targets" />
    <None Include="Assets\Package.props" Pack="True" PackagePath="\build\$(PackageId).props" />
  </ItemGroup>

放入到 NuGet 包里面的 build 文件夹下，这样安装了分析器的项目就会自动引入这两个文件，依靠这两个文件提供的配置，不需要手动添加配置。以下是从原本项目引用方式分析器，更改为引用分析器 NuGet 包的方式之后，控制台项目的 csproj 文件里的配置内容发生的变更

原来的引用分析器项目：

  <PropertyGroup>
    <BanAPIFileName>BanList.txt</BanAPIFileName>
  </PropertyGroup>

  <ItemGroup>
    <CompilerVisibleProperty Include="BanAPIFileName" />
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles Include="BanList.txt" />
  </ItemGroup>

改用分析器 NuGet 包之后：

  <PropertyGroup>
    <BanAPIFileName>BanList.txt</BanAPIFileName>
  </PropertyGroup>

可以看到，引用分析器 NuGet 包之后，不需要再手动添加 <CompilerVisibleProperty Include="BanAPIFileName" /> 和 <AdditionalFiles Include="BanList.txt" /> 这两个配置内容，这两个配置内容已经被分析器 NuGet 包的 Package.targets 文件提供了。整个项目看起来更加简洁

以上在分析器 NuGet 包里面存放 props 和 targets 的全部项目代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin fb40665eacad9578d14bf799969bb0e9ac6f0b89

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin fb40665eacad9578d14bf799969bb0e9ac6f0b89

获取代码之后，进入 Roslyn/JabeehuharKekajerlurlaw 文件夹，即可获取到源代码

以上就是 dotnet 的源代码生成器、分析器的入门介绍，希望能够帮助大家更好的了解源代码生成器、分析器的使用方法。在使用过程中，可能以上介绍的内容还不够满足大家的需求。我将在下文给出一些常用方法，供大家参考

常用方法

以下是我记录的一些零碎的常用方法和做法，供大家参考，期望能够解决大家一些使用上的问题

获取配置

IIncrementalGenerator 增量 Source Generator 生成代码入门读取 csproj 项目文件的属性配置

Roslyn 分析器读取 csproj 项目文件的 AdditionalFiles Item 的 Metadata 配置

获取文件的实际本地路径

Roslyn 源代码生成器 SourceGenerator 获取代码文件的本地绝对路径

获取引用程序集的所有类型

IIncrementalGenerator 增量 Source Generator 生成代码入门获取引用程序集的所有类型

判断程序集之间的 InternalsVisibleTo 关系

IIncrementalGenerator 增量 Source Generator 生成代码入门判断程序集之间的 InternalsVisibleTo 关系

判断程序集的引用关系

IIncrementalGenerator 增量 Source Generator 生成代码入门判断程序集的引用关系

获取项目默认命名空间

IIncrementalGenerator 增量 Source Generator 生成代码入门获取项目默认命名空间

使用符号判断类型

在上文提到的类型判断方法里面，基本全是通过字符串判断的方式，比如在《分析使用了 CollectionAttribute 特性的分部方法》判断是否返回值类型是 System.Collections.Generic.IEnumerable 泛型类型时，就使用了如下的字符串判断方法

 var returnTypeName = methodSymbolReturnType.ToDisplayString(fullNameDisplayFormat);

 // 预期的返回值类型
 const string exceptedReturnTypeName = "global::System.Collections.Generic.IEnumerable";

 if (!string.Equals(returnTypeName, exceptedReturnTypeName, StringComparison.InvariantCulture))
 {
     return null;
 }

 if (methodSymbolReturnType.TypeArguments.Length != 1)
 {
     // 预期是 IEnumerable<Func> 这样的类型，在 IEnumerable 里面只有一个泛型参数
     return null;
 }

 // 取出 IEnumerable<Func<IContext, IFoo>> 中的 Func<IContext, IFoo> 部分
 if (methodSymbolReturnType.TypeArguments[0] is not INamedTypeSymbol funcTypeSymbol)
 {
     return null;
 }

字符串判断方法本身可以实现一些模糊判断效果，如采用 StartsWith 等方法进行不精确的判断。接下来将和大家介绍使用符号判断类型的方法，通过符号进行判断，可以实现十分精确的判断逻辑，这就意味着在上面代码里面的多个判断条件都可以合并为一个判断

先取出 System.Collections.Generic.IEnumerable 泛型类型，代码如下

 // 预期的返回值类型
 // 使用反引号 (`) 和泛型参数的数量在元数据中指定泛型类型。这就是为什么你在元数据名称中看不到“...IEnumerable<T>”的原因
 // [适用于 ImmutableArrays 的 Roslyn 分析器和代码感知库 - Microsoft Learn](https://learn.microsoft.com/zh-cn/visualstudio/extensibility/roslyn-analyzers-and-code-aware-library-for-immutablearrays?view=vs-2022 )
 const string exceptedReturnTypeName = "System.Collections.Generic.IEnumerable`1";

对比可以看出，去掉了 global:: 前缀，加上了反引号和泛型参数的数量

由于此基础类型必定存在，因此可以直接使用以下代码获取

GeneratorAttributeSyntaxContext syntaxContext = ...

// 此基础类型必定存在
INamedTypeSymbol symbolOfIEnumerable = syntaxContext.SemanticModel
    .Compilation
    .GetTypeByMetadataName(exceptedReturnTypeName)!;

获取类型之后，即可和方法返回类型进行对比判断是否相同。由于这里是两个泛型进行对比，需要获取方法返回值类型的 ConstructedFrom 属性，判断代码如下

 ITypeSymbol returnType = methodSymbol.ReturnType;
 // 这是一个泛型类型，我们需要获取泛型参数
 // 预期是 IEnumerable<Func<IContext, IFoo>> 这样的类型
 if (returnType is not INamedTypeSymbol methodSymbolReturnType)
 {
     return null;
 }

 // 此基础类型必定存在
 INamedTypeSymbol symbolOfIEnumerable = syntaxContext.SemanticModel
     .Compilation
     .GetTypeByMetadataName(exceptedReturnTypeName)!;

 var methodSymbolReturnTypeConstructedFrom = methodSymbolReturnType.ConstructedFrom;

 if (!symbolOfIEnumerable.Equals(methodSymbolReturnTypeConstructedFrom, SymbolEqualityComparer.Default))
 {
     return null;
 }

 // 通过以上的符号判断，以下几个判断都可不需要。如判断类型名、判断是否是泛型类型，判断泛型参数数量。这些全部包括在 System.Collections.Generic.IEnumerable`1 类型里面，只要类型符号判断相同，就等于这些条件满足
 //var returnTypeName = methodSymbolReturnType.ToDisplayString(fullNameDisplayFormat);
 //if (!string.Equals(returnTypeName, exceptedReturnTypeName, StringComparison.InvariantCulture))
 //{
 //    return null;
 //}

 //if (!methodSymbolReturnType.IsGenericType)
 //{
 //    // 不是泛型类型，不是我们想要的
 //    return null;
 //}

 //if (methodSymbolReturnType.TypeArguments.Length != 1)
 //{
 //    // 预期是 IEnumerable<Func> 这样的类型，在 IEnumerable 里面只有一个泛型参数
 //    return null;
 //}

也许有伙伴开始疑惑，为什么不能直接用 methodSymbolReturnType 做相等比较，而是需要取 ConstructedFrom 属性？这是因为 ConstructedFrom 属性是获取把当前“已构造”的泛型类型还原成“去掉自身类型实参”的那个泛型定义的符号，但保留外层已确定的封闭类型实参。这使你可以忽略本类型自己的类型参数替换结果，只比较它到底是哪一个泛型类型模板

以上代码的 GetTypeByMetadataName 拿到的是“泛型定义”符号（Definition），它不带具体类型实参。而实际代码的 IEnumerable<Func<IContext, IFoo>> 是一个“已构造”实例。自然两个符号是不相等的。通过 ConstructedFrom 把它还原为 IEnumerable<T> 类型符号，两者才语义等价，从而比较成功

以上代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 60954446bebcbc84cfa6e91cb8681b551ac60b93

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 60954446bebcbc84cfa6e91cb8681b551ac60b93

获取代码之后，进入 Roslyn/JicanerekeaFawbairbalbayhearwear 文件夹，即可获取到源代码

基础知识

参考文档

从零开始学习 dotnet 编译过程和 Roslyn 源码分析 - walterlv

手把手教你写 Roslyn 修改编译

Source Generators Cookbook

Source Generators

Incremental Generators

更多编译器、代码分析、代码生成相关博客，请参阅我的博客导航

WPF 从裸 Win 32 的 WM_Pointer 消息获取触摸点绘制笔迹

Tue, 07 Apr 2026 21:01:54 +0000

本文将告诉大家如何在 WPF 里面，接收裸 Win 32 的 WM_Pointer 消息，从消息里面获取触摸点信息，使用触摸点信息绘制简单的笔迹

开始之前必须说明的是使用本文的方法不会带来什么优势，既不能带来笔迹书写上的加速，也不能带来笔迹效果的平滑，且代码复杂。本文唯一的作用只是让大家了解一下基础机制

需要再次说明的是，在 WPF 里面，开启了 WM_Pointer 消息之后，通过 Touch 或 Stylus 事件收到的信息也是从 WM_Pointer 消息里面过来的。大家可以尝试在 Touch 事件监听函数添加断点，通过堆栈可以看到是从 Windows 消息循环来的

可以从调用堆栈看到如下函数，此函数就是核心的 WPF 框架里面从 WM_Pointer 消息获取触摸信息的代码

>	PresentationCore.dll!System.Windows.Interop.HwndPointerInputProvider.System.Windows.Interop.IStylusInputProvider.FilterMessage(nint hwnd, MS.Internal.Interop.WindowMessage msg, nint wParam, nint lParam, ref bool handled)

这个 FilterMessage 函数的大概代码如下

	nint IStylusInputProvider.FilterMessage(nint hwnd, WindowMessage msg, nint wParam, nint lParam, ref bool handled)
	{
		handled = false;
		if (PointerLogic.IsEnabled)
		{
			switch (msg)
			{
			case WindowMessage.WM_ENABLE:
				IsWindowEnabled = MS.Win32.NativeMethods.IntPtrToInt32(wParam) == 1;
				break;
			case WindowMessage.WM_POINTERENTER:
				handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.InRange, Environment.TickCount);
				break;
			case WindowMessage.WM_POINTERUPDATE:
				handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.Move, Environment.TickCount);
				break;
			case WindowMessage.WM_POINTERDOWN:
				handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.Down, Environment.TickCount);
				break;
			case WindowMessage.WM_POINTERUP:
				handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.Up, Environment.TickCount);
				break;
			case WindowMessage.WM_POINTERLEAVE:
				handled = ProcessMessage(GetPointerId(wParam), RawStylusActions.OutOfRange, Environment.TickCount);
				break;
			}
		}
		return IntPtr.Zero;
	}

由此可以了解到，使用本文自己从 Win32 消息获取的触摸信息，和从 WPF 提供的 Touch 或 Stylus 事件里面获取的触摸信息的来源是相同的

这时候也许有人会说，在 WPF 里面经过了一些封装，可能性能不如自己写的。我只想说，不要过于自信了哦。且别忘了消息是从 UI 线程里面获取的，无论你用不用 WPF 的事件，在 WPF 底层的解析消息获取触摸数据引发事件的代码都会跑，也就是无论你用不用，需要 WPF 干的活一点都没少。只有一个 UI 线程的情况下，如果用自己解析的，那还会多一点点处理逻辑，完全不如直接使用 WPF 的。再加上 WPF 的解析部分没有多少代码，如果有做性能分析的话，可以看到甚至做路由事件时的命中测试，判断命中到哪个控件和引发事件等逻辑的耗时远比解析来的多。且解析消息的数据耗时接近无法被直接测量出来，即测量所需时间大于解析的性能

科普就到这里，如果对 WPF 触摸相关感兴趣，请看 WPF 触摸相关

为了能够在消息里面收到 POINTER 消息，我根据 WPF dotnet core 如何开启 Pointer 消息的支持博客提供的方法，在 App 构造函数里面添加如下代码开启 Pointer 消息的支持。本文内容里面只给出关键代码片段，如需要全部的项目文件，可到本文末尾找到本文所有代码的下载方法

    public App()
    {
        AppContext.SetSwitch("Switch.System.Windows.Input.Stylus.EnablePointerSupport", true);
    }

接下来按照 WPF 如何确定应用程序开启了 Pointer 触摸消息的支持博客提供的方法添加消息监听处理逻辑，如以下代码

    public MainWindow()
    {
        InitializeComponent();

        SourceInitialized += OnSourceInitialized;
    }

    private void OnSourceInitialized(object? sender, EventArgs e)
    {
        var windowInteropHelper = new WindowInteropHelper(this);
        var hwnd = windowInteropHelper.Handle;

        HwndSource source = HwndSource.FromHwnd(hwnd)!;
        source.AddHook(Hook);
    }

    private unsafe IntPtr Hook(IntPtr hwnd, int msg, IntPtr wparam, IntPtr lparam, ref bool handled)
    {
        ... // 忽略其他代码
        return IntPtr.Zero;
    }

再定义上一些消息常量，然后跑起来代码确定 Pointer 消息开启成功

    private unsafe IntPtr Hook(IntPtr hwnd, int msg, IntPtr wparam, IntPtr lparam, ref bool handled)
    {
        const int WM_POINTERDOWN = 0x0246;
        const int WM_POINTERUPDATE = 0x0245;
        const int WM_POINTERUP = 0x0247;

        if (msg is WM_POINTERDOWN or WM_POINTERUPDATE or WM_POINTERUP)
        {
             // 在这里打断点，如果能进断点则证明 Pointer 消息开启成功
        }

        ... // 忽略其他代码
        return IntPtr.Zero;
    }

以下逻辑需要调用一些 Win32 的 API 函数，为了方便使用，根据 dotnet 使用 CsWin32 库简化 Win32 函数调用逻辑博客提供的方法，使用 CsWin32 库简化 Win32 函数调用逻辑，可以减少大量的 PInvoke 定义

可以避免定义错 PInvoke 函数导致的诡异失败

编辑 csproj 项目文件，替换为如下代码用于快速安装 CsWin32 库

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0-windows</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Windows.CsWin32" PrivateAssets="all" Version="0.3.106" />
  </ItemGroup>
</Project>

大家可以看到以上的项目文件代码的 OutputType 被我设置为 exe 类型，如此启动项目将会有默认的控制台，方便我在控制台输出内容

按照 dotnet 使用 CsWin32 库简化 Win32 函数调用逻辑博客提供的方法添加 NativeMethods.txt 文件，在此文件里面添加一些代码需要用到的 Win32 函数

GetPointerTouchInfo
ScreenToClient
RegisterTouchWindow
WM_TOUCH
GetTouchInputInfo
GetPointerDeviceRects
ClientToScreen

在 NativeMethods.txt 文件添加的是所需的 Win32 函数名，添加之后将会由 CsWin32 库使用源代码生成器方式生成对应的 PInvoke 代码和参数所需的类型，如结构体和枚举

根据 WPF 的源代码，先将消息过来的 wparam 转换为 pointerId 参数，代码如下

            var pointerId = (uint) (ToInt32(wparam) & 0xFFFF);
            PInvoke.GetPointerTouchInfo(pointerId, out var info);

这里需要额外说明的是这个 pointerId 参数不等于设备 Id 号，即如 WPF 的 TouchDevice.Id 等，这是不相同的，需要使用 GetPointerCursorId 进行关联才能拿到和 WPF 一样的值。但是使用 pointerId 参数去区分不同的触摸点还是可以的

如此即可拿到核心的 POINTER_INFO 结构体对象

            POINTER_INFO pointerInfo = info.pointerInfo;

简单处理的话，拿到的 pointerInfo 的 ptPixelLocation 字段就是当前触摸的坐标点了，采用的是像素坐标，使用屏幕坐标系

            var point = pointerInfo.ptPixelLocation;

从屏幕坐标系转换为 WPF 坐标系，代码如下

            PInvoke.ScreenToClient(new HWND(hwnd), ref point);

不考虑 DPI 的情况下，这样就可以使用了

按照 WPF 最简逻辑实现多指顺滑的笔迹书写博客提供的方法进行笔迹对接即可绘制出笔迹

这就是最简单的从 Win32 消息接收 Pointer 消息绘制笔迹的方法

然而以上的方法也存在不少的问题，比如忽略了 DPI 问题，以及精度问题。在大尺寸触摸屏上，直接使用 ptPixelLocation 字段将会画出锯齿的笔迹。如下图，黑色的线是直接使用 ptPixelLocation 字段收到的触摸点连接的折线

上图红色的曲线是使用 WPF 记一个特别简单的点集滤波平滑方法博客提供的方法进行平滑的笔迹线

在大屏触摸设备上，从硬件层面就有一层平滑算法了，但是受限于硬件的计算资源，只有简单的平滑。在 Windows 的 WISPTIS 模块里面，也会对触摸做一定的平滑算法，如丢弃某些过于离谱的触摸点。关于 Windows 上的 WISPTIS 模块的平滑算法属于我和系统软件，即软硬件工程师，进行合作测试出来的，他输入的点和我使用 BusHound 抓到得点和 WPF 层报告的点做对比，可以看到硬件层发送过来的点和 BusHound 抓到的相同，而和 WPF 层报告的点大部分情况下相同，只有某些点被丢弃。被丢弃的点是我这边设计的杂点。但是如果报告的触摸点，有瞬间飞到 0,0 点的情况，那这个 0,0 点则不会被丢弃

在 WPF 层上，从消息到 Touch 事件这里，是不会对点的坐标进行处理，不会执行平滑算法，最多只有做控件坐标转换。在 WPF 的 Ink 模块里面才会对输入的点做更进一步的平滑处理

我对比了从 Pointer 消息的 ptPixelLocation 字段收到的触摸点对接的 WPF 最简逻辑实现多指顺滑的笔迹书写博客提供的方法，和原始博客提供的程序，可以看到还是原来的笔迹更加顺滑

其核心原因在于 Pointer 消息的 ptPixelLocation 字段拿到的是丢失精度的点，像素为单位。如果在精度稍微高的触摸屏下，将会有明显的锯齿效果

如果想要获取比较高精度的触摸点，可以使用 ptHimetricLocationRaw 字段。这里需要对后缀 Raw 作出更多的说明，在微软官方文档里面说了不带 Raw 的是预测的值，即 ptPixelLocation 是预测的像素坐标点，而 ptPixelLocationRaw 是不带预测的像素坐标点。对于咱如果是使用在笔迹上，其实更应该使用的是 ptPixelLocationRaw 是不带预测的像素坐标点。否则预测效果可能会导致毛刺

使用 ptHimetricLocationRaw 字段会稍微复杂，由于 ptHimetricLocationRaw 采用的是 pointerDeviceRect 坐标系，需要转换到屏幕坐标系

转换方法就是先将 ptHimetricLocationRaw 的 X 坐标，压缩到 [0-1] 范围内，然后乘以 displayRect 的宽度，再加上 displayRect 的 left 值，即得到了屏幕坐标系的 X 坐标。压缩到 [0-1] 范围内的方法就是除以 pointerDeviceRect 的宽度。同理可以计算 Y 坐标

以上的 displayRect 和 pointerDeviceRect 需要使用 GetPointerDeviceRects 函数获取

            global::Windows.Win32.Foundation.RECT pointerDeviceRect = default;
            global::Windows.Win32.Foundation.RECT displayRect = default;

            PInvoke.GetPointerDeviceRects(pointerInfo.sourceDevice, &pointerDeviceRect, &displayRect);

以上代码用到了不安全代码，记得给 Hook 函数标记上 unsafe 作为不安全代码

根据上文提供的算法，编写如下代码将 ptHimetricLocationRaw 转换为 WPF 坐标系的点

            // 如果想要获取比较高精度的触摸点，可以使用 ptHimetricLocationRaw 字段
            // 由于 ptHimetricLocationRaw 采用的是 pointerDeviceRect 坐标系，需要转换到屏幕坐标系
            // 转换方法就是先将 ptHimetricLocationRaw 的 X 坐标，压缩到 [0-1] 范围内，然后乘以 displayRect 的宽度，再加上 displayRect 的 left 值，即得到了屏幕坐标系的 X 坐标。压缩到 [0-1] 范围内的方法就是除以 pointerDeviceRect 的宽度
            // 为什么需要加上 displayRect.left 的值？考虑多屏的情况，屏幕可能是副屏
            // Y 坐标同理
           var point2D = new Point2D(
                pointerInfo.ptHimetricLocationRaw.X / (double) pointerDeviceRect.Width * displayRect.Width +
                displayRect.left,
                pointerInfo.ptHimetricLocationRaw.Y / (double) pointerDeviceRect.Height * displayRect.Height +
                displayRect.top);

以上代码的 Point2D 类型的定义如下

readonly record struct Point2D(double X, double Y);

以上代码获取的是屏幕坐标系的点，需要转换到 WPF 坐标系

转换过程的两个重点：

1.底层 ClientToScreen 只支持整数类型，直接转换会丢失精度。即使是 WPF 封装的 PointFromScreen 或 PointToScreen 方法也会丢失精度

2.需要进行 DPI 换算，必须要求 DPI 感知

先测量窗口与屏幕的偏移量，这里直接取 0 0 点即可，因为这里获取到的是虚拟屏幕坐标系，不需要考虑多屏的情况

            var screenTranslate = new Point(0, 0);
            PInvoke.ClientToScreen(new HWND(hwnd), ref screenTranslate);

获取当前的 DPI 值

            var dpi = VisualTreeHelper.GetDpi(this);

先做平移，再做 DPI 换算

            point2D = new Point2D(point2D.X - screenTranslate.X, point2D.Y - screenTranslate.Y);
            point2D = new Point2D(point2D.X / dpi.DpiScaleX, point2D.Y / dpi.DpiScaleY);

此时拿到的 point2D 就是 WPF 坐标系的点了，但是拿这个点对接笔迹，如以下代码

            if (msg == WM_POINTERUPDATE)
            {
                var strokeVisual = GetStrokeVisual(pointerId);
                strokeVisual.Add(new StylusPoint(point2D.X, point2D.Y));
                strokeVisual.Redraw();
            }
            else if (msg == WM_POINTERUP)
            {
                StrokeVisualList.Remove(pointerId);
            }

运行代码即可看到可以在较高精度触摸屏上绘制出比较顺滑的笔迹

本文代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 322313ee55d0eeaae7148b24ca279e1df087871e

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 322313ee55d0eeaae7148b24ca279e1df087871e

获取代码之后，进入 WPFDemo/DefilireceHowemdalaqu 文件夹，即可获取到源代码

更多 WPF 触摸相关技术博客，请参阅博客导航

asp dotnet core 基于 TestServer 做集成测试

Tue, 07 Apr 2026 03:39:40 +0000

我有一个古老的 dotnet core 3.1 的 asp dotnet core 项目，现在我准备将他升级到 dotnet 5 了。但是我不想和博客园一样翻车，因此我需要做一点集成测试的辅助，尽管依然还是翻车了，但是我要学习博客园伟大的精神，将在这个项目里面所做的所有自动化测试项目的方法写下来

在开始从 dotnet core 3.1 升级到 dotnet 5 之前，我先开始准备集成测试。一开始准备的测试是开启主机，然后通过网络调用。然而这个方法一开启我就被拖出去了…… 因为开启主机会占用端口，而刚好我的几个项目都采用了相同的端口

而我开始尝试在配置文件里面指定随机的端口，而此时又有玄学的网络权限，但是我又不知道将谁拖出去

此时小伙伴给我安利了 TestServer 库，通过这个库可以不监听端口，全部都在内存中跑。当然了，访问外部服务就看注入了，没做注入也依然走网络的。只是自己的应用不会去监听端口而已

先新建一个项目，这是一个单元测试项目，用来做集成测试

在 dotnet 里面的套路就是先安装 NuGet 包，然后调用。安装的 NuGet 是 Microsoft.AspNetCore.TestHost 库。这个库一开始需要安装 3.1.10 的版本，在之后项目升级到 dotnet 5 才能使用最新的版本

        <PackageReference Include="Microsoft.AspNetCore.TestHost" Version="3.1.10" />

在我的单元测试项目里面全部安装的库如下

    <ItemGroup>
        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.8.0" />
        <PackageReference Include="MSTest.TestAdapter" Version="2.1.1" />
        <PackageReference Include="MSTest.TestFramework" Version="2.1.1" />
        <PackageReference Include="coverlet.collector" Version="1.3.0" />
        <PackageReference Include="Moq" Version="4.15.1" />
        <PackageReference Include="MSTest.TestAdapter" Version="2.1.2" />
        <PackageReference Include="MSTest.TestFramework" Version="2.1.2" />
        <PackageReference Include="MSTestEnhancer" Version="2.1.0" />
        <PackageReference Include="System.Text.Encoding.CodePages" Version="5.0.0" />
        <PackageReference Include="Microsoft.AspNetCore.TestHost" Version="3.1.10" />
    </ItemGroup>

如果是 .NET 5 的应用，那么 csproj 文件的代码大概如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>

    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.10.0" />
    <PackageReference Include="MSTest.TestAdapter" Version="2.2.4" />
    <PackageReference Include="MSTest.TestFramework" Version="2.2.4" />
    <PackageReference Include="coverlet.collector" Version="3.0.3">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
    <PackageReference Include="Moq" Version="4.16.1" />
    <PackageReference Include="MSTestEnhancer" Version="2.1.0" />
    <PackageReference Include="Microsoft.AspNetCore.TestHost" Version="5.0.7" />
  </ItemGroup>

</Project>

在使用 TestServer 进行集成测试的时候，其实就是将启动主机的逻辑替换掉，如 ASP.NET Core搭建多层网站架构【12-xUnit单元测试之集成测试】 - kasnti - 博客园这篇博客所说的方法，咱来新建一个静态类，用来创建主机和运行

    [TestClass]
    public static class TestHostBuild
    {
        public static HttpClient GetTestClient() => _host.GetTestClient();

        [AssemblyInitialize]
        public static async Task GlobalInitialize(TestContext testContext)
        {
            IHost host = await CreateAndRun();
            _host = host;
        }

        private static IHost _host;

        [AssemblyCleanup]
        public static void GlobalCleanup()
        {
            _host.Dispose();
        }

        private static Task<IHost> CreateAndRun() => CreateHostBuilder().StartAsync();

        public static IHostBuilder CreateHostBuilder() =>
            Host.CreateDefaultBuilder()
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                    webBuilder.UseTestServer(); //关键是多了这一行建立TestServer
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                	// 进行测试的配置
                    var appConfigurator = config.ToAppConfigurator();
                    // 这里使用了 https://github.com/dotnet-campus/dotnetCampus.Configurations 做配置
                    var apmConfiguration = appConfigurator.Of<ApmConfiguration>();
                    apmConfiguration.DisableApm = true;
                })
                // 使用 auto fac 代替默认的 IOC 容器 
                .UseServiceProviderFactory(new AutofacServiceProviderFactory());
               
    }

上面代码中的 CreateHostBuilder 和 asp dotnet core 项目的 Program.cs 的代码差不多，只是 ConfigureWebHostDefaults 方法更改了

而 ConfigureAppConfiguration 是进行配置，这里进行一些测试项目特意的配置，如禁用了我的 APM 服务。在做集成测试的时候，可以选择开启或关闭 APM 服务，如果你的运维小伙伴不会打你，那么还是开始 APM 比较好。这里的代码使用了 https://github.com/dotnet-campus/dotnetCampus.Configurations 的方法进行配置

在 MSTest 单元测试项目里面，使用 AssemblyInitialize 特性，可以让某个静态方法在单元测试启动的时候运行一次。而使用 AssemblyCleanup 方法可以在单元测试完成之后，无论是否成功都会调用一次

因此在 GlobalInitialize 方法标记 AssemblyInitialize 特性，在这里面创建主机然后运行主机。此时运行的主机不会去监听端口，因此不能通过端口的形式去调用他，而是需要使用 TestServer 提供的扩展方法获取 HttpClient 去访问。也就是通过 TestHostBuild.GetTestClient 拿到的才能访问这个在内存的主机

我对每个控制器都创建一个测试文件，用来进行单元测试

如我的项目里面有一个 StatusOverviewController 控制器，这个控制器用来返回服务的内容，大概逻辑如下

    [ApiController]
    [Route("[controller]")]
    [Route("/")]
    public class StatusOverviewController : ControllerBase
    {
    	[HttpGet]
        public string Get()
        {
        	// 也许使用 DateTimeOffset 更清真，但这又不是我写的
        	return DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss.fff");
        }
    }

新建一个单元测试来测试这个接口的访问

    [TestClass]
    public class StatusOverviewControllerTest
    {
        [TestMethod]
        public async Task GetTest()
        {
            using var httpClient = TestHostBuild.GetTestClient();

            var result = await httpClient.GetStringAsync("/");
            Assert.IsNotNull(result);
        }
    }

大概这样就能完成对这个接口的测试了

当然了这是对简单的接口可以这样写，但是对复杂的接口来说，有很多特殊的需求，此时就需要用到 CUnit 库了，通过安装 MSTestEnhancer 这个 NuGet 库就可以添加单元测试辅助库，如下面代码

        <PackageReference Include="MSTestEnhancer" Version="2.0.1" />

安装之后，就可以写入如下面的逻辑

[TestClass]
public class DemoTest
{
    [ContractTestCase]
    public void Foo()
    {
        "当满足 A 条件时，应该发生 A' 事。".Test(() =>
        {
            // Arrange
            // Action
            // Assert
        });
        
        "当满足 B 条件时，应该发生 B' 事。".Test(() =>
        {
            // Arrange
            // Action
            // Assert
        });
    }
}

这个 CUnit 在 GitHub 上完全开源，请看 https://github.com/dotnet-campus/CUnit

在准备好了集成测试项目之后，我就开始准备升级到 dotnet 5 了，然而此时发现构建服务器翻车了，如刚刚我从服务器回滚了 dotnet 5 的环境博客的内容

终于我通过如何给 CI CD 服务器搭建上 .NET 5 构建和运行环境的方法修好了

然而小伙伴告诉我从 dotnet core 3.1 到 dotnet 5 有如下的更改 Breaking changes, version 3.1 to 5.0 - .NET Core

在经过了两天的更新依然失败之后，我强行魔改了代码，上到了 dotet 5 之后，发现了 APM 挂了…… 因 APM 内部使用了原先 dotnet core 3.1 的在 dotnet 5 废弃的接口…… 然后就到了写博客时间了

更新，当使用 WebApplicationBuilder 时，应该取 WebApplicationBuilder 的 WebHost 属性调用 UseTestServer 方法，代码如下

        WebApplicationBuilder builder = WebApplication.CreateBuilder();
        builder.WebHost.UseTestServer();

实验豆包大模型录音文件识别带上下文识别功能

Tue, 07 Apr 2026 02:19:03 +0000

本文记录我实验豆包大模型录音文件识别带上下文识别功能

我这里使用的是豆包 ASR 新版控制台，地址是： https://console.volcengine.com/speech/new/experience/asr

使用新版控制台对接比较简单，只需要一个 X-Api-Key 即可

进入控制台开通「语音服务」的大模型ASR能力，拿到你的API Key记录起来。我这里存放到 C:\lindexi\Work\Speech.txt 文件里面

目前豆包提供两个版本的录音文件识别模型可选：

1.0版本：volc.bigasr.auc
2.0版本：volc.seedasr.auc（本次实验用的是2.0版本，识别准确率更高）

首先读取API Key，初始化HttpClient并配置公共请求头：

var keyFile = @"C:\lindexi\Work\Speech.txt";
var key = File.ReadAllText(keyFile).Trim();

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Key", key);
// 替换成你要使用的模型ID
var resourceId = "volc.seedasr.auc";
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Resource-Id", resourceId);

var requestId = Guid.NewGuid().ToString();
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Request-Id", requestId);
// 发包序号固定为-1即可
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Sequence", "-1");

你需要将上文代码中的文件路径换成你自己的API Key存储路径，也可以直接写配置、用环境变量等方式读取Key，相信这一步难不倒你。

接下来构造识别任务提交请求，核心是上下文热词配置，我们可以把业务里的专有名词、特定术语放在上下文里，大模型识别时会优先匹配这些内容：

var url = "https://openspeech.bytedance.com/api/v3/auc/bigmodel/submit";

// 构造上下文提示词，这里示例是告诉大模型当前设备安装的软件列表，识别语音的时候会优先匹配列表里的名称
var corpusContext = new CorpusContext()
{
    ContextData =
    {
        new CorpusContextData()
        {
            Text = "你是一个应用软件使用助手，你可以调用工具帮助用户实现电脑的操作",
        }, 
        new CorpusContextData()
        {
            Text = "现在电脑上安装的程序有：哔哩哔哩直播姬、软媒魔方、腾讯课堂、微软OfficePLUS、西娃白板、向日葵、小狼毫输入法、QQ影音。请选择将打开的应用程序",
        },
    }
};

var corpusContextJson = JsonSerializer.Serialize(corpusContext, new JsonSerializerOptions()
{
    WriteIndented = true,
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
});
var asrRequest = new AsrRequest()
{
    User = new UserMeta()
    {
        Uid = "abc"
    },
    Audio = new AudioMeta()
    {
        // 测试用的录音，内容是用户说“打开希沃白板”，可替换成你自己的音频地址
        Url = "https://pro-en-ali-pub.en5static.com/easinote5_public/uwixkwvzhhqjjhnohwvyzzwnykhhihhh.mp3",
        Format = "mp3",
    },
    Request = new RequestMeta()
    {
        ModelName = "bigmodel",
        Corpus = new CorpusMeta()
        {
            Context = corpusContextJson,
        }
    }
};

var jsonString = JsonSerializer.Serialize(asrRequest, new JsonSerializerOptions()
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
});

// 提交识别任务
using var httpResponseMessage =
    await httpClient.PostAsync(url, new StringContent(jsonString, Encoding.UTF8, "application/json"));
var responseText = await httpResponseMessage.Content.ReadAsStringAsync(); // 提交成功返回空内容

上面用到的CorpusContext、AsrRequest等实体类可以直接参考火山引擎语音服务的文档定义，详细定义的类型代码可到本文末尾找到本文的所有代码下载方法获取到

提交任务后需要轮询查询接口拉取识别结果：

var queryUrl = "https://openspeech.bytedance.com/api/v3/auc/bigmodel/query";

while (true)
{
    try
    {
        using var queryHttpResponseMessage =
            await httpClient.PostAsync(queryUrl, new StringContent("{}", Encoding.UTF8, "application/json"));
        var queryHttpResponseText = await queryHttpResponseMessage.Content.ReadAsStringAsync();

        string statusCodeText = string.Empty;
        if (queryHttpResponseMessage.Headers.TryGetValues("X-Api-Status-Code", out var statusCode) &&
            statusCode is string[] { Length: > 0 } codeArray)
        {
            statusCodeText = codeArray[0];
        }

        Console.WriteLine($"[{statusCodeText}] {queryHttpResponseText}");

        var speechRecognitionResponse = JsonSerializer.Deserialize<SpeechRecognitionResponse>(queryHttpResponseText);
        // 识别完成拿到结果就退出轮询
        if (!string.IsNullOrEmpty(speechRecognitionResponse?.Result?.Text))
        {
            break;
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(e);
    }
}

我用的测试录音是录音有两个，分别如下：

打开西瓜白板录音.mp3: https://pro-en-ali-pub.en5static.com/easinote5_public/uwixjonmhhqjjhnohwvvwyyhvzphihhh.mp3
- 会被识别为 “打开西瓜白榜”，但可以提示正为 “西瓜白板”，但就是很难被正确识别为 “希沃白板”
打开西wa白板录音.mp3: https://pro-en-ali-pub.en5static.com/easinote5_public/uwixkwvzhhqjjhnohwvyzzwnykhhihhh.mp3
- 可用提示词 “西娃白板” 或 “西喔白板” 来进行掰歪，但也可以用正确的 “希沃白板”定正

对比结果如下：

采用打开西wa白板录音.mp3 时， 没有加上下文的时候，识别结果完全跑偏：

{"audio_info":{"duration":4223},"result":{"additions":{"duration":"4223"},"text":"打开西瓜白榜。","utterances":[{"end_time":2890,"start_time":1450,"text":"打开西瓜白榜。","words":[{"confidence":0,"end_time":1690,"start_time":1450,"text":"打"},{"confidence":0,"end_time":1890,"start_time":1690,"text":"开"},{"confidence":0,"end_time":2170,"start_time":1930,"text":"西"},{"confidence":0,"end_time":2410,"start_time":2170,"text":"瓜"},{"confidence":0,"end_time":2610,"start_time":2570,"text":"白"},{"confidence":0,"end_time":2890,"start_time":2850,"text":"榜"}]}]}}

加了包含「西娃白板」的上下文之后，识别结果完全匹配提示内容：

[20000000] {"audio_info":{"duration":3455},"result":{"additions":{"duration":"3455"},"text":"打开西娃白板。","utterances":[{"end_time":2470,"start_time":1150,"text":"打开西娃白板。","words":[{"confidence":0,"end_time":1390,"start_time":1150,"text":"打"},{"confidence":0,"end_time":1550,"start_time":1390,"text":"开"},{"confidence":0,"end_time":1750,"start_time":1710,"text":"西"},{"confidence":0,"end_time":1950,"start_time":1910,"text":"娃"},{"confidence":0,"end_time":2310,"start_time":2110,"text":"白"},{"confidence":0,"end_time":2470,"start_time":2310,"text":"板"}]}]}}

同理如果你把上下文里的名称换成「西喔白板」或者正确的「希沃白板」，识别结果也会跟着对应调整，完全不需要额外训练模型，只要修改提示词就能适配不同业务场景，对于有大量专有名词的语音识别需求来说开发成本极低，日常做语音控制、录音转写之类的功能非常好用。

整个 Program.cs 代码如下

using System.Text;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.Json.Serialization;

using VolcEngineSdk.OpenSpeech.Contexts;

var keyFile = @"C:\lindexi\Work\Speech.txt";
var key = File.ReadAllText(keyFile).Trim();

/*
   豆包录音文件识别模型1.0
   - volc.bigasr.auc
   豆包录音文件识别模型2.0
   - volc.seedasr.auc
 */

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Key", key);
var resourceId = "volc.seedasr.auc";
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Resource-Id", resourceId);

var requestId = Guid.NewGuid().ToString();
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Request-Id", requestId);
// 发包序号，固定值，-1
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("X-Api-Sequence", "-1");

var url = "https://openspeech.bytedance.com/api/v3/auc/bigmodel/submit";

var corpusContext = new CorpusContext()
{
    ContextData =
    {
        new CorpusContextData()
        {
            Text = "你是一个应用软件使用助手，你可以调用工具帮助用户实现电脑的操作",
        }, 
        new CorpusContextData()
        {
            Text = "现在电脑上安装的程序有：哔哩哔哩直播姬、软媒魔方、腾讯课堂、微软OfficePLUS、西娃白板、向日葵、小狼毫输入法、QQ影音。请选择将打开的应用程序",
        },
    }
};

var corpusContextJson = JsonSerializer.Serialize(corpusContext, new JsonSerializerOptions()
{
    WriteIndented = true,
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
});
var asrRequest = new AsrRequest()
{
    User = new UserMeta()
    {
        Uid = "abc"
    },
    Audio = new AudioMeta()
    {
        // - 打开西瓜白板录音.mp3: https://pro-en-ali-pub.en5static.com/easinote5_public/uwixjonmhhqjjhnohwvvwyyhvzphihhh.mp3 会被识别为 “打开西瓜白榜”，但可以提示正为 “西瓜白板”，但就是很难被正确识别为 “希沃白板”
        // - 打开西wa白板录音.mp3: https://pro-en-ali-pub.en5static.com/easinote5_public/uwixkwvzhhqjjhnohwvyzzwnykhhihhh.mp3 可用提示词 “西娃白板” 或 “西喔白板” 来进行掰歪，但也可以用正确的 “希沃白板”定正

        Url = "https://pro-en-ali-pub.en5static.com/easinote5_public/uwixkwvzhhqjjhnohwvyzzwnykhhihhh.mp3",
        Format = "mp3",
    },
    Request = new RequestMeta()
    {
        ModelName = "bigmodel",
        Corpus = new CorpusMeta()
        {
            Context = corpusContextJson,
        }
    }
};

var jsonString = JsonSerializer.Serialize(asrRequest, new JsonSerializerOptions()
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
});

using var httpResponseMessage =
    await httpClient.PostAsync(url, new StringContent(jsonString, Encoding.UTF8, "application/json"));

var responseText = await httpResponseMessage.Content.ReadAsStringAsync();
_ = responseText; // 这是一个空内容

var queryUrl = "https://openspeech.bytedance.com/api/v3/auc/bigmodel/query";

while (true)
{
    try
    {
        using var queryHttpResponseMessage =
            await httpClient.PostAsync(queryUrl, new StringContent("{}", Encoding.UTF8, "application/json"));
        var queryHttpResponseText = await queryHttpResponseMessage.Content.ReadAsStringAsync();

        // {"audio_info":{"duration":4223},"result":{"additions":{"duration":"4223"},"text":"打开西瓜白榜。","utterances":[{"end_time":2890,"start_time":1450,"text":"打开西瓜白榜。","words":[{"confidence":0,"end_time":1690,"start_time":1450,"text":"打"},{"confidence":0,"end_time":1890,"start_time":1690,"text":"开"},{"confidence":0,"end_time":2170,"start_time":1930,"text":"西"},{"confidence":0,"end_time":2410,"start_time":2170,"text":"瓜"},{"confidence":0,"end_time":2610,"start_time":2570,"text":"白"},{"confidence":0,"end_time":2890,"start_time":2850,"text":"榜"}]}]}}
        string statusCodeText = string.Empty;
        if (queryHttpResponseMessage.Headers.TryGetValues("X-Api-Status-Code", out var statusCode) &&
            statusCode is string[]
            {
                Length: > 0
            } codeArray)
        {
            statusCodeText = codeArray[0];
        }

        Console.WriteLine($"[{statusCodeText}] {queryHttpResponseText}");

        var speechRecognitionResponse = JsonSerializer.Deserialize<SpeechRecognitionResponse>(queryHttpResponseText);
        if (!string.IsNullOrEmpty(speechRecognitionResponse?.Result?.Text))
        {
            break;
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(e);
    }
}

本文代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 0ac18baa912e060d79b4a10a5f77f0c432d954c4

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 0ac18baa912e060d79b4a10a5f77f0c432d954c4

获取代码之后，进入 SemanticKernelSamples/ChederehemculerlairLujurraqeldawjear 文件夹，即可获取到源代码

更多技术博客，请参阅博客导航

Avalonia 已知问题过早创建 App 对象将抛出 PlatformNotSupportedException 异常

Fri, 03 Apr 2026 23:11:22 +0000

本文记录 Avalonia 的一个已知问题，过早创建 App 对象将抛出 PlatformNotSupportedException 异常

此问题能够在 Avalonia 的 11.3 以及更早版本复现

只需要让 App 对象在 AppBuilder.Configure 委托之外创建，那么在调用 StartWithClassicDesktopLifetime 方法时，将在 Avalonia.Threading.Dispatcher.MainLoop 方法抛出异常

System.PlatformNotSupportedException: Operation is not supported on this platform.
   at Avalonia.Threading.Dispatcher.MainLoop(CancellationToken cancellationToken)
   at Avalonia.Controls.ApplicationLifetimes.ClassicDesktopStyleApplicationLifetime.StartCore(String[] args)
   at Avalonia.Controls.ApplicationLifetimes.ClassicDesktopStyleApplicationLifetime.Start(String[] args)
   at Avalonia.ClassicDesktopStyleApplicationLifetimeExtensions.StartWithClassicDesktopLifetime(AppBuilder builder, String[] args, Action`1 lifetimeBuilder)
   at RemhemlaidejeheWhahaheenalira.Program.Main(String[] args)

点进去 Dispatcher.MainLoop 看，可以发现进入了 _controlledImpl == null 的分支，如以下代码所示

	public void MainLoop(CancellationToken cancellationToken)
	{
		if (_controlledImpl == null)
		{
			throw new PlatformNotSupportedException();
		}
		DispatcherFrame frame = new DispatcherFrame();
		cancellationToken.Register(delegate
		{
			frame.Continue = false;
		});
		PushFrame(frame);
	}

大概问题原因就是因为 App 过早初始化，导致碰了静态的 Dispatcher.UIThread 属性，进而导致了 Dispatcher 过早初始化，导致 _controlledImpl 没有被初始化，这才导致出现此异常

public partial class Dispatcher : IDispatcher
{
    ...
    public static Dispatcher UIThread
    {
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        get
        {
            return s_uiThread ??= CreateUIThreadDispatcher();
        }
    }

    ...
}

我认为这是 Avalonia 的一个设计问题，但可以按照它现在的框架，也没有什么可以优化

本文代码放在 github 和 gitee 上，可以使用如下命令行拉取代码。我整个代码仓库比较庞大，使用以下命令行可以进行部分拉取，拉取速度比较快

先创建一个空文件夹，接着使用命令行 cd 命令进入此空文件夹，在命令行里面输入以下代码，即可获取到本文的代码

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 266f08d8df93a15051573c88676671d48136aeb0

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin 266f08d8df93a15051573c88676671d48136aeb0

获取代码之后，进入 AvaloniaIDemo/RemhemlaidejeheWhahaheenalira 文件夹，即可获取到源代码

更多技术博客，请参阅博客导航

林德熙

博客导航

技术交流群

dotnet 职业技术学院

CPF xamarin MAUI UNO 国产 UOS 开发

Microsoft.Maui.Graphics

WPF SharpDx Vortice

dotnet UNO

SkiaSharp

OpenTK

OpenXML Office 开发

Windows 定制

Roslyn

SemanticKernel

UWP WPF 开发交流群

其他博客发布平台

语言

dotnet

代码优化

基础库

.NET Framework

.NET Framework 与 .NET Core 差别

dotnet core 2

dotnet 5

dotnet 6

dotnet 7

dotnet 8

dotnet 9

序列化

XML

JSON

公共组件 CBB 建设

插件式开发

构建和打包

AOT

多线程和锁相关

多进程

多进程通讯

性能优化

网络

文件读写

平台调用

原理博客

设计规范

工具方法

已知问题

混淆

WMI

跨平台开发

UOS

麒麟

UNO

Avalonia

Avalonia 界面效果

Avalonia 渲染

Avalonia 已知问题

CPF

X11

X11 触摸相关

X11 多屏

数据库

WPF

WPF 应用开发

WPF 触摸相关

控件

自定义控件

控件库

布局

XAML

图片

文本

线程

窗口

渲染

视频

动画

平台调用

Win32

WinRT

WPF 基础 2D 图形学知识