インストルメンテーション属性リファレンス

このページでは、インストルメンテーション機能の差し込みを制御する属性を列挙します。

以下のすべての属性は名前空間 PreEmptive.Attributes に定義されていますが、セクションのタイトルでは簡潔にするため省略されています。

全般の差し込みは、［差し込みを有効にする］オプションによって制御されることに留意してください。 このオプションを無効にした場合、どんな属性を指定しても、コードは差し込まれなくなります。

属性の参照

Dotfuscator には、インストルメンテーション属性が定義されている参照アセンブリが付属しています。 このアセンブリは PreEmptive.Attributes.dll という名前であり、Dotfuscator がインストールされているのと同じディレクトリに格納されています。

このアセンブリのパスを見つける最も簡単な方法は、次のとおりです。

1： コマンド プロンプトを開きます。

2. where PreEmptive.Attributes.dll コマンドを実行し、その結果をコピーします。

メモ： Dotfuscator のインストーラーは、自動的に Dotfuscator を PATH へ追加します。

次に、このアセンブリへの参照をプロジェクトに追加します。 アセンブリはフレームワーク自体以外には依存関係を持たないため、必要であれば別の場所にコピーすることもできます。 コードを差し込むときに、Dotfuscator は既定でこの DLL への参照を解除します。そのため、アプリケーションの実行時に DLL は必要なく、DLL をアプリケーションと共に配布する必要はありません。 ［差し込み属性の除去］オプションの値が、この既定の設定のままであることを確認します。

属性の一覧

このセクションでは、Dotfuscator がインストルメンテーション機能の差し込みを構成するために認識する属性を列挙します。

BusinessAttribute

差し込み対象のアセンブリの所有者である会社を指定します。 インストルメンテーションの遠隔測定とチェックの遠隔測定では必須です。

• 適用対象：アセンブリ

• 必要条件：なし

• プロパティ：

  • CompanyKey：必須。会社を一意に識別する GUID 文字列。通常、これは、特定の会社のデータが正しくルーティングされるように、PreEmptive Solutions によって提供されます。

  • CompanyName：推奨。会社を識別する文字列。Analytics サーバーに集められたデータを読みやすくするために使用されます。

ApplicationAttribute

差し込み対象のアセンブリのアプリケーションを指定します。 インストルメンテーションの遠隔測定とチェックの遠隔測定では必須です。

• 適用対象：アセンブリ

• 必要条件：なし

• プロパティ：

  • Guid：必須。会社内のアプリケーションを一意に識別し、アプリケーションの有効期間中に変更してはいけない GUID 文字列。このアプリケーション ID により、エンドポイントはアプリケーションの名前やバージョン番号が変わっても、そのアプリケーションのデータを集めることが可能になります。

  • Name：推奨。アプリケーションを識別する文字列。Analytics サーバーに集められたデータを読みやすくするために使用されます。このプロパティが空白である場合は、実行時にリフレクションを使ってアセンブリのファイル名を取得できれば、それが代わりに使用されます。

  • Version：任意。アプリケーションのバージョンを識別する文字列。Analytics サーバーに集められたデータをフィルタリングするために使用されます。このプロパティが空白である場合は、実行時にリフレクションを使ってアセンブリのバージョンを取得できれば、それが代わりに使用されます。

  • ApplicationType：任意。アプリケーションの種類を識別する文字列。Analytics サーバーに集められたデータをフィルタリングするために使用されます。このプロパティが空白である場合は、実行時にリフレクションを使ってアセンブリの種類（たとえば .exe）を取得できれば、それが代わりに使用されます。

BinaryAttribute

差し込み対象のアセンブリを指定します。 このアセンブリが別のアセンブリからもたらされる場合は、そのアセンブリが、インストルメンテーションの遠隔測定とチェックの遠隔測定の発信元のアセンブリを報告するときに使用されます。

• 適用対象：アセンブリ

• 必要条件：なし

