快速开始¶

Windows SDK 同时提供两个独立发布的包：.NET/C# 应用通过 NuGet 使用 Guance.Windows，Native C/C++ 应用通过 SDK 的 vcpkg 注册表使用 guance-windows-native。二者使用相同的 RUM 应用 ID 和数据上报方式，但包版本、升级节奏和更新日志彼此独立。

前置准备¶

在「用户访问监测」中创建「自定义」应用，并获取应用 ID。
准备一种数据上报方式：
公网 DataWay：上报地址和 Client Token；
本地环境部署（DataKit）：应用进程可访问的 DataKit 地址。
确认应用运行在 Windows 10 或更高版本。

接入步骤¶

根据应用技术栈选择 NuGet 或 vcpkg 包。
安装依赖并填写 RUM 应用与上报配置。
初始化 SDK，并按需开启自动采集、Log、Trace 和 Session Replay。
运行应用，在控制台确认数据上报成功。

选择包¶

应用类型	包	安装方式	当前支持
.NET / C#	`Guance.Windows`	NuGet.org	`net6.0`、`net8.0`、`net6.0-windows10.0.17763.0`、`net8.0-windows10.0.17763.0`；x86、x64、ARM64 Native 运行时资产
Native C/C++	`guance-windows-native`	SDK vcpkg 注册表	Windows x64，非 UWP；首个版本为动态库

版本说明

本文使用 [latest_version] 表示最新版本。NuGet 搜索界面需要启用预发布包；生产项目请将 [latest_version] 替换为经过验证的具体版本并固定依赖。

.NET / C#：使用 NuGet¶

在项目目录中安装：

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

或在项目文件中添加：

<PackageReference Include="Guance.Windows" Version="[latest_version]" />

NuGet 包会按运行时标识（RID）带入以下 Native DLL，无需手动复制：

runtimes/win-x64/native/guance_windows_native.dll
runtimes/win-arm64/native/guance_windows_native.dll
runtimes/win-x86/native/guance_windows_native.dll

Native C/C++：使用 vcpkg¶

配置 SDK 注册表¶

在项目根目录创建或更新 vcpkg-configuration.json。请将默认注册表基线替换为项目已验证的 Microsoft vcpkg 提交；<latest-sdk-vcpkg-registry-commit> 表示 SDK 注册表的最新提交。接入时应将占位符替换为实际提交并固定，保证构建可复现。

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "<compatible-microsoft-vcpkg-commit>"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/GuanceCloud/gc-vcpkg-registry.git",
      "baseline": "<latest-sdk-vcpkg-registry-commit>",
      "packages": [
        "guance-windows-native"
      ]
    }
  ]
}

声明依赖并安装¶

在项目根目录的 vcpkg.json 中声明端口：

{
  "dependencies": [
    "guance-windows-native"
  ]
}

随后以清单模式安装：

vcpkg install

CMake 链接¶

配置 CMake 时传入 vcpkg toolchain 文件，然后在 CMakeLists.txt 中查找并链接包：

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

可使用 C 头文件 guance_sdk.h、各信号专用 C 头文件 guance_rum.h、guance_trace.h、guance_log.h，或 C++ 辅助头文件 guance_sdk.hpp。完整 C API 请参考公开的 guance_sdk.h。

最小初始化示例¶

初始化时必须填写 RUM 应用 ID、服务名、环境和应用版本。公共 DataWay 模式使用 DatawayUrl 和 ClientToken；使用本地环境部署（DataKit）时，仅设置 DatakitUrl，不需要公网 Token。

.NET / C#：DataWay.NET / C#：DataKitNative C/C++：DataWayNative C/C++：DataKit

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.<your-domain>",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});

GuanceSdk.EnableAutomaticInstrumentation();

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_init(&config);
config.dataway_url = "https://openway.<your-domain>";
config.client_token = "<client-token>";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "prod";
config.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);
if (sdk == nullptr) {
    // 处理初始化失败。
}

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "local";
config.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);

初始化一次后，在应用退出前显式处理队列并关闭 SDK：

.NET / C#Native C/C++

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(sdk);
guance_sdk_shutdown(sdk);

可选：初始化 Log、Trace 和 Session Replay¶

.NET/C# 可选择自动采集 WPF、WinForms、WinUI 3、HttpClient、未处理异常和 UI 线程阻塞；在第一个窗口创建前调用 GuanceSdk.EnableAutomaticInstrumentation()。Native C/C++ 通过公开 C API 在窗口、命令和网络边界显式接入。
Trace Header 仅应向可信服务发送。请通过 Trace 配置中的目标地址白名单限制可注入 Header 的请求。
SDK 默认使用隐私保护配置。Session Replay 默认关闭，需显式开启；它仍是实验性功能，不属于稳定兼容承诺。

有关 UI、WebView2、Electron 和各信号的配置，请参阅桌面 UI 框架、WebView2 监测、Electron 监测、RUM 配置、Log 配置和 Trace 配置。

验证接入是否成功¶

启动应用并打开至少一个 View。
完成一次点击操作，并发起一次 HTTP 请求。
在「用户访问监测 > 查看器」中选择对应应用，确认出现 Session、View、Action 和 Resource 数据。
开启 Log 或 Trace 后，分别确认日志数据和 Trace Header/RUM Resource 关联正常。
开启 Session Replay 后，确认 Replay 上传诊断状态为成功，并在会话详情中检查回放入口。

如果控制台没有数据，请参考故障排查。

下一步¶

完整基础参数、缓存、诊断和生命周期配置：SDK 初始化
RUM、Log 和 Trace 配置：RUM 配置、Log 配置、Trace 配置
桌面 UI、WebView2 和 Electron：桌面 UI 框架、WebView2 监测、Electron 监测
隐私和数据保护：隐私与权限说明

升级和更新日志¶

NuGet 与 vcpkg 使用独立版本流，即使版本号相同也不能视为同一个发布：

发行方式	版本标签	更新日志
NuGet / C#	`nuget_<semver>`	C# 更新日志
vcpkg / Native C/C++	`vcpkg_<semver>`	Native C/C++ 更新日志

支持稳定版 1.2.3，以及 1.2.3-alpha.1、1.2.3-beta.1 形式的预发布版本。升级时请分别阅读对应包的更新日志，并更新 NuGet 版本或 vcpkg 注册表基线；两个发布流在更新日志中分区展示。

常见问题¶

在 Visual Studio 的 NuGet UI 中找不到包：启用「包括预发行版」，或使用本文给出的 dotnet add package 命令。
vcpkg install 未找到端口：确认 vcpkg-configuration.json 中的注册表 URL、packages 列表和固定基线正确，并在项目根目录以清单模式执行安装。
.NET 应用未加载 Native DLL：确认项目目标框架为本页列出的支持框架，并且发布时 RID 与部署环境架构一致。