Windows アプリの統合¶

Windows SDK は、.NET/C# と Native C/C++ 向けに、RUM、Log、HTTP Trace を統一的に関連付ける機能を提供します。アプリケーションはランタイムに応じて統合方法を選択し、データは同じアプリID、サービス、環境ディメンションでコンソールに取り込まれます。

読み進め方¶

初回導入：先にクイックスタートを参照してください。
本格導入：本ドキュメントを続けてお読みください。
パラメータの詳細：SDK 初期化、RUM 設定、Log 設定、Trace 設定を参照してください。
高度な機能：「高度なシナリオ」グループ内の専用ページを参照してください。
トラブルシューティング：トラブルシューティングを参照してください。

前提条件¶

対応範囲¶

項目	対応範囲
OS	Windows 10+
.NET ターゲットフレームワーク	`net6.0` / `net8.0`
Native 標準	C11 ABI、C++17 アダプター
NuGet Native RIDs	`win-x64` / `win-x86` / `win-arm64`
vcpkg Native	動的 `x64-windows`、UWP 非対応
配布方法	NuGet / vcpkg
データ送信	パブリックネットワーク DataWay、ローカル環境デプロイ（Datakit）
RUM	View、Action、Resource、Error、Long Task
Log	カスタム/バッチ Log、独立キュー、RUM 関連付け。C# は `System.Diagnostics.Trace` の収集に対応
Trace	HTTP ヘッダー伝播と RUM Resource の関連付け。独立した APM Span はアップロードしない
Session Replay	デフォルトでは無効。WPF、WinForms、WinUI 3、WebView2、Electron、Native で明示的に有効化して検証可能。現時点では実験的機能

機能の境界

Session Replay は明示的に有効化・検証できますが、依然として実験的機能であり、安定した互換性の保証対象ではありません。Avalonia、.NET MAUI、UWP には独立した自動収集アダプターがありません。Native C ABI を再利用するフレームワークでは、ウィンドウとコントロールのライフサイクルを自身で管理する必要があります。

アプリの統合¶

統合方法の選択¶

統合方法	対応アプリ	インストール方法	UI 統合の境界
.NET / C#	WPF、WinForms、WinUI 3	`Guance.Windows` NuGet	フレームワークが自動収集。WinUI 3 では Window を明示的に関連付け
Native C/C++	Win32、`HWND` ベースのデスクトップフレームワーク	CMake、ヘッダーファイル、インポートライブラリ、`guance_windows_native.dll`	ウィンドウとコントロールのライフサイクルを C ABI で明示的に呼び出し
WebView2	.NET ホスト内の Edge WebView2	.NET SDK に同梱	自動検出、またはコントロールを明示的に関連付け
Electron	Electron Renderer + Windows Native Bridge	Browser SDK + `guance-windows-native[electron-bridge]`	Browser SDK は収集とシリアライズのみ実行。信頼済み Main Process とネイティブ側が Session、キュー、アップロードを管理

アプリの作成¶

Guance コンソールにログインし、「RUM」を開いて「アプリを作成」をクリックします：

アプリ名とアプリIDを入力します。
アプリタイプで「カスタム」を選択します。
アプリIDを保存します。RumAppId または rum_app_id に使用します。

同じ Windows 製品の C#、C++、WebView2、Electron は同じアプリIDを使用でき、service、version、ランタイムタグでデータを区別できます。

インストール¶

.NET / C#Native C/C++Electron

dotnet add package Guance.Windows --version [latest_version]

サンプル：

SDK の vcpkg レジストリから guance-windows-native をインストールすることをお勧めします。レジストリ、マニフェスト、CMake 設定はクイックスタートに従って完了してください。インストール後、公開 CMake Target をリンクします：

find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)

SDK のソースコードをデバッグする場合は、直接ビルドすることもできます：

