Netwright

Netwright

面向 .NET 桌面应用的 Playwright 风格自动化。 Netwright 是一个 MCP 服务，可让 AI Agent 查看和操作 WPF、WinForms 和 WinUI 应用：它们启动你的项目，以精简文本读取 UI，在不抢占鼠标的情况下执行操作，验证结果，并将已验证的流程转化为回归测试。

▶ 观看带声音的演示

前身为 WPF-MCP。2.0 版进行了重写；请参阅 从 WPF-MCP 1.x 迁移。

> desktop_app action=launch project=src/Orders/Orders.csproj
Launched Orders.exe (pid 9120, WPF, launched by Netwright)
- window "Orders" [e1]

> desktop_snapshot
- window "Orders" [e1]
  - textbox "Customer" [e4] #txtCustomer
  - combobox "Country" [e5] #cmbCountry collapsed
  - checkbox "Accept terms" [e6] #chkTerms unchecked
  - button "Save" [e7] #btnSave disabled

> desktop_set_state target=#chkTerms checked=true
checked checkbox "Accept terms" [e6] #chkTerms
~ checkbox "Accept terms" [e6] #chkTerms checked
~ button "Save" [e7] #btnSave

> desktop_click target=#btnSave
clicked button "Save" [e7] #btnSave
+ window "Confirm" [e9] modal
  + text "Save order 42?"
  + button "Yes" [e10]

为什么选择 Netwright

• 专为 .NET 应用打造。 通过 UI Automation 支持 WPF、WinForms（.NET 和 .NET Framework 4.x）以及 WinUI/MAUI。它直接从 .csproj 启动应用，捕获 stdout/stderr 和 Trace 输出，并报告包含异常和堆栈跟踪的崩溃信息。
• 节省 token。
  • 快照经过筛选，只保留 Agent 所需内容：折叠未命名的布局窗格，并按行汇总网格。
  • 操作会返回变更报告，说明哪些内容出现、消失或发生变化，因此 Agent 很少需要再次获取快照。
  • 引用（e12）在不同快照之间仍然有效。
• 不打扰你的工作。 操作在后台运行：对于由 Netwright 启动的应用，一个小型伴随程序会在应用内部执行操作，因此应用不会进入前台，绑定字段也会像真实编辑一样提交。你可以继续工作，同时让 Agent 进行测试。按键和右键操作会明确执行，短暂获取焦点后再将焦点还给你。
• 默认可靠。
  • 每项操作都会等待目标启用并显示在屏幕上。
  • 随后会等待 UI 稳定下来，因此异步屏幕无需使用休眠等待。
  • 失败会以错误代码返回，并附带下一步操作提示。
• 从探索到回归测试。 desktop_expect 用于验证状态，desktop_export_test 可将会话转化为基于 Netwright.Testing 的 C# 测试（xUnit、NUnit 或 MSTest）。

基准测试

所有 MCP 服务使用相同场景、相同 Fixture App 和相同 token 编码（完整方法和所有数据见 benchmarks/results）：

WPF Fixture App，5 次运行的中位数	WPF-MCP 1.0	FlaUI-MCP	Windows-MCP	Netwright 2.0
每轮发送的工具定义（tokens）	2,023（24 个工具）	1,418（12 个）	3,984（20 个）	1,387（15 个）
表单快照（tokens）	1,023	785	1,956¹	385
1000 行网格快照（tokens）	3,988	6,234	1,897¹	627
填写并提交表单：调用次数 / tokens	10 / 2,463	10 / 3,469	–²	6 / 549
同一表单在 WinForms 上的成功次数	0/5	0/5	–²	5/5
等待异步加载：调用次数 / tokens	5 / 3,337	5 / 2,484	–²	3 / 405
屏幕截图（tokens）	25,073	1,000	1,944	1,020
含 1000 行未虚拟化数据的 WinForms 网格：快照耗时	9.2 s	12.9 s	0.3 s¹	1.5 s

¹ Windows-MCP 汇总的是整个桌面，而不是应用的 UI 树；其网格快照不包含网格行。² 它通过真实鼠标在屏幕坐标处执行操作，因此未运行脚本化流程。

tokens 使用 o200k_base 计算，作为 Claude 分词器的近似值。Netwright 每次调用的操作速度较慢：表单流程耗时约 1.8 s，而其他方案约为 0.6 s，因为每项操作都会等待 UI 稳定下来。作为交换，响应中已包含操作结果，因此 Agent 需要的调用更少，消耗的 tokens 也大幅减少。

安装

需要 Windows 10/11 和 .NET 10 SDK。你的应用可以面向任何 .NET 或 .NET Framework 版本。

Claude Code

claude mcp add netwright -- dnx Netwright --yes

任何 MCP 客户端（Claude Desktop、Cursor、VS Code、Copilot……）

