桌面 UI 框架¶

Windows SDK 同时覆盖 .NET UI 框架和 Native HWND 应用。.NET 提供框架适配器；Native C/C++ 通过窗口、命令和消息生命周期显式调用 C ABI。

能力对比¶

能力	WPF	WinForms	WinUI 3	Native Win32/HWND
Window View	自动	自动	显式关联后自动	显式调用 View C ABI
控件 Action	自动	自动	显式关联后自动	命令或消息中显式调用
动态控件	Loaded 事件	Idle 扫描	关联窗口内发现	应用负责生命周期
网络 Resource	`HttpClient`	`HttpClient`	`HttpClient`	WinHTTP 适配器或手动 C ABI
Error	未处理异常	未处理异常	未处理异常	崩溃恢复或手动 C ABI
Long Task	UI 线程探测	UI 线程探测	UI 线程探测	`HWND` Watchdog

框架接入¶

WPFWinFormsWinUI 3Native C/C++

在 App.OnStartup() 初始化并开启自动采集：

protected override void OnStartup(StartupEventArgs e)
{
    RumSdk.Init(config);
    RumSdk.EnableAutomaticInstrumentation();
    base.OnStartup(e);
}

protected override void OnExit(ExitEventArgs e)
{
    RumSdk.ShutdownAsync().GetAwaiter().GetResult();
    base.OnExit(e);
}

在第一个 Form 创建前初始化，在消息循环结束后关闭：

ApplicationConfiguration.Initialize();
RumSdk.Init(config);
RumSdk.EnableAutomaticInstrumentation();

Application.Run(new MainForm());
RumSdk.ShutdownAsync().GetAwaiter().GetResult();

WinUI 3 的每个 Window 都需要显式关联：

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    window = new MainWindow().UseGuanceRum("MainWindow");
    window.Activate();
}

也可以调用 RumSdk.AttachWinUIWindow(window, "MainWindow")。应在创建 Window 后、Activate() 前完成关联。

在顶层窗口的可见生命周期维护 View：

guance_rum_start_view(rum, "MainWindow");

// 运行窗口消息循环。

guance_rum_stop_view(rum);

在命令或窗口消息处理边界维护 Action：

const char* action_id =
    guance_rum_start_action(rum, "SaveButton", "click");

save_settings();

guance_rum_stop_action(rum, action_id);

MFC 等能够提供稳定窗口和交互生命周期的 Windows 桌面框架可以使用同一 C ABI，但当前没有框架级自动发现适配器。

View 命名¶

优先使用稳定的业务名称，不要使用对象地址、随机值或包含用户数据的窗口标题。

来源	推荐名称
WPF	Window 类型名或稳定 Title
WinForms	Form 类型名、Name 或稳定 Text
WinUI 3	`UseGuanceRum()` 传入的业务名称
Native	`guance_rum_start_view()` 传入的业务名称

Action 类型¶

.NET 自动采集会按输入来源生成 click、key_press、input、select、toggle 等类型。Native 应用应使用相同的稳定类型名称，并避免同时对同一交互执行自动与手动上报。

多窗口¶

WPF 和 WinForms 会跟踪当前可见窗口。
WinUI 3 每创建一个 Window 都需要关联。
Native 应用在活动顶层窗口切换时结束旧 View，再开始新 View。
新 View 开始会结束当前活动 View，不要并行维护多个 View。

Native UI 卡顿与崩溃¶

Native 应用可通过 guance_rum_native_monitoring_config 关联主窗口 HWND，开启 UI Watchdog 和下次启动崩溃恢复。配置字段和默认阈值请参考 RUM 配置。

关闭 SDK¶

.NET / C#Native C/C++

WPF 和 WinForms 可以在同步退出边界等待 ShutdownAsync()。WinUI 3 应在最后一个窗口关闭流程中等待关闭完成。

消息循环结束、业务线程不再访问 Handle 时调用：

guance_rum_shutdown(rum);
rum = nullptr;