PowerShell 的 COM 互操作引擎（ComInterop）：三方代码谱系、7.1 刷新流程与源码布局解析

本篇文章以 PowerShell 仓库中 engine/ComInterop/README.md 为核心，系统梳理该目录下 COM 互操作代码的来龙去脉：它源自 .NET 的哪三条代码谱系、在 PowerShell 7.1 中如何通过手工“三方对比（three-way comparison）”完成刷新并重新启用编译、以及目录/文件布局经历了怎样的增删与重构。读完你将理解 ComInterop 代码在 PowerShell 引擎中的接入方式与维护约束，并能对照仓库源码定位绑定、事件订阅等关键实现。

ComInterop 是什么：进入 PowerShell 的动态 COM 绑定层

在 PowerShell 中，用户可通过 New-Object -ComObject 创建 COM 对象，再以属性访问、方法调用、事件订阅等自然的脚本语法与之交互。这一能力依赖一套名为 ComInterop 的动态绑定代码：它把 COM 的 IDispatch 机制翻译为 .NET 的 DLR（Dynamic Language Runtime）绑定操作，从而让 PowerShell 脚本无需强类型封装即可驱动 COM 组件。

从仓库结构看，这套代码位于 src/System.Management.Automation/engine/ComInterop，且仅在 Windows 构建中参与编译：System.Management.Automation.csproj 中，当 '$(IsWindows)' != 'true' 时执行 <Compile Remove="engine\ComInterop\**\*.cs" />，与 engine\COM\**\*.cs 一并从非 Windows 构建中排除，这与 COM 互操作本身是 Windows 平台能力的前提一致。

在引擎侧，动态绑定器通过 ComBinder 接入 COM 对象。位于 engine/runtime/Binding/Binders.cs 的 PowerShell 各类 PS*Binder 会在目标对象是 RCW（Runtime Callable Wrapper）时，将操作委托给 System.Management.Automation.ComInterop.ComBinder：

• 读取索引：ComInterop.ComBinder.TryBindGetIndex（Binders.cs）
• 写入索引：TryBindSetIndex（同上文件 L4610）
• 读取属性/成员：TryBindGetMember（L5203）
• 写入属性：TryBindSetMember（L6089）
• 调用方法/带参属性：TryBindInvokeMember（L6684）

例如 ComInvokeAction.cs 中，FallbackInvoke 首先调用 ComBinder.TryBindInvoke；绑定失败时再走 errorSuggestion 或抛 NotSupportedException，从而在 PowerShell 脚本语义层与底层 COM 调用之间建立起清晰的降级链。

三条代码谱系：ComInterop 的“血脉”来源

README 明确指出：PowerShell 中随附的 ComInterop 代码源自 .NET 运行时仓库（dotnet/runtime），但经过了大量为适配 PowerShell 而做的重构工作。其参考代码共有三个来源：

1. .NET Framework 版本：最初来自 IronLanguages 项目的 ipy-2.7-maint 分支（Runtime/Microsoft.Dynamic/ComInterop），该代码于 2012 年被归档。这是历史最久的一条谱系，也是 Windows PowerShell 时代代码的基础。
2. .NET 5.0 版本：位于 .NET 5.0 的 Microsoft.CSharp 组件中（Microsoft/CSharp/RuntimeBinder/ComInterop），于 2020 年 5 月通过 PR 合并进入 .NET 5.0。它以 .NET Framework 版本为基础做了相当规模的重构（命名空间调整、清理死代码、拆分文件等）。
3. Windows PowerShell 遗留 ComInterop：位于本仓库 PowerShell v7.0.0 标签下的 src/System.Management.Automation/engine/ComInterop。它长期存在于仓库中但被排除出编译范围，同样基于 .NET Framework 版本，并带有大量为适配 Windows PowerShell 而做的重构。

也就是说，三条谱系同根同源（都源自 .NET Framework 的 ComInterop），但各自演进：谱系 1 是“原始基线”，谱系 2 代表 .NET 5.0 的现代化改造方向，谱系 3 代表 PowerShell 特有的集成改动。理解这一点是读懂后续“刷新”工作的前提。

