Desktop UI Frameworks¶

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 lifecycles.

Capability Comparison¶

Capability	WPF	WinForms	WinUI 3	Native Win32/HWND
Window View	Automatic	Automatic	Automatic after explicit association	Explicit View C ABI calls
Control Action	Automatic	Automatic	Automatic after explicit association	Explicit calls in commands or messages
Dynamic Controls	Loaded event	Idle scanning	Discovered within the associated window	Application manages the lifecycle
Network Resource	`HttpClient`	`HttpClient`	`HttpClient`	WinHTTP adapter or manual C ABI calls
Error	Unhandled exceptions	Unhandled exceptions	Unhandled exceptions	Crash recovery or manual C ABI calls
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 the first Form is created, and shut down after the message loop ends:

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

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

Every 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"). Complete the association after creating the Window and before calling Activate().

Maintain the View for the visible lifetime of the top-level window:

guance_rum_start_view(rum, "MainWindow");

// Run the window message loop.

guance_rum_stop_view(rum);

Maintain 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 that provide stable window and interaction lifecycles, such as MFC, can use the same C ABI, but no framework-level automatic discovery adapter is currently available.

View Naming¶

Prefer 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¶

.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 reporting the same interaction both automatically and manually.

Multiple Windows¶

WPF and WinForms track the currently visible window.
Every Window created in WinUI 3 must be associated.
Native applications end the old View when the active top-level window switches, then start the new View.
Starting a new View ends the currently active View. Do not maintain multiple Views in parallel.

Native UI Freezes and Crashes¶

Native applications can associate the main window HWND via guance_sdk_native_monitoring_config to enable the UI Watchdog and crash recovery on the next launch. 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 the synchronous exit boundary. WinUI 3 should wait for shutdown to complete during the last window closing flow.

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

guance_sdk_shutdown(rum);
rum = nullptr;