• プロパティ：

  • Guid：必須。アプリケーション内のアセンブリを一意に識別する GUID 文字列。

SetupAttribute

この属性でアノテーションが付けられたメソッドの冒頭にセッションの開始コードを差し込むよう、Dotfuscator に指示します。 差し込まれたコードにより、インストルメンテーションが設定され、セッションの開始メッセージが生成されます。

SetupAttribute を持つメソッドは、実行時、遠隔測定を送信する前に呼び出す必要があるため、通常のアプリケーション起動ロジックのできる限り近くに置く必要があります。

この属性は、StaticEndpoint プロパティを使用して、遠隔測定レポートの宛先となるエンドポイントを指定します。 また、この属性を使って、ユーザーのオプトイン/オプトアウト動作を実装できます。

• 適用対象：メソッド

• 必要条件：

  • インストルメンテーションを設定する場合：

    • ビルド時：

      • メソッドのアセンブリに BusinessAttribute がある。

      • メソッドのアセンブリに ApplicationAttribute がある。

    • 実行時：なし。

  • セッションの開始メッセージを生成する場合：

    • 上記のすべて。

    • ビルド時：［分析メッセージの送信］オプションが有効である。

    • 実行時：ユーザーがオプトアウトしていない。

• プロパティ：

  • StaticEndpoint：インストルメンテーションの遠隔測定とチェックの遠隔測定の送信先となる URL（プロトコルを除く）。 既定値は、PreEmptive Analytics エンドポイントの URL です。 EndpointSource が指定されていない場合は必須です。

  • EndpointSourceElement：インストルメンテーションの遠隔測定とチェックの遠隔測定の送信先となる URL（プロトコルを除く）を提供するソースを指定します。 StaticEndpoint が指定されていない場合は必須です。

    • string 型のメソッド引数、フィールド、またはプロパティ、あるいは string() 署名付きのメソッドを指定できます。

    • "ApplicationSetting" の場合は、デスクトップ アプリケーションおよび Web アプリケーションの標準 .NET 構成に定義されている設定を指定できます。

    • "None"（既定値）の場合は、StaticEndpoint から URL が取得されます。

    • "DefaultAction" は、"None" の単なる別名です。

  • EndpointSourceName：上記のソースの名前（または、"ApplicationSetting" の場合はキー）を指定します。

  • EndpointSourceOwner：上記のソースを宣言する型を指定します。

  • UseSSL：PreEmptive Analytics Endpoint へ遠隔測定を送信するときに、HTTPS プロトコル（"True" に設定した場合）または HTTP プロトコル（"False" に設定した場合）のどちらを使用するかを指定します。既定値は "True" です。

  • OptInSourceElement：ユーザーのオプトインの選択を示すソースを指定します。

    • bool 型のメソッド引数、フィールド、またはプロパティ、あるいは bool() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、ユーザーは常にオプトインになります。

  • OptInSourceName：上記のソースの名前を指定します。

  • OptInSourceOwner：上記のソースを宣言する型を指定します。

  • OmitPII：遠隔測定から個人を特定できる情報を除外するかどうかを指定します。既定値は "False" です。

  • InstanceIdSourceElement：生成されるメッセージに含めるアプリケーション インスタンス ID を、差し込まれたコードに伝えるソースを指定します。

    • string 型のメソッド引数、フィールド、またはプロパティ、あるいは string() 署名付きのメソッドを指定できます。

    • "None" の場合は、生成されるメッセージにアプリケーション インスタンス ID は含まれません。

  • InstanceIdSourceName：上記のソースの名前を指定します。

  • InstanceIdSourceOwner：上記のソースを宣言する型を指定します。

  • OfflineStateSourceElement：アプリケーションがネットワーク接続していない状況にある場合、生成されたメッセージのためにオフライン記憶域を使用するかどうかを、差し込まれたコードに伝えるソースを指定します。

    • bool 型のメソッド引数、フィールド、またはプロパティ、あるいは bool() 署名付きのメソッドを指定できます。

    • "DefaultAction"（既定値）の場合は、差し込まれたアプリケーションではオフライン記憶域がサポートされるため、Dotfuscator により既定の接続検出コードが差し込まれます。

    • "None" の場合は、差し込まれたアプリケーションでオフライン記憶域は使用されません。

  • OfflineStateSourceName：上記のソースの名前を指定します。

  • OfflineStateSourceOwner：上記のソースを宣言する型を指定します。

  • OfflineStorageResultSinkElement：生成されたメッセージをオフライン記憶域に保存する一番最近の試行が成功した場合には true を、失敗した場合には false を報告するために、差し込まれたコードが使用するシンクを指定します。

    • bool 型のフィールドまたはプロパティ、あるいは void(bool) 署名付きのメソッド、デリゲート フィールド、またはデリゲート メソッド引数を指定できます。

    • "None"（既定値）の場合、差し込まれたアプリケーションは、オフライン記憶域への保存の結果を報告しません。

    • "DefaultAction" の場合は、オフライン記憶域へのメッセージの保存が失敗すると、差し込まれたアプリケーションは直ちに終了します。

  • OfflineStorageResultSinkName：上記のシンクの名前を指定します。

  • OfflineStorageResultSinkOwner：上記のシンクを宣言する型を指定します。

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、セッションの開始メッセージと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、セッションの開始メッセージと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、セッションの開始メッセージと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。