git clone https://github.com/GuanceCloud/datakit-windows-desktop.git
cd datakit-windows-desktop
cmake -S src/Guance.Windows.Native -B build/native -A x64
cmake --build build/native --config Release

公開ヘッダーファイル：

guance_rum.h：C11 ABI。C と C++ の両方で使用可能。
guance_sdk.hpp：C++ スコープの Resource と std::terminate のアダプター。
guance_rum_winhttp.hpp：同期および非同期 WinHTTP Resource/Trace アダプター。

アプリ、インポートライブラリ、DLL のアーキテクチャは一致している必要があります。現在の vcpkg ポートが提供するのは動的 x64-windows のみです。NuGet パッケージ内の x86、x64、ARM64 Native DLL は .NET ラッパーレイヤー向けであり、C/C++ のヘッダーファイルとインポートライブラリは含まれません。

Renderer に Browser SDK をインストールします：

npm install @cloudcare/browser-rum @cloudcare/browser-logs

Electron フルモードでは、まずクイックスタートに従って SDK の vcpkg レジストリを設定し、vcpkg.json で guance-windows-native の electron-bridge Feature を有効化したうえで、マニフェストモードで vcpkg install --triplet x64-windows を実行する必要があります。この Feature は Bridge EXE と対応する Native DLL をインストールします。両者は必ず一緒にパッケージングしてください。

C++ 初期化によるハイブリッドモードでは Bridge EXE は起動されず、C++ ホストが既存の SDK Handle に書き込む Adapter を提供します。完全なインストール、パッケージング、機能の境界については、Electron モニタリングを参照してください。

ソースコード：Windows SDK ソースコード

初期化の説明¶

送信方法¶

パブリックネットワーク DataWayローカル環境デプロイ（Datakit）

ランタイム	エンドポイント	認証情報
.NET / C#	`GuanceConfig.DatawayUrl`	`GuanceConfig.ClientToken`
Native C/C++	`guance_sdk_config.dataway_url`	`guance_sdk_config.client_token`

ランタイム	エンドポイント	認証情報
.NET / C#	`GuanceConfig.DatakitUrl`	Client Token 不要
Native C/C++	`guance_sdk_config.datakit_url`	Client Token 不要

ローカル環境デプロイを使用する前に、DataKit をインストールし、RUM コレクターを有効化する必要があります。

初期化の順序¶

.NET / C#Native C/C++

// config には送信先と RUM アプリ情報を最低限含めます。Log/Trace は必要に応じて追加します。
GuanceSdk.Init(config);
GuanceSdk.EnableAutomaticInstrumentation();

// アプリ終了前に実行します。
await GuanceSdk.ShutdownAsync();

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_start_view(rum, "MainWindow");

// メッセージループ終了後に実行します。
guance_rum_stop_view(rum);
guance_sdk_shutdown(rum);

Log または Trace が必要な場合は、guance_sdk_init() の成功後に guance_log_configure() と guance_trace_configure() をそれぞれ呼び出します。

SDK はディスクキューを使用して RUM と Log をキャッシュします。正常終了時にはシャットダウンプロセスが完了し、プロセス終了時に未永続化の操作が残らないようにします。

詳細設定の参照先¶

ベースURL、認証情報、キュー、ライフサイクル：SDK 初期化
View、Action、Resource、Error、Long Task：RUM 設定
カスタムログと自動 Trace 出力：Log 設定
HTTP Trace ヘッダーと RUM の関連付け：Trace 設定

高度なシナリオ¶

WPF、WinForms、WinUI 3、Native UI：デスクトップ UI フレームワーク
WebView2 ページモニタリング：WebView2 モニタリング
Electron Renderer と Native Bridge：Electron モニタリング
プライバシー、権限、データマスキング：プライバシーと権限について

よくある質問¶

初期化、データ送信、デスクトップ UI、WebView2、Electron、Log、Trace、Session Replay に関する問題は、トラブルシューティングを参照してください。