代码刷新：PowerShell 7.1 中的手工三方对比迁移

README 记载，ComInterop 代码在 PowerShell 7.1（2020 年 8 月）被刷新并重新启用编译。这项工作完全是手工完成的，主要分三步：

1. 严谨的三方对比（three-way comparison）：
   • 用谱系 3（Windows PowerShell 遗留代码）对比谱系 1（.NET Framework），提取出“PowerShell 特有改动”；
   • 用谱系 2（.NET 5.0）对比谱系 1，提取出“.NET 5.0 带来的改动”。
2. 移植并再重构：把从谱系 3 提取出的 PowerShell 特有改动应用到谱系 2 的 .NET 5.0 代码上，过程中辅以必要的新一轮重构。
3. 复核评审：再次使用三方对比对应用到谱系 2 的新 PowerShell 改动做细致复查——将刷新后的 ComInterop 代码与谱系 3 对比得到差异，再逐一分析每个差异，确认其要么是“.NET 5.0 相对 .NET Framework 的纯粹改进”，要么是“应用 PowerShell 特有改动所必需的重构调整”。

这一流程的价值在于：通过两次两两对比确定改动归属，再通过一次差异审计确认“没有夹带私货”，从而在把代码库整体升级到 .NET 5.0 谱系的同时，完整保留下 PowerShell 所需的适配逻辑。

维护铁律：不破坏与上游的最小差异

README 有一段醒目的警告：

注意：除非是为了修复 Bug，否则不要修改 ComInterop 代码。我们希望在与 .NET 5.0 ComInterop 代码库对比时保持最小差异。

这条“最小 diff”约束不仅是文档口号，也在仓库中留下了具体痕迹。GlobalSuppressions.cs 中对 System.Management.Automation.ComInterop 命名空间下的 IDE0044: Add readonly modifier（Style 规则）做了全局抑制，其 Justification 正是“see src/System.Management.Automation/engine/ComInterop/README.md”。也就是说，为了不引入与上游不一致的无谓改动（如为每个字段加 readonly），代码库主动关闭了该命名空间的相应风格检查——这是“保持最小差异、便于日后与 .NET 上游对齐”策略的工程化落地。

代码布局变化：被移除的源文件

刷新后文件布局发生了显著变化。README 记录了在谱系 2（.NET 5.0）中被移除的、曾存在于谱系 1 与谱系 3 中的源文件：

ComDispIds.cs
ComEventSink.cs
ComEventSinkProxy.cs
ComParamDesc.cs
ComType.cs
ComTypeLibInfo.cs
ComTypeLibMemberDesc.cs
TypeLibInfoMetaObject.cs

README 说明，逐一检查后确认这主要是 .NET 5.0 做的**清理（clean-up）**工作，可细分为两类：

• 纯清理（代码无用/不再需要而被删除）：ComParamDesc.cs、ComType.cs、ComTypeLibInfo.cs、ComTypeLibMemberDesc.cs、TypeLibInfoMetaObject.cs 中的代码不再被使用或不再需要。
• 迁移/重构（代码被搬走或拆散到其他文件）：ComDispIds.cs、ComEventSink.cs、ComEventSinkProxy.cs 中的代码被移动到不同文件中，或以重构后的新形态存续（详见下文）。

一个值得注意的呼应点：作为“DISPID 常量”承载者的 ComDispIds.cs 虽在旧布局中消失，但同名内容并未丢失——在刷新后的 ComInterop.cs 中仍能看到 internal static class ComDispIds，定义了 DISPID_VALUE = 0、DISPID_PROPERTYPUT = -3、DISPID_NEWENUM = -4 等关键常量。这正好印证了 README 所说“被移动到不同文件中”的处理方式。

代码布局变化：新增文件与 InteropServices 命名空间

与删除相对的是新增与迁移。README 指出，部分源文件在 .NET 5.0 中被重构并移入 System.Runtime.InteropServices 命名空间（在 .NET 运行时仓库中位于 src/libraries/Common/src/System/Runtime/InteropServices）；在 PowerShell 仓库中，对应源文件被放置在 engine\ComInterop\InteropServices 目录下。