TeardownAttribute

この属性でアノテーションが付けられたメソッドの exit ポイントにセッションの停止コードを差し込むよう、Dotfuscator に指示します。 差し込まれたコードにより、セッションの停止メッセージが生成され、キューに入っているメッセージがあれば送信されて、インストルメンテーションがシャットダウンされます。

この属性は、アプリケーションが停止するポイントのできる限り近くで、"通常" の終了状態で使用する必要があります。 アノテーションが付けられたメソッドは、必ずしも最後に呼び出されるメソッドである必要はありませんが、そのアプリケーションがシャットダウンするときに 1 回だけ実行されるという特性を持っている必要があります。 この属性によって指定されるコードは、メソッドの exit ポイントに差し込まれるため、SetupAttribute を置いたのと同じメソッドに置くこともできます。

• 適用対象：メソッド

• 必要条件：

  • インストルメンテーションをシャットダウンする場合：

    • ビルド時：

      • メソッドのアセンブリに BusinessAttribute がある。

      • メソッドのアセンブリに ApplicationAttribute がある。

    • 実行時：インストルメンテーションがあらかじめ設定されている（SetupAttribute でアノテーションが付けられたメソッドを呼び出すことにより設定されます）。

  • セッションの停止メッセージを生成する場合：

    • 上記のすべて。

    • ビルド時：［分析メッセージの送信］オプションが有効である。

    • 実行時：ユーザーがセットアップ時にオプトアウトしていない。

• プロパティ：

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、セッションの停止メッセージと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、セッションの停止メッセージと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、セッションの停止メッセージと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。

FeatureAttribute

この属性でアノテーションが付けられたメソッドに機能の追跡コードを差し込むよう、Dotfuscator に指示します。 差し込まれたコードにより、機能メッセージが生成されます。

• 適用対象：メソッド（1 つのメソッドに複数の属性を指定できます)

• 必要条件：

  • ビルド時：

    • ［分析メッセージの送信］オプションが有効である。

    • 同じ入力アセンブリ内の同一メソッドに SetupAttribute がある。

  • 実行時：

    • インストルメンテーションがあらかじめ設定されている（SetupAttribute でアノテーションが付けられたメソッドを呼び出すことにより設定されます）。

    • ユーザーがセットアップ時にオプトアウトしていない。

• プロパティ：

  • FeatureEventType：必須。送信する機能メッセージの種類を指定します。既定値は "Tick" です。

    • Tick：このメソッドのエントリ ポイントは、機能の瞬間（Tick）を示します。

    • Start：このメソッドのエントリ ポイントは、機能の開始/停止の始まりを示します。

    • Stop：このメソッドの exit ポイントは、機能の開始/停止の終わりを示します。

  • Name：必須。機能の名前。

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、機能メッセージと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、機能メッセージと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、機能メッセージと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。