{
  "mcpServers": {
    "netwright": {
      "command": "dnx",
      "args": ["Netwright", "--yes"]
    }
  }
}

想使用全局工具？运行 dotnet tool install -g Netwright，并使用 "command": "netwright"。若要限制 Agent 可以操作的应用，请在参数中添加 "--", "--allow", "MyApp*"。所有选项请参阅集成指南。

工具

工具	功能
desktop_app	启动 .exe 或构建并启动项目、附加、关闭、查看状态
desktop_snapshot	将 UI 转换为带有 Refs 的精简文本
desktop_find	查找与 Selector 匹配的元素（#id、role "name"、a >> b）
desktop_inspect	查看单个元素的属性、模式和稳定的 Selector
desktop_click	点击（后台；使用 foreground 可右键或双击）
desktop_type	设置文本（后台）或输入实际按键
desktop_set_state	勾选、选择、展开、设置值或按名称选取项目
desktop_press_key	按下按键和快捷键（前台）
desktop_scroll	按方向滚动、滚动到边缘或滚动到视图范围内
desktop_window	列出、激活、最小化、最大化、还原、关闭窗口
desktop_screenshot	获取窗口或元素的图像，即使被遮挡也可以
desktop_wait	等待元素状态或文本；报告发生的更改
desktop_expect	重试断言：文本、值、启用状态、勾选状态、数量……
desktop_logs	应用输出：stdout、stderr、debug/trace
desktop_export_test	将会话转换为 C# 回归测试

完整参考：docs/TOOLS_REFERENCE.md。

支持的 UI 技术

级别	技术	说明
1	WPF、WinForms（.NET 6+ 和 .NET Framework 4.x）	提供 Fixture App，每次更改都会运行集成测试，并经过基准测试
2	WinUI 3、Windows 上的 .NET MAUI	提供 Fixture App 和集成测试
3	Avalonia、Uno Platform	通过 UI Automation 尽力支持

其他 Windows 应用（Win32、Qt、Electron……）通常也能运行，因为 Netwright 使用标准的 UI Automation，但不提供支持。

如果你的应用在需要操作的控件上设置了 AutomationProperties.AutomationId（WPF/WinUI）或 Name（WinForms），自动化效果会更好。请参阅让应用更适合自动化操作。

无需 Agent 的回归测试

[Fact]
public async Task Saving_an_order_asks_for_confirmation()
{
    await using var app = await DesktopApp.LaunchProjectAsync(@"..\..\..\..\src\Orders\Orders.csproj");

    await app.TypeAsync("#txtCustomer", "Rossi");
    await app.CheckAsync("#chkTerms");
    await app.ClickAsync("#btnSave");

    await app.Expect("window \"Confirm\"").ToBeVisibleAsync();
}

dotnet add package Netwright.Testing。这是 desktop_export_test 为你编写的代码。

工作原理

Netwright 使用一次缓存的 UI Automation 查询捕获每个窗口。窗口通过 Win32 查找，只请求约 20 个属性，并在提供程序内部过滤屏幕外的元素。随后，它会根据捕获结果生成过滤后的文本，在内存中解析 Selectors，并通过 RuntimeId 比较树以生成更改报告。详情和测量数据：docs/ARCHITECTURE.md。术语：CONTEXT.md。设计决策：docs/adr。

从 WPF-MCP 1.x 迁移

1.x	2.0
wpf_launch_application、wpf_attach_application、wpf_close_application	desktop_app action=launch|attach|close
wpf_snapshot（每次快照都会重置 refs）	desktop_snapshot（refs 保持稳定）
wpf_find_element、wpf_get_element_properties	desktop_find、desktop_inspect
wpf_click、wpf_type	desktop_click、desktop_type；两者都接受 Ref 或 Selector
wpf_set_value、wpf_toggle、wpf_select、wpf_expand_collapse	desktop_set_state（value、checked、item、expanded）
wpf_press_key	desktop_press_key foreground=true
wpf_scroll、wpf_scroll_into_view、wpf_focus	desktop_scroll（direction、to、into_view）
wpf_list_windows、wpf_switch_window、wpf_window_action	desktop_window
wpf_take_screenshot（base64 文本）	desktop_screenshot（图像内容）
wpf_wait_for	desktop_wait（也可等待文本）
wpf_console_messages	desktop_logs
wpf_set_background_mode	后台模式为默认值；需要时可在每次调用中传入 foreground=true
JSON 信封（success、data、metadata）	精简文本；错误以包含 code 和 hint 的 isError 结果返回

软件包现已更名为 Netwright（命令为 netwright），取代 WpfMcp.Server（wpf-mcp）。

贡献

欢迎提交问题和 PR。请参阅 CONTRIBUTING.md。使用 .\scripts\build.ps1 -Integration 进行构建和测试，并使用 .\scripts\benchmark.ps1 进行测量。

许可证

MIT