インストルメンテーションの理解
Dotfuscator のインストルメンテーション機能は、コードを追加することなく、事前に作成されたアプリケーション利用状況、機能の利用状況、例外の追跡、およびシステム メトリックをアプリケーションに追加します。 この処理はコードの差し込みと呼ばれています。 この処理が行われたアプリケーションは、コードが差し込まれたアプリケーションと呼ばれます。 実行時に、アプリケーションに差し込まれたコードが、PreEmptive Analytics エンドポイントに遠隔測定を送信します。
インストルメンテーション コードをアプリケーションに差し込むための開発ワークフローは、アセンブリを難読化する開発ワークフローと類似しています。 どちらも特定のアセンブリで動作するように Dotfuscator を構成する必要があり、また、どちらも入力アセンブリと一致する一連の出力アセンブリを生成します。 唯一の違いは、使用される特定の構成要素です。 出力アセンブリには、遠隔測定データを収集、配信するために必要なすべてのランタイム コードが含まれます。
以下に、開発者の観点からのワークフローを図解します。
コードの差し込みを使用するとき、その他の Dotfuscator 機能も使用可能です。 差し込まれたランタイム コードには、難読化属性を使ってアノテーションが付けられています。このため、Dotfuscator によってアプリケーションに差し込まれるコードに対して名前の変更や除去などの変換を実行する場合、ユーザーによる構成は、入力アセンブリとアプリケーション コードの詳細に対して必要となること以外は何も必要ありません。
構成
インストルメンテーションは、属性と一連のオプションによって構成されます。 詳細については、以下を参照してください。
サポートされないアプリケーションの種類
Dotfuscator は、以下に挙げる .NET アセンブリ以外のすべての .NET アセンブリにインストルメンテーション コードを差し込むことができます。
- .NET 1.0 を対象とする入力アセンブリ
- ネイティブ コードおよびマネージ コードを含んでいる Managed C++ 入力アセンブリ
- マルチ モジュール入力アセンブリ
- .NET Core アセンブリ
- Unity アセンブリ
- Xamarin アセンブリ
遠隔測定
コードが差し込まれたアプリケーションを実行すると、差し込まれたコードにより、セッションの追跡用のセッションの開始をマークする "セッションの開始" メッセージなど、追跡対象イベントに関する情報をマークするためのメッセージが生成されます。
十分な数のメッセージが生成され、かつコードを差し込まれたアプリケーションが高負荷状態で実行されていない場合には、それらのメッセージはエンベロープと呼ばれる HTTP の POST 本文にパッケージされ、構成されているエンドポイントに送信されます。
これらのメッセージを生成してエンドポイントに送信する処理は、遠隔測定と呼ばれます。 また、それらのメッセージ自体が遠隔測定と呼ばれることもあります。
エンベロープと、エンベロープ内のメッセージは、アプリケーション用に構成されたビジネス、アプリケーション、およびバイナリ情報によって識別されます。
エンド ユーザーのオプトイン
コードが差し込まれたアプリケーションは、ユーザーが遠隔測定を有効または無効にできるオプションを提供することができます。 このオプションは、インストルメンテーションのセットアップ時にアプリケーション コードで提供されていれば、差し込まれたインストルメンテーション コードによって使用されます。
ユーザーの選択は、SetupAttribute
の OptInSource で定義されたソースを介して伝えられます。
このソースには、ユーザーがオプトインしている場合は true
、オプトアウトしている場合は false
になるブール
値を定義します。
SetupAttribute
にソースが設定されていない場合、差し込まれたコードは、ユーザーがオプトインしている場合と同じように動作します。
たとえば、次の属性とそのプロパティについて考えましょう。
実行時に InstrumentationExample.Program.Main
が呼び出されると、差し込まれたコードはまず静的メソッド InstrumentationExample.Program.OptIn()
を呼び出します。
この呼び出しの結果が true
の場合には、アプリケーションの実行中にメッセージが生成されて送信されます。
この呼び出しの結果が false
の場合には、標準のメッセージの大半は生成されません。
以下の場合には、オプトインの設定に関係なくメッセージが生成、送信されます。
ハンドルされない例外が報告されたときに、ユーザーが例外レポートの情報を使って遠隔測定のオプトイン設定をオーバーライドした場合
Sign of Life メッセージで、遠隔測定のオプトイン設定が無視された場合
チェックの遠隔測定で、遠隔測定のオプトイン設定が無視された場合
個人を特定できる情報
インストルメンテーションの追跡から個人を特定できる情報(PII:Personally Identifiable Information)を除外するかどうかは、SetupAttribute
の OmitPII プロパティを使用して構成できます。
オフライン記憶域
コードが差し込まれたアプリケーションは、指定されたエンドポイントに実行時に接続できない場合には、生成されたメッセージを記憶域に格納しておき、接続が復元されたときに送信することができます。 メッセージは分離ストレージのディスクに格納されます。 この動作は既定値では有効になっており、既定の接続検出コードがインストルメント化されたアプリケーションに差し込まれます。
オフライン記憶域を完全に無効にするには、SetupAttribute
の OfflineStateSourceElement プロパティを構成します。
アプリケーションが指定されたエンドポイントに接続できない場合、生成されたメッセージは格納されず、失われることになります。
また、独自のネットワーク検出コードを書いて、検出されたネットワーク接続の状態を差し込まれたコードで利用できるようにすることもできます。後者は、SetupAttribute
の OfflineStateSource で定義されたブール値のソースを介して行います。
さらに、SetupAttribute
の OfflineStorageResultSink で定義されたブール値のシンクを介して、オフライン記憶域へのメッセージの格納が成功したか失敗したかを通知することもできます。
このシンクを構成する場合に、オフライン記憶域の成否に対応するコードを書くことができます。
アプリケーションのインスタンス ID の報告
アプリケーションのインストール ID(たとえば、シリアル番号)を
生成されるメッセージに追加することができます。
必要な場合には、アプリケーションはこの ID を SetupAttribute
の InstanceIdSource で定義されたソースに入れて提供することができます。
差し込まれたインストルメンテーション コードは、そのソースにこの文字列 ID を要求して、その他の遠隔測定データと共に送信します。
エンドポイント
PreEmptive Solutions には、アプリケーションからのメッセージの送信先にできるエンドポイントがいくつか用意されています。
PreEmptive Analytics Workbench
PreEmptive Analytics Workbench は、Web ブラウザーで表示するための遠隔測定の受け付け、処理、変換、および集計を行います。 幅広い構成およびカスタマイズが可能で、アプリケーションの利用状況、導入、ユーザー動作、およびソフトウェアの品質を役割ベースでリアルタイムに「見える化」して提供することができます。これにより、時間とコストが削減されます。
詳細については、弊社 Web サイトの PreEmptive Analytics Workbench をお読みください。
Analytics API
Analytics API には、メッセージの送信、オフライン記憶域の管理、および全般的なインストルメンテーションのセットアップに関連するコードが含まれています。
アプリケーションに差し込まれたコードからこの API にアクセスする方法には以下の 2 つがあります。
Dotfuscator は、入力アセンブリの 1 つに Analytics API のランタイム コードをマージする(差し込む)ことができます。
- この場合、PreEmptive Analytics DLL を別途配布する必要はありません。
Dotfuscator は、別のアセンブリに Analytics API のランタイム コードを出力し、入力アセンブリに適切なアセンブリ参照を追加することができます。
入力アセンブリの一部が厳密名を持っている場合は、Dotfuscator はランタイム DLL に厳密な名前を付け、それを透過的に署名します。入力アセンブリのうちどれも厳密名を持っていなければ、Dotfuscator はランタイム DLL に厳密な名前を付けません。
この場合は、新しい DLL をアプリケーションと一緒に配布する必要があります。
Dotfuscator は今後も、インストルメンテーション用に構成されたアセンブリごとにインストルメンテーションのヘルパー メソッドを差し込む必要があります。
この動作を制御する[ランタイムのマージ]オプションは、グローバルな差し込みオプションです。 差し込み関連オプションには、構成エディターと Visual Studio 統合のどちらからもアクセスできます。
Analytics API を使用するには、[ランタイムのマージ]オプションの設定に関係なく、Dotfuscator では依然として入力アセンブリの 1 つにコードを差し込む必要があります。 Dotfuscator は最良の入力アセンブリを選択するために、入力アセンブリの依存関係分析を実行します。 入力アセンブリ間の新しい依存関係を最小限にするように、このような方法で選択を行っていますが、新しい依存関係の追加が避けられない場合もあります。
このコードの差し込み先となるアセンブリをオーバーライドするには、"accesspoint" という名前の構成プロパティを追加し、その値として、コードの挿入先となるアセンブリの名前を設定します。 この構成プロパティの追加は、構成エディターでも Visual Studio 統合でも行えます。