ExceptionTrackAttribute

指定されたアセンブリまたはメソッド内で発生する例外を検出し、報告（任意）するためのコードを差し込むよう、Dotfuscator に指示します。

• 適用対象：アセンブリまたはメソッド

• 必要条件：

  • ビルド時：同じ入力アセンブリ内の同一メソッドに SetupAttribute がある。

  • 実行時：

    • インストルメンテーションがあらかじめ設定されている（SetupAttribute でアノテーションが付けられたメソッドを呼び出すことにより設定されます）。

    • ユーザーがオプトアウトしていない。収集されたレポート情報に応じて、例外レポートに対してセットアップ時に構成したオプトイン設定をオーバーライドできます。

• プロパティ：

  • ReportInfoSourceElement：ユーザー指定のレポート情報を格納するソースを指定します。

    • IDictionary<string,string> 型または IDictionary 型のメソッド引数、フィールド、またはプロパティ、あるいは IDictionary<string,string> 署名付きまたは IDictionary 署名付きのメソッドを指定できます。 含めることができるキーと値のペアについては、アプリケーション提供のレポート情報を参照してください。

    • "DefaultAction" の場合、差し込まれたコードは Dotfuscator の汎用の例外ダイアログを使用します。

    • "None"（既定値）の場合、差し込まれたコードは、セットアップ時に指定されたオプトインの選択に従います。

  • ReportInfoSourceName：上記のソースの名前を指定します。

  • ReportInfoSourceOwner：上記のソースを宣言する型を指定します。

  • PrivacyPolicyUri：Dotfuscator の汎用の例外ダイアログで使用される、例外レポートの送信を保護するプライバシー ポリシーの URL。

    • ReportInfoSourceElement が "DefaultAction" でない場合には、このプロパティは無視されます。

  • ExceptionNotificationSinkElement：差し込まれたコードが、例外の発生をアプリケーションに通知するために使用するシンクを指定します。

    • System.Exception 型のフィールドまたはプロパティ、あるいは void(System.Exception) 署名付きのメソッド、デリゲート フィールド、またはデリゲート メソッド引数を指定できます。

    • "None"（既定値）の場合は、アプリケーションに例外の発生は通知されません。 これは、例外の遠隔測定が送信されるかどうかには影響しません。

  • ExceptionNotificationSinkName：上記のシンクの名前を指定します。

  • ExceptionNotificationSinkOwner：上記のシンクを宣言する型を指定します。

  • ExceptionSourceElement：差し込まれたコードが、例外の発生時にその例外を取得できる取得元のソースを指定します。 この ExceptionTrackAttribute でアセンブリにアノテーションを付ける場合は、プロパティを "DefaultAction" に設定する必要があります。

    • System.Exception 型のメソッド引数、フィールド、またはプロパティ、あるいは System.Exception() 署名付きのメソッドを指定できます。

    • "DefaultAction"（既定値）の場合は、Dotfuscator は、例外を自動的に検出するコードを差し込みます。

    • "None" は、"DefaultAction" の単なる別名です。

  • ExceptionSourceName：上記のソースの名前を指定します。

  • ExceptionSourceOwner：上記のソースを宣言する型を指定します。

  • ExceptionType：どのような種類の例外の発生を検出するかを指定します。次のいずれかを指定できます。

    • "Unhandled"（既定値）

    • "Caught"

    • "Thrown"

  • SendReport：例外が発生したときに、例外の遠隔測定（オプションで例外レポート情報も含まれる）を送信するかどうかを指定します。既定値は "True" です。

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、エラー メッセージと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、エラー メッセージと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、エラー メッセージと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。

SignOfLifeAttribute