对照当前仓库目录 engine/ComInterop/InteropServices，可见 4 个文件：

InteropServices/
  ComEventsMethod.cs
  ComEventsSink.cs
  IDispatch.cs
  Variant.cs

此外，engine\ComInterop 根目录下的 ComEventsSink.Extended.cs 与 Variant.Extended.cs 是 .NET 5.0 中新增的文件。README 特别说明：

ComEventsSink.Extended.cs 与 Variant.Extended.cs（位于 engine\ComInterop），加上 engine\ComInterop\InteropServices 下的 ComEventsSink.cs 与 Variant.cs，共同构成了旧 .NET Framework 中 ComEventSink.cs、ComEventSinkProxy.cs、Variant.cs 三个文件的重构替代品。

也就是说，旧布局中“一个文件承担事件接收器 + 代理 + 变体全部职责”的做法，在新布局中被拆成了“基础类型（InteropServices，偏 .NET 5.0 上游）+ PowerShell 扩展（*.Extended.cs，位于 ComInterop 根目录）”的分层结构。从实现看，ComEventsSink.Extended.cs 正是 System.Management.Automation.InteropServices.ComEventsSink 的 partial 扩展部分，其 AddHandler/RemoveHandler 会把 PowerShell 脚本块通过 SplatCallSite 包装成委托后按 dispid 注册到 ComEventsMethod 上，体现了“上游通用机制 + PowerShell 特有桥接”的分工。

源码佐证：绑定与 COM 事件处理的核心链路

作为对 README 所述内容的延伸，仓库源码可以进一步印证 ComInterop 的实现层次：

1. IDispatch 接口声明与类型描述缓存。 ComInterop.cs 用 [ComImport] 声明了标准 IDispatch 接口（GUID 00020400-0000-0000-C000-000000000046，IUnknown 布局、PreserveSig 方法），以及 IProvideClassInfo（GUID B196B283-BAB4-101A-B69C-00AA00341D07）。这些 COM 层面最小的互操作定义是上层所有动态绑定行为的基石。

2. 成员访问的语义判定。 IDispatchComObject.cs 的类注释详细解释了其设计挑战：IDispatch 本身无法区分“零参数方法”与“属性”，因此需要借助 ITypeInfo 判断方法参数、属性、默认属性与枚举行为。同时该注释完整描述了事件订阅链路：COM 对象通过 Connect Points 机制发布事件；当 TryGetMember 请求某成员且判定为事件时，返回 BoundDispEvent 实例，其 InPlaceAdd 运算符会：创建 ComEventSinksContainer 并把事件接收器生命周期绑定到 RCW；按源接口创建并 advise ComEventSink；ComEventSink 内部维护 DISPID 到多播委托的映射，并通过实现 IReflect 拦截 IDispatch.Invoke 来分发事件。整条链路对应文件中 IDispatchComObject、ComTypeDesc 类型缓存（s_cacheComTypeDesc）等实现。

3. PowerShell 侧测试与基准。 COM 能力在仓库测试中有直接覆盖，例如 New-Object.Tests.ps1 会按平台断言 ComObject 参数是否存在，并用 New-Object -ComObject 'doesnotexist' 验证报错行为；Scripting 基准 也以 New-Object -ComObject Shell.Application、scripting.filesystemobject 等脚本度量引擎调用方法的性能。这些用例从功能与性能两个维度，为刷新后的 ComInterop 提供了回归验证的入口。

小结

PowerShell 的 ComInterop 是一个“舶来后深度定制”的经典案例：它以 .NET Framework 谱系为基线，跟随 .NET 5.0 完成了大规模清理与命名空间重构（移除 8 个旧文件、新增 InteropServices 子目录与 *.Extended.cs 拆分），同时通过 7.1 时代的精细三方对比，把 Windows PowerShell 的特有改动无损迁移到新基线上，最终在 Windows 构建中重新启用编译。对维护者而言，engine/ComInterop/README.md 既是这份工作的完整记录，也是“修复 Bug 而非重构、保持与上游最小 diff”这一长期维护契约的权威说明。