Skip to content

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

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

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;