アプリケーションが実行されていることを報告するためのコードを差し込むよう、Dotfuscator に指示します。 差し込まれたコードにより、Sign of Life メッセージが生成されます。

この属性を使用するには、Shelf Life Activation Key が必要です。

この属性によって差し込まれたコードでは、他のインストルメンテーション属性によって差し込まれたコードと異なり、ユーザーのオプトイン選択は使用されません。

属性名 "InsertSignOfLifeAttribute" の使用は現在推奨されていません。

• 適用対象：メソッド

• 必要条件：

  • ビルド時：

    • ［Shelf Life メッセージの送信］オプションが有効である。

    • 同じ入力アセンブリ内の同一メソッドに SetupAttribute がある。

  • 実行時：インストルメンテーションがあらかじめ設定されている（SetupAttribute でアノテーションが付けられたメソッドを呼び出すことにより設定されます）。

• プロパティ：

  • ActivationKeyFile：必須。ビルド時に有効な Shelf Life Activation Key ファイルのパスです。

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、Sign of Life メッセージと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、Sign of Life メッセージと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、Sign of Life メッセージと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。

PerformanceProbe

アプリケーションのパフォーマンスに関連する情報を取得して報告するためのコードを差し込むよう、Dotfuscator に指示します。 詳細については、システム メトリックを参照してください。

• 適用対象：メソッド

• 必要条件：

  • ビルド時：

    • ［分析メッセージの送信］オプションが有効である。

    • 同じ入力アセンブリ内の同一メソッドに SetupAttribute がある。

  • 実行時：

    • インストルメンテーションがあらかじめ設定されている（SetupAttribute でアノテーションが付けられたメソッドを呼び出すことにより設定されます）。

    • ユーザーがオプトアウトしていない。

• プロパティ：

  • Name：PerformanceProbeAttribute のこのインスタンスの名前。これは、実行中にさまざまな時点で取得したパフォーマンス測定値を区別するために使用できます。

  • InjectionPoint：生成されたコードを差し込む、メソッド内の場所。既定値は "Beginning" です。

    • "Beginning"：メソッドの最初の部分にパフォーマンス メトリックを収集するコードを差し込みます。

    • "End"：メソッドの最後の部分にパフォーマンス メトリックを収集するコードを差し込みます。

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、パフォーマンス メトリックと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、パフォーマンス メトリックと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、パフォーマンス メトリックと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。

SystemProfile

アプリケーションが実行されているシステムに関する情報を取得して報告するためのコードを差し込むよう、Dotfuscator に指示します。 詳細については、システム メトリックを参照してください。

• 適用対象：メソッド

• 必要条件：

  • ビルド時：

    • ［分析メッセージの送信］オプションが有効である。

    • 同じ入力アセンブリ内の同一メソッドに SetupAttribute がある。

  • 実行時：

    • インストルメンテーションがあらかじめ設定されている（SetupAttribute でアノテーションが付けられたメソッドを呼び出すことにより設定されます）。

    • ユーザーがオプトアウトしていない。

• プロパティ：

  • ExtendedKeyMethodArguments：アノテーションが付けられたメソッドのどの引数（ある場合）をユーザー定義データとして、システム メトリックと一緒に送信するかを指定します。 このプロパティの構成方法の詳細については、メソッド パラメーターを拡張キーとして自動的に送信するを参照してください。

  • ExtendedKeySourceElement：差し込まれたコードが、システム メトリックと一緒に送信するユーザー定義データを取得するときに使用するソースを指定します。

    • IDictionary 型または IDictionary<string, string> 型のフィールド、プロパティ、またはメソッド引数、あるいは IDictionary() 署名付きまたは IDictionary<string, string>() 署名付きのメソッドを指定できます。

    • "None"（既定値）の場合は、システム メトリックと一緒に送信するユーザー定義データを取得するためにソースは使用されません。

  • ExtendedKeySourceName：上記のソースの名前を指定します。

  • ExtendedKeySourceOwner：上記のソースを宣言する型を指定します。