Desktop UI Framework¶

The Windows SDK covers both .NET UI frameworks and Native HWND applications. .NET provides framework adapters; Native C/C++ explicitly calls the C ABI through window, command, and message lifecycle.

Capability Comparison¶

Capability	WPF	WinForms	WinUI 3	Native Win32/HWND
Window View	Automatic	Automatic	Automatic after explicit association	Explicitly call View C ABI
Control Action	Automatic	Automatic	Automatic after explicit association	Explicitly call in command or message
Dynamic Controls	Loaded event	Idle scan	Discovered within associated window	Application manages lifecycle
Network Resource	`HttpClient`	`HttpClient`	`HttpClient`	WinHTTP adapter or manual C ABI
Error	Unhandled exception	Unhandled exception	Unhandled exception	Crash recovery or manual C ABI
Long Task	UI thread detection	UI thread detection	UI thread detection	`HWND` Watchdog

Framework Integration¶

WPFWinFormsWinUI 3Native C/C++

Initialize and enable automatic instrumentation in App.OnStartup():

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

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

Initialize before creating the first Form, and shut down after the message loop ends:

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

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

Each Window in WinUI 3 must be explicitly associated:

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

You can also call GuanceSdk.AttachWinUIWindow(window, "MainWindow"). The association should be completed after creating the Window and before Activate().

Manage the View across the visible lifecycle of the top-level window:

guance_rum_start_view(rum, "MainWindow");

// Run the window message loop.

guance_rum_stop_view(rum);

Manage Actions at command or window message handling boundaries:

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

save_settings();

guance_rum_stop_action(rum, action_id);

Windows desktop frameworks like MFC that provide stable window and interaction lifecycles can use the same C ABI, but there is currently no framework-level automatic discovery adapter.

View Naming¶

Use stable business names. Do not use object addresses, random values, or window titles that contain user data.

Source	Recommended Name
WPF	Window type name or stable Title
WinForms	Form type name, Name, or stable Text
WinUI 3	Business name passed to `UseGuanceRum()`
Native	Business name passed to `guance_rum_start_view()`

Action Types¶

The .NET automatic instrumentation generates types such as click, key_press, input, select, and toggle based on the input source. Native applications should use the same stable type names and avoid both automatic and manual reporting for the same interaction.

Multiple Windows¶

WPF and WinForms track the currently visible window.
WinUI 3 requires an association for each Window created.
Native applications end the old View and start a new View when switching the active top-level window.
Starting a new View ends the current active View. Do not maintain multiple Views in parallel.

Native UI Hangs and Crashes¶

Native applications can use guance_sdk_native_monitoring_config to associate the main window HWND, enabling the UI Watchdog and crash recovery on next startup. For configuration fields and default thresholds, refer to RUM Configuration.

Shutting Down the SDK¶

.NET / C#Native C/C++

WPF and WinForms can wait for ShutdownAsync() at synchronous exit boundaries. WinUI 3 should wait for shutdown to complete during the close flow of the last window.

Call after the message loop ends and business threads no longer access the Handle:

guance_sdk_shutdown(rum);
rum = nullptr;