デスクトップ UI フレームワーク¶

Windows SDK は .NET UI フレームワークと Native HWND アプリケーションの両方をカバーします。.NET にはフレームワークアダプターが用意されています。Native C/C++ では、ウィンドウ、コマンド、メッセージのライフサイクルを通じて C ABI を明示的に呼び出します。

機能比較¶

機能	WPF	WinForms	WinUI 3	Native Win32/HWND
ウィンドウビュー	自動	自動	明示的関連付け後に自動	View C ABI を明示的に呼び出し
コントロールアクション	自動	自動	明示的関連付け後に自動	コマンドまたはメッセージ内で明示的に呼び出し
動的コントロール	Loaded イベント	Idle スキャン	関連付けられたウィンドウ内で検出	アプリがライフサイクルを管理
ネットワークリソース	`HttpClient`	`HttpClient`	`HttpClient`	WinHTTP アダプターまたは手動 C ABI
エラー	未処理例外	未処理例外	未処理例外	クラッシュリカバリまたは手動 C ABI
長時間タスク	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;