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 的框架需要自行管理窗口和控件生命周期。

应用接入¶

选择 SDK 与运行时¶

SDK 与运行时	适用应用	安装方式	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 和运行时标签区分数据。

选择接入方式¶

在应用配置页面选择「Agent 自动接入」或「手动接入」，再完成「接入配置」。已有应用可直接进入配置页面继续接入。

接入方式	适用场景	操作入口
Agent 自动接入	希望由编程助手分析项目并完成 SDK 接入	复制控制台生成的提示词，在应用代码仓库中交给编程助手执行
手动接入	希望自行安装 SDK 并配置参数	确认数据上报方式，再按本文和快速开始完成配置

Agent 自动接入¶

在当前应用的配置页面选择「Agent 自动接入」。
复制「接入配置」中的完整提示词，确保使用当前应用的接入信息。
在应用代码仓库中打开编程助手，粘贴提示词，由 Agent 按接入指引分析项目并完成 SDK 配置。
构建并运行应用，触发页面访问等操作，在当前应用的查看器中确认收到数据。

若页面提示个人 API Key 或临时授权码未就绪，请按提示补齐后重新复制提示词。

手动接入¶

在应用配置页面选择「手动接入」，确认数据上报方式：

公网 DataWay：从当前应用的接入配置中获取上报地址和 Client Token，无需自行部署 DataKit。
本地环境部署：使用已部署的 DataKit 接收数据，并确保应用可以访问其上报地址。

按下文安装和快速开始完成 SDK 安装、初始化与验证。已有 SDK 配置时，应先核对并复用，避免重复初始化。

安装¶

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

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

使用 Session Replay 时，添加同版本的 Guance.Windows.SessionReplay。安装及迁移要求见可选组件安装。

示例：

推荐通过 SDK 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++ 头文件和导入库。Session Replay 通过同一 port 的 replay Feature 安装。

安装 Main Process Adapter 和 Renderer Browser SDK：

npm install @cloudcare/electron-native-adapter@alpha @cloudcare/browser-rum @cloudcare/browser-logs

Electron 全量模式由 npm Adapter 下载基础运行时并管理 Bridge EXE。使用 Replay 时，还需显式安装同版本、同架构的 Replay 补充归档，并与基础运行时一起打包到 ASAR 外。

C++ 初始化的混合模式由宿主启动 named-pipe Bridge Server，Electron Adapter 连接已有 SDK Handle；Replay 组件由宿主的 vcpkg replay Feature 提供。完整安装、打包与能力边界参考 Electron 监测。

源码地址：Windows SDK 源码

初始化说明¶

上报方式¶

公网 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 问题请参考故障排查。