デスクトップ 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)
{
    GuanceSdk.Init(config);
    GuanceSdk.EnableAutomaticInstrumentation();
    base.OnStartup(e);
}

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

最初の Form を作成する前に初期化し、メッセージループの終了後にシャットダウンします：

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

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

WinUI 3 では、各 Window に明示的な関連付けが必要です：

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

GuanceSdk.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_sdk_native_monitoring_config を使用してメインウィンドウの HWND を関連付け、UI Watchdog と次回起動時のクラッシュリカバリを有効にできます。設定フィールドとデフォルトのしきい値については、RUM 設定を参照してください。

SDK のシャットダウン¶

.NET / C#Native C/C++

WPF と WinForms は、同期終了の境界で ShutdownAsync() を待機できます。WinUI 3 では、最後のウィンドウのクローズフローでシャットダウンの完了を待機してください。

メッセージループが終了し、ビジネススレッドが Handle にアクセスしなくなったら呼び出します：

guance_sdk_shutdown(rum);
rum = nullptr;