Windows 应用接入¶

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

阅读路径¶

首次接入：先看快速开始。
完整接入：继续阅读本文。
参数详解：查看 SDK 初始化、RUM 配置、Log 配置和 Trace 配置。
高级能力：查看“高级场景”分组下的专项页面。
问题排查：查看故障排查。

前置条件¶

支持范围¶

项目	支持范围
操作系统	Windows 10+
.NET 目标框架	`net6.0` / `net8.0`
Native 标准	C11 ABI、C++17 适配器
NuGet Native RIDs	`win-x64` / `win-x86` / `win-arm64`
vcpkg Native	动态 `x64-windows`，非 UWP
分发方式	NuGet / vcpkg
数据上报	公网 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 的框架需要自行管理窗口和控件生命周期。

应用接入¶

选择接入方式¶

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

创建应用¶

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

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

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

安装¶

.NET / C#Native C/C++Electron

dotnet add package Guance.Windows --version [latest_version]

示例：

推荐通过 GuanceCloud vcpkg 注册表安装 guance-windows-native。注册表、清单和 CMake 配置请按快速开始完成；安装后链接公开 CMake Target：

find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)

如需调试 SDK 源码，也可以直接构建：

git clone https://github.com/GuanceCloud/datakit-windows-desktop.git
cd datakit-windows-desktop
cmake -S src/Guance.Windows.Native -B build/native -A x64
cmake --build build/native --config Release

公共头文件：

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

应用、导入库和 DLL 的架构必须一致。当前 vcpkg 端口只提供动态 x64-windows；NuGet 包中的 x86、x64 和 ARM64 Native DLL 供 .NET 包装层使用，不包含 C/C++ 头文件和导入库。

Renderer 安装 Browser SDK：

npm install @cloudcare/browser-rum @cloudcare/browser-logs

Electron 全量模式还需要先按快速开始配置 GuanceCloud vcpkg 注册表，再在 vcpkg.json 中为 guance-windows-native 启用 electron-bridge Feature，并以清单模式执行 vcpkg install --triplet x64-windows。该 Feature 会安装 Bridge EXE 与匹配的 Native DLL；两者必须一起打包。

C++ 初始化的混合模式不启动 Bridge EXE，由 C++ 宿主提供写入已有 SDK Handle 的 Adapter。完整安装、打包与能力边界参考 Electron 监测。

源码地址：GuanceCloud/datakit-windows-desktop

初始化说明¶

上报方式¶

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

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

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

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

初始化顺序¶

.NET / C#Native C/C++

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

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

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_start_view(rum, "MainWindow");

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

如需 Log 或 Trace，在 guance_sdk_init() 成功后分别调用 guance_log_configure()、guance_trace_configure()。

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 页面监测：WebView2 监测
Electron Renderer 与 Native Bridge：Electron 监测
隐私、权限和数据脱敏：隐私与权限说明

常见问题¶

初始化、数据上报、桌面 UI、WebView2、Electron、Log、Trace 和 Session Replay 问题请参考故障排查。