企业官网建设流程全解析

• 后端

本文是 Rx.NET 内置 Roslyn 分析器System.Reactive.Analyzers的规则使用指南。文章以仓库中的规则清单 AnalyzerReleases.Unshipped.md 为骨架，结合 AddUiFrameworkPackageAnalyzer.cs 等源码实现，系统讲解 RXNET0001 至 RXNET0004 四条诊断规则的触发场景、检测机制、消息内容与修复方法。读完本文，你将能理解 Rx 7.0 包拆分背景下这些警告为何出现、如何精准识别"因缺少 UI 框架专用 NuGet 包引用而导致的编译错误"，并掌握正确的升级修复路径。

一、规则清单：四条未发布（Unshipped）诊断规则

System.Reactive.Analyzers项目采用 Roslyn 官方的 ReleaseTracking 机制管理诊断规则的发布状态，规则清单保存在两个文件中：

• AnalyzerReleases.Unshipped.md：记录尚未随正式版本发布的新规则；
• AnalyzerReleases.Shipped.md：记录已经发布的规则，当前内容为空（仅有文件头注释），说明 RXNET0001 至 RXNET0004 是该分析器的第一批新规则，尚未随任何正式 NuGet 版本发布。

Unshipped 清单中登记的四条规则如下：

四条规则全部由同一个分析器类 AddUiFrameworkPackageAnalyzer.cs 产生，Category 均为NuGet，Severity 均为Warning，并且默认启用（isEnabledByDefault: true）。它们分别对应四个 UI 框架专用包：System.Reactive.WindowsForms、System.Reactive.Wpf、System.Reactive.WindowsRuntime与System.Reactive.Uwp。

二、背景：为什么 Rx 7.0 需要这样一个分析器

要理解这四条规则的价值，必须先了解 Rx 7.0 的包拆分决策。在 Rx 7 之前，System.Reactive一个包承载了所有 UI 框架集成代码：WPF 的DispatcherScheduler、Windows Forms 的ControlScheduler、WinRT 的CoreDispatcherScheduler与IEventPatternSource<TSender, TEventArgs>、UWP 的DependencyObject调度支持等全部混在主包中。

这带来一个严重问题：任何目标框架为 Windows 特定 TFM（如net8.0-windows10.0.19041）且引用System.Reactive的应用，无论是否使用 WPF/WinForms，都会被强制引入Microsoft.Desktop.App框架依赖。对于自包含（self-contained）部署，这一依赖会把部署体积从约 90MB 推高到 182MB；即便配合裁剪，也会带来约 47MB 的额外体积（详见 ADR 0005：Moving UI framework support out ofSystem.Reactive中的实测数据）。

Rx 7.0 的解决方案是：

1. UI 框架专用代码从System.Reactive的公共 API（ref 程序集）中移除，但保留在运行时程序集（lib）中，以维持二进制兼容；
2. 需要继续使用这些类型和方法的代码，必须显式引用新的 UI 框架专用包；
3. System.Reactive包本身不再强制引入Microsoft.Desktop.App依赖。

正如 Rx.v7.md 所述，这一改动属于"源码级破坏性变更，而非二进制级破坏性变更"——升级后旧代码会突然出现难以理解的编译错误，而分析器正是为了在这种情况下"指引开发者找到正确的补救方向"而存在。源码注释（AddUiFrameworkPackageAnalyzer.cs 第 34-39 行）明确说明了设计初衷：升级到 Rx 7 时最可能遇到的摩擦点，就是原本在 Rx 6 及更早版本中编译通过的 UI 框架代码突然报错，且错误信息往往不会直接告诉开发者该引用哪个新包。

三、分析器的运行机制：只在编译出错时才介入

与大多数持续扫描语法节点的分析器不同，AddUiFrameworkPackageAnalyzer采用"问题驱动"的极简设计。从源码（AddUiFrameworkPackageAnalyzer.cs）可以看到其核心流程：

