跳转至

快速开始

Windows SDK 同时支持 .NET/C# 与 Native C/C++。两种运行时使用相同的应用 ID、数据协议和 RUM、Log、Trace 能力，但安装方式与自动采集边界不同。

前置准备

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

安装

WPF、WinForms 和 WinUI 3 应用使用 .NET 6 或 .NET 8，在项目目录安装 NuGet 包：

dotnet add package Guance.Rum.Windows

Native 应用使用 C11 ABI 或 C++17 适配器。从源码构建目标架构的 DLL：

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

将 src/Guance.Rum.NativeCore/include 加入头文件搜索路径，链接 guance_rum_native，并将 guance_rum_native.dll 部署到应用可加载的位置。

初始化 RUM

using Guance.Rum.Windows;

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

RumSdk.EnableAutomaticInstrumentation();

#include "guance_rum.hpp"

int main()
{
    guance_rum_config config;
    guance_rum_config_init(&config);
    config.dataway_url = "https://openway.guance.com";
    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_rum_handle rum = guance_rum_init(&config);
    if (rum == nullptr) {
        return 1;
    }

    guance_rum_start_view(rum, "MainWindow");

    // 运行窗口消息循环。

    guance_rum_stop_view(rum);
    guance_rum_shutdown(rum);
    return 0;
}

以上示例已满足最小 RUM 接入。

UI 框架初始化位置

框架 初始化位置 额外处理
WPF App.OnStartup() App.OnExit() 等待 ShutdownAsync()
WinForms Application.Run() 前 消息循环结束后等待 ShutdownAsync()
WinUI 3 App 构造函数 每个 Window 创建后显式关联
Native C/C++ 创建首个顶层窗口前 从窗口生命周期显式调用 View C ABI

WinUI 3 创建窗口时还需要：

window = new MainWindow().UseGuanceRum("MainWindow");
window.Activate();

Native SDK 不安装进程级 Hook。应用需要从窗口、命令和网络边界调用 C ABI；WinHTTP、UI Watchdog 和崩溃恢复提供显式适配组件。

可选：初始化 Log 和 Trace

如果您还需要日志采集或链路追踪，可继续追加以下初始化。

C# 需要在调用 RumSdk.Init() 前，将 Logging 和 Trace 追加到同一个 RumConfig：

RumSdk.Init(new RumConfig
{
    // ...省略基础 RUM 配置
    Logging = new RumLogConfig
    {
        EnableCustomLog = true,
        EnableLinkRumData = true
    },
    Trace = new RumTraceConfig
    {
        EnableAutoTrace = true,
        EnableLinkRumData = true
    }
});

RumSdk.EnableAutomaticInstrumentation();

Native C/C++ 在 guance_rum_init() 成功后配置 Log 和 Trace：

guance_rum_log_config logging;
guance_rum_log_config_init(&logging);
logging.enable_custom_log = 1;
logging.enable_link_rum_data = 1;
guance_rum_configure_logging(rum, &logging);

guance_rum_trace_config trace;
guance_rum_trace_config_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
guance_rum_configure_trace(rum, &trace);
限制 Trace Header 的目标地址

以上代码展示最小启用方式。生产环境应通过 ShouldTrace 或 should_trace 设置可信服务白名单。C# 自动 Trace 作用于 HttpClient 采集边界；Native C/C++ 需要使用 WinHTTP 适配器或手动 Trace 上下文 API。

使用本地环境部署（Datakit）

将 DatawayUrl 和 ClientToken 替换为：

DatakitUrl = "http://127.0.0.1:9529"

将 dataway_url 和 client_token 替换为：

config.datakit_url = "http://127.0.0.1:9529";

验证接入

  1. 启动应用并开始一个 View。
  2. 产生 Action 或 HTTP Resource。
  3. 正常关闭 SDK，确认控制台中出现 RUM 数据。
  4. 如果启用了 Log，写入一条 info Log 并确认关联的 RUM 上下文。
  5. 如果启用了 Trace，检查可信目标服务是否收到所选格式的 Trace Header。
var rum = RumSdk.GetDiagnosticsSnapshot();
Console.WriteLine($"rum={rum.RumEventsEnqueued}");

// 启用 Log 后可以同时检查：
var log = RumSdk.GetLogDiagnosticsSnapshot();
Console.WriteLine($"log={log.LogsEnqueued}");

await RumSdk.ShutdownAsync();

guance_rum_diagnostics rum_diagnostics{};
guance_rum_get_diagnostics(rum, &rum_diagnostics);

// 启用 Log 后可以同时检查：
guance_rum_log_diagnostics log_diagnostics;
guance_rum_log_diagnostics_init(&log_diagnostics);
guance_rum_get_log_diagnostics(rum, &log_diagnostics);

guance_rum_shutdown(rum);

下一步

文档评价

文档内容是否对您有帮助？ ×