Windows 应用接入¶

Windows SDK 为 .NET/C# 和 Native C/C++ 提供统一的 RUM、Log 与 HTTP Trace 关联能力。应用根据运行时选择接入方式，数据使用相同的应用 ID、服务和环境维度进入控制台。

选择接入方式¶

接入方式	适用应用	安装方式	UI 边界
.NET / C#	WPF、WinForms、WinUI 3	`Guance.Rum.Windows` NuGet	框架自动采集；WinUI 3 显式关联 Window
Native C/C++	Win32、基于 `HWND` 的桌面框架	CMake、头文件、导入库、`guance_rum_native.dll`	窗口和控件生命周期显式调用 C ABI
WebView2	.NET 宿主中的 Edge WebView2	随 .NET SDK	自动发现或显式关联控件
Electron	Electron Renderer + Windows Native Bridge	`@cloudcare/browser-rum` 与 SDK Native Host	Browser RUM 仅采集和序列化；原生端管理 Session、队列和上传

支持范围¶

项目	支持范围
操作系统	Windows 10 或更高版本
.NET	.NET 6、.NET 8
Native 标准	C11 ABI、C++17 适配器
架构	x86、x64、ARM64
数据上报	公网 DataWay、本地环境部署（Datakit）
RUM	View、Action、Resource、Error、Long Task
Log	自定义/批量 Log、独立队列、RUM 关联；C# 支持 `System.Diagnostics.Trace` 采集
Trace	HTTP Header 传播与 RUM Resource 关联，不上传独立 APM Span
Session Replay	默认关闭；WPF、WinForms、WinUI 3、WebView2、Electron 和 Native 均可显式开启验证，当前为实验性能力

功能边界

Session Replay 可以显式开启和验证，但仍为实验性能力，不属于稳定兼容承诺。Avalonia、.NET MAUI 和 UWP 没有独立自动采集适配器；可复用 Native C ABI 的框架需要自行管理窗口和控件生命周期。

创建应用¶

登录观测云控制台，进入「用户访问监测」，点击「新建应用」：

填写应用名称和应用 ID。
应用类型选择「自定义」。
保存应用 ID，用于 RumAppId 或 rum_app_id。

同一 Windows 产品的 C#、C++、WebView2 和 Electron 可以使用同一个应用 ID，再通过 service、version 和运行时标签区分数据。

安装¶

.NET / C#Native C/C++

dotnet add package Guance.Rum.Windows

示例：

git clone https://github.com/GuanceCloud/rum-windows-sdk.git
cd rum-windows-sdk
cmake -S src/Guance.Rum.NativeCore -B build/native -A x64
cmake --build build/native --config Release

公共头文件：

guance_rum.h：C11 ABI，C 和 C++ 均可使用；
guance_rum.hpp：C++ 作用域 Resource 与 std::terminate 适配；
guance_rum_winhttp.hpp：同步和异步 WinHTTP Resource/Trace 适配。

应用、导入库和 DLL 的架构必须一致。NuGet 包包含供 .NET 包装层使用的 Native 运行时 DLL，但当前不提供 C/C++ 头文件和导入库。

源码地址：https://github.com/GuanceCloud/rum-windows-sdk

上报方式¶

公网 DataWay本地环境部署（Datakit）

运行时	地址	凭证
.NET / C#	`RumConfig.DatawayUrl`	`RumConfig.ClientToken`
Native C/C++	`guance_rum_config.dataway_url`	`guance_rum_config.client_token`

运行时	地址	凭证
.NET / C#	`RumConfig.DatakitUrl`	不需要 Client Token
Native C/C++	`guance_rum_config.datakit_url`	不需要 Client Token

使用本地环境部署前，需要安装 DataKit并启用 RUM 采集器。

初始化顺序¶

.NET / C#Native C/C++

// config 至少包含上报地址和 RUM 应用信息；Log/Trace 按需追加。
RumSdk.Init(config);
RumSdk.EnableAutomaticInstrumentation();

// 应用退出前执行。
await RumSdk.ShutdownAsync();

guance_rum_handle rum = guance_rum_init(&config);
guance_rum_start_view(rum, "MainWindow");

// 消息循环结束后执行。
guance_rum_stop_view(rum);
guance_rum_shutdown(rum);

如需 Log 或 Trace，在 guance_rum_init() 成功后分别调用 guance_rum_configure_logging()、guance_rum_configure_trace()。

SDK 使用磁盘队列缓存 RUM 和 Log。正常退出时完成关闭流程，避免进程终止时仍有未持久化操作。

阅读路径¶

基础地址、身份、队列和生命周期：SDK 初始化
View、Action、Resource、Error、Long Task：RUM 配置
自定义日志和自动 Trace 输出：Log 配置
HTTP Trace Header 与 RUM 关联：Trace 配置
WPF、WinForms、WinUI 3 和 Native UI：桌面 UI 框架
WebView2 或 Electron：WebView2、Electron