public override void Initialize(AnalysisContext context) { if (context is null) { throw new ArgumentNullException(nameof(context)); } context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None); context.EnableConcurrentExecution(); context.RegisterSemanticModelAction(AnalyzeSemanticModel); } private void AnalyzeSemanticModel(SemanticModelAnalysisContext context) { // 只遍历编译器已经报告的 Error 级别诊断 var d = context.SemanticModel.GetDiagnostics(); foreach (var diag in d) { if (diag.Severity != DiagnosticSeverity.Error) { continue; } var node = diag.Location.SourceTree?.GetRoot().FindNode(diag.Location.SourceSpan); if (!UiFrameworkSpecificTypes.Check(context, node, diag)) { UiFrameworkSpecificExtensionMethods.CheckForExtensionMethods(context, node, diag); } } }

关键设计决策：

• 注册的是RegisterSemanticModelAction，而非语法节点回调。因为分析器只希望在已经存在编译错误的代码上运行，正常情况下绝大多数编译是不需要介入的，这样可以最大限度降低对构建性能的影响；
• 只处理Error级别的编译器诊断（如 CS0234、CS0246、CS0103、CS1061、CS1503 等），其余严重级别直接跳过；
• 分析器自身产生的诊断会被叠加在原始编译错误的位置上（Diagnostic.Create(d, diag.Location, ...)），即在报错处额外追加一条 RXNET 警告，帮助开发者理解错误的根因；
• 项目启用并发执行（EnableConcurrentExecution）并跳过生成代码（GeneratedCodeAnalysisFlags.None）。

需要特别注意的是，该分析器不检测 VB.NET，源码中以TODO: VB.NET?明确标注了这一点（AddUiFrameworkPackageAnalyzer.cs 第 52 行），并在[DiagnosticAnalyzer(LanguageNames.CSharp)]上限定仅作用于 C#。

四、RXNET 规则与已移动类型的映射关系

分析器维护了一张"已移动类型"清单（UiFrameworkSpecificTypes.cs 第 65-75 行），把旧包中的类型精确映射到对应的 RXNET 规则：

其中IEventPatternSource比较特殊：它要求两个类型参数（TSender、TEventArgs），在诊断消息中会显示为全名IEventPatternSource<TSender, TEventArgs>，避免与主库中单参数的IEventPatternSource<TEventArgs>混淆。源码注释指出这是一个"awkward case"——编译器可能误以为代码写错了类型参数个数，而真实原因其实是IEventPatternSource<TSender, TEventArgs>这个双参数类型已移入System.Reactive.WindowsRuntime包。

五、RXNET 规则与已移动扩展方法的映射关系

除类型外，分析器还维护了一张更庞大的"已移动扩展方法"表（UiFrameworkSpecificExtensionMethods.cs 第 27-90 行），涵盖ObserveOn、SubscribeOn、ObserveOnDispatcher、SubscribeOnDispatcher、ObserveOnCoreDispatcher、SubscribeOnCoreDispatcher、ToObservable、ToObservableProgress、ToObservableMultiple、ToEventPattern等方法的数十个重载。典型映射关系：

RXNET0001（Windows Forms，目标包System.Reactive.WindowsForms）

• ObserveOn(System.Windows.Forms.Control)
• SubscribeOn(System.Windows.Forms.Control)

RXNET0002（WPF，目标包System.Reactive.Wpf）

• ObserveOn(Dispatcher)/ObserveOn(Dispatcher, DispatcherPriority)
• ObserveOn(DispatcherObject)/ObserveOn(DispatcherObject, DispatcherPriority)
• SubscribeOn(Dispatcher)/SubscribeOn(Dispatcher, DispatcherPriority)等
• ObserveOnDispatcher()/SubscribeOnDispatcher()

RXNET0003（Windows Runtime，目标包System.Reactive.WindowsRuntime）

• ObserveOn(CoreDispatcher)/SubscribeOn(CoreDispatcher)等
• ObserveOnCoreDispatcher()/SubscribeOnCoreDispatcher()
• IAsyncAction/IAsyncOperation系列的ToObservable/ToObservableProgress/ToObservableMultiple
• IObservable<EventPattern<TSender, TEventArgs>>上的ToEventPattern()

RXNET0004（UWP，目标包System.Reactive.Uwp）

• ObserveOn(Windows.UI.Xaml.DependencyObject)/ObserveOn(DependencyObject, CoreDispatcherPriority)
• SubscribeOn(Windows.UI.Xaml.DependencyObject)系列

设计上还特意不检测WindowsObservable.StandardSequenceOperators中四个带Func<TArg, TResult>参数的SelectMany重载（源码第 71-89 行的注释说明了原因）：因为表驱动的检测机制无法只凭参数类型Func<TArg, TResult>判断返回类型是否为IAsyncOperation<T>，强行检测会引入误报；而实际项目中只使用这些重载、不使用其他 Windows Runtime 功能的场景极为罕见——一旦开发者添加包引用，其他检测点会先于这些场景给出提示。

六、消息内容：警告文本与资源定义

四条规则的标题、描述与消息格式全部定义在 Resources.resx 中，通过LocalizableResourceString在分析器中加载，保证多语言可本地化。以 RXNET0001 为例：

• 标题："Rx.NET Windows Forms support is now in System.Reactive.WindowsForms"
• 消息格式：The '{0}' {1} has moved. Add a reference to the System.Reactive.WindowsForms NuGet package.
• 描述："Add a reference to the System.Reactive.WindowsForms NuGet Package to continue using Rx.NET Windows Forms support."

其中{0}是具体类型或方法名（如ControlScheduler或ObserveOn(Control)），{1}是type或extension method占位符（定义于 Resources.resx 中的TypeText与ExtensionMethodText）。四条规则的消息模板结构完全一致，仅目标包名不同：

• RXNET0002 →System.Reactive.Wpf
• RXNET0003 →System.Reactive.WindowsRuntime
• RXNET0004 →System.Reactive.Uwp

各规则的helpLinkUri统一指向https://github.com/dotnet/reactive（即当前仓库的上游地址），帮助开发者跳转查看项目主页与发布历史。

七、防误报策略：语法检测与语义验证的结合

分析器的一个核心难点在于：它必须在编译器无法解析类型的情况下工作（因为要检测的正是"已消失"的类型）。因此 UiFrameworkSpecificTypes.cs 采用"几乎完全基于语法"的策略，同时通过语义模型验证来规避误报：

1. 命名空间限定名匹配：如果代码写出了完整的System.Reactive.Concurrency.DispatcherScheduler这类限定名，直接按命名空间 + 简单名 + 泛型元数精确匹配；
2. 非限定名匹配：对只写简单名（如DispatcherScheduler）的情况，先确认编译器确实无法解析该符号的类型（ti.Type is null || ti.Type.TypeKind == TypeKind.Error），再检查相关命名空间是否通过using导入（GetImportScopes+Imports检查）。这样即使项目中碰巧存在一个同名但属于其他命名空间的类型，也不会误报；
3. 成员访问表达式匹配：对System.Reactive.Concurrency.ControlScheduler.Current这类调用，检查成员访问表达式的接收者文本是否就是目标命名空间，并确认语义模型无法解析该成员类型；
4. 扩展方法参数匹配：扩展方法检测在 UiFrameworkSpecificExtensionMethods.cs 中通过表驱动实现，需要满足：方法名匹配、参数个数匹配、接收者类型是IObservable<T>（通过 CodeAnalysisExtensions.cs 的IsIObservable等匹配器）、所有参数类型已知且可继承自目标参数类型。

源码注释（第 19-30 行）强调了两条设计红线：避免误报和在不会产出诊断的场景避免开销——因为在开发者修复包引用之后，该分析器仍会随每次编译错误被触发，必须能快速判断"无需干预"并退出。

八、测试验证：行为即规格

仓库为每条规则都配备了专门的测试类（位于 System.Reactive.Analyzers.Test 目录）：

• WindowsFormsSchedulerNewPackageAnalyzerTests.cs：验证ControlScheduler在完全限定名、using导入、嵌套命名空间、变量声明、字段/属性/返回类型等十余种写法下均能触发 RXNET0001；
• WpfExtensionsNewPackageAnalyzerTests.cs：验证ObserveOn/SubscribeOn系列重载触发 RXNET0002，包括Dispatcher、DispatcherObject及其派生类型（如System.Windows.Controls.Button作为DispatcherObject子类也能被识别）等各种参数组合；
• UapNewPackageAnalyzerTests.cs：在 UAP 参考程序集环境下验证DependencyObject相关调用触发 RXNET0004；
• 另有 WindowsRuntimeSchedulerNewPackageAnalyzerTest.cs、WindowsRuntimeTypesNewPackageAnalyzerTest.cs、WindowsRuntimeExtensionsNewPackageAnalyzerTests.cs、WindowsFormsExtensionsNewPackageAnalyzerTests.cs 分别覆盖 RXNET0003 与 RXNET0001 的扩展方法场景。

测试用例同时验证了分析器对底层编译器错误码（如 CS0234、CS0246、CS0103、CS1061、CS1503）的适配，例如：对于主库中已有同名方法的ObserveOn(Dispatcher)重载，编译器会误判为"参数类型错误"（CS1503，诊断落在参数节点上）；而对于主库中不存在的ObserveOnDispatcher()，编译器会报告"方法不存在"（CS1061，诊断落在调用节点上）。分析器分别处理这两种情况，详见 UiFrameworkSpecificExtensionMethods.cs 第 122-152 行。

九、使用与修复：从警告到正确配置

9.1 如何启用

分析器项目本身构建为netstandard2.0程序集，依赖Microsoft.CodeAnalysis.CSharp4.12.0，并启用了EnforceExtendedAnalyzerRules（见 System.Reactive.Analyzers.csproj）。当System.Reactive.Analyzers以 NuGet 分析器（或随System.Reactive包以分析器方式）进入项目后，四条规则默认启用，无需额外配置；若需临时关闭，可在.editorconfig或GlobalAnalyzerConfig中按规则 ID 设置严重级别，例如：

dotnet_diagnostic.RXNET0002.severity = none

9.2 典型修复路径

当编译器错误伴随 RXNET 警告出现时，修复方式非常直接：为项目添加对应 UI 框架专用包的引用。映射关系如下：

以 Windows Forms 项目为例，升级到 Rx 7 后应在项目文件中加入：

<ItemGroup> <PackageReference Include="System.Reactive.WindowsForms" Version="7.0.0" /> </ItemGroup>

此外还有一个连带配置点：Rx 7 中System.Reactive不再自动带来Microsoft.Desktop.App框架引用，如果应用本身确实依赖 WPF 或 Windows Forms 框架，需要在项目文件中显式声明（Rx.v7.md 第 19 行）：

<PropertyGroup> <UseWPF>true</UseWPF> <!-- 或 <UseWindowsForms>true</UseWindowsForms> --> </PropertyGroup>

9.3 一个已知的特殊场景

WpfExtensionsNewPackageAnalyzerTests.cs 的文档注释描述了一个罕见的边界场景：如果一个针对 Rx 6 编译的库公开了DispatcherScheduler类型的静态属性，而应用升级到 Rx 7 后不添加System.Reactive.Wpf引用，那么读取该属性的表达式会触发编译错误，且仅添加 WPF 包也无法解决——因为运行时System.Reactive.dll中的DispatcherScheduler与System.Reactive.Wpf.dll中的同名类型被视为不同程序集中的不同类型。该场景的变通方案是：用PackageDownload替换PackageReference并让编译器直接引用运行时程序集（lib\net8.0-windows10.0.19401\System.Reactive.dll），以重新获得那些被隐藏的 UI 类型。分析器目前刻意不为这种极少数场景产出诊断（因为难以在一条消息里解释清楚），测试注释也呼吁遇到此问题的开发者反馈给上游。

十、小结

System.Reactive.Analyzers的 RXNET0001 至 RXNET0004 四条规则，是 Rx.NET 为化解 7.0 版本包拆分这一"源码级破坏性变更"而提供的贴心向导：它只在实际编译错误出现时介入，通过语法与语义结合的方式精准识别已移出System.Reactive公共 API 的类型与扩展方法，并直接告诉开发者该引用哪个新的 UI 框架专用包。从 AnalyzerReleases.Unshipped.md 的规则登记，到 Resources.resx 的消息文本，再到 System.Reactive.Analyzers.Test 目录下覆盖各平台各写法的测试矩阵，仓库完整展示了从问题背景（见 ADR 0005 与 Rx.v7.md）、规则设计到自动化验证的全链路。对于正从 Rx 6 及更早版本升级的开发者，理解并善用这四条规则，可以显著降低"编译突然失败却不知所以然"的升级摩擦。

• 后端