例外の追跡
例外の追跡は、キャッチされた例外、スローされた例外、またはハンドルされない例外が発生したときに、コードを差し込まれたアプリケーションがそれを報告できるようにするインストルメンテーション機能です。 また、このような例外の発生に対応するように、当該アプリケーションを構成することもできます。
例外の追跡は、メソッド レベルで構成すれば、メソッド内で発生した例外を検出でき、アセンブリ レベルで構成すれば、アセンブリ内の任意の場所で発生した例外を検出できます。
構成
例外を追跡するには
in-code 属性または拡張属性を使って、
ExceptionTrackAttributeを適切なアセンブリやメソッドに追加します。これらの属性のプロパティを適切に構成します。
Dotfuscator 構成をビルドします。
これで、出力アセンブリには、例外追跡用の差し込みコードが含まれます。
サポートされるアプリケーションの種類
例外の追跡は、インストルメンテーションでサポートされるすべてのアセンブリに含まれるメソッドで使用できます。 また、そのようなアセンブリ自体でも例外の追跡を使用できますが、次の場合は除きます。
- XNA アセンブリ
汎用の例外ダイアログを導入する場合は、追加の制限が適用されることに注意してください。
例外の検出
既定では、Dotfuscator は構成されている ExceptionType に応じて、例外を自動的に検出するコードを以下の各方法で差し込みます。
Caught：Dotfuscator は、例外が
catchブロックに入った直後に例外を追跡するコードを差し込みます。Thrown：Dotfuscator は、例外が
throwステートメントによってスローされる直前に例外を追跡するコードを差し込みます。Unhandled：Dotfuscator は、メソッド レベルでは、try/catch ブロックでメソッドをラップし、元のスタック トレースを伴って例外を再度スローすることによって、例外を追跡するコードを差し込みます。また、アセンブリ レベルでは、
AppDomain.UnhandledExceptionイベントや類似したイベントのハンドラーを差し込むことによって、例外を追跡するコードを差し込みます。
これらの検出を組み合わせるには、1 つのアセンブリまたはメソッドに複数の ExceptionTrackAttribute を定義します。
あるいは、独自のコードで例外を検出し、その例外を、ExceptionTrackAttribute の ExceptionSource で定義されたソース経由で、差し込まれたコードに提供することもできます。
メモ：アセンブリ レベルの
ExceptionTrackAttributeでは、ExceptionSource を定義することができないため、Dotfuscator によって差し込まれた例外検出コードを使用する必要があります。
アプリケーション通知
任意で、アプリケーション コードに例外の発生を通知することもできます。 これにより、アプリケーションは例外に対し、サード パーティ製の遠隔測定を送信したりするなど、カスタマイズされた方法で対応できます。
例外の検出は、ExceptionTrackAttribute の ExceptionNotificationSink で定義されたシンクを介して伝えられます。
差し込まれたコードは、検出された Exception オブジェクトをこのシンクに転送します。
たとえば、次の属性とそのプロパティについて考えましょう。
実行時に ExceptionExample.ApplicationNotification.ExceptionTrackLocation が呼び出されると、差し込まれたコードはハンドルされない例外を検出します（この例では ExceptionType が "Unhandled" に設定されているため）。
検出された例外は、静的メソッド ExceptionExample.ApplicationNotification.OnExceptionDetected(Exception) に渡されます。
これにより、OnExceptionDetected メソッドは、検出された例外に対するアプリケーション固有の動作を実行することができます。
メモ： ExceptionNotificationSink は、チェックが実行されるたびに呼び出される他のシンクとは異なり、構成された種類の例外が明確に発生した場合にのみ呼び出されます。つまり、このシンクは呼び出されることも、
nullが設定されることもありません。
レポート情報
例外が発生した場合、そのエラーがどのようなシナリオでトリガーされたかなどの追加情報をユーザーから提供していただくことは有用です。 また、ユーザーは、以前に遠隔測定をオプトアウトしている場合でも、例外レポートの送信に同意することができます。 アプリケーションにこの情報を提供させることができ、差し込まれたコードを使ってユーザーに情報を求めることもできます。
アプリケーションによる提供
この情報は、ExceptionTrackAttribute の ReportInfoSource で定義されたソースを介して伝えられます。
このソースは、IDictionary または IDictionary<string,string> を定義します。
この辞書から、差し込まれたコードが検索するキーには、以下の 3 つがあります。
consent：値は、ユーザーがこの例外レポートの送信を選択（オプトイン）したかどうかを示す、文字列のtrueまたはfalseです。trueの場合は、ユーザーが遠隔測定をオプトアウトしている場合でも、例外レポートは常に送信されます。falseなどtrue以外の場合は、ユーザーが遠隔測定をオプトインしている場合でも、例外レポートは送信されません。このキーが指定されていない場合は、グローバルな遠隔測定のオプトイン設定が使用されます。
comment：値は、例外が発生したときにアプリケーションが実行していた内容についてユーザーが提供したコメントです。- このキーが指定されている場合、この情報はエラー メッセージに含まれます。
contact：値は、ユーザーが提供した、構造化されていない連絡先情報です。- このキーが指定されている場合、この情報はエラー メッセージに含まれます。
ユーザー提供のレポート情報を収集することは任意です。 このアプリケーション提供のレポート情報機能を使用する場合は、アプリケーションのユーザーに情報を実際に要求しなくても、これらの値の一部または全部を設定できます。
汎用の例外ダイアログ
Dotfuscator は、アプリケーション コードを呼び出す代わりに、差し込まれたコードを使ってユーザーに情報を提供するように依頼することができます。
これを行うには、ExceptionTrackAttribute の ReportInfoSourceElement プロパティで、"DefaultAction" 値を選択します。
動作
次の情報を指定している場合は、それらがこのダイアログで使用されます。
ApplicationAttributeの Name プロパティに指定されている、アプリケーションの名前BusinessAttributeの CompanyName プロパティに指定されている、会社の名前ExceptionTrackAttributeの PrivacyPolicyUri プロパティに指定されている、プライバシー ポリシーの URI
ユーザーは、［Add Details］ボタンをクリックすれば、追加の詳細（コメントや連絡先情報）を提供できます。 ［Send Error Report］ボタンをクリックすると、レポートが送信されます。 これ以外の方法でこのダイアログを閉じた場合には、レポートは送信されません。 どちらの場合も、グローバルな遠隔測定オプトイン設定は無視されます。
ダイアログと互換性のあるアプリケーションの種類
汎用の例外ダイアログは、例外の追跡でサポートされているアセンブリと、そのようなアセンブリ内のメソッドで使用できますが、以下の場合は除きます。
- .NET Compact Framework アセンブリ。
- Windows Phone アセンブリ
- ユニバーサル Windows プラットフォーム（UWP）アセンブリ
- Xamarin アセンブリ
- Unity アセンブリ
アセンブリは、.NET Framework バージョン 1.1 以降または Silverlight バージョン 2 以降を対象としている必要があります。
さらに、Silverlight アセンブリでは、汎用の例外ダイアログは、アセンブリ レベルの例外の追跡にのみ使用できます。メソッド レベルの追跡には使用できません。
この組み込みダイアログは、.NET Framework で使用する場合、Windows フォーム API を使って構築、表示されます。 これは、コンソールやサービス アプリケーションに予期せぬ結果をもたらす可能性があります。このような場合は、アプリケーション提供のレポート情報を使用するのが望ましいかもしれません。 アセンブリがまだ適切な Windows フォーム ライブラリを参照していない場合は、その参照が追加されます。
メッセージ
例外の追跡では、エラーの種類のメッセージのみが生成されます。
エラー
この種類のメッセージは、ExceptionTrackAttribute でアノテーションが付けられたアセンブリまたはメソッド内でハンドルされない例外が検出され、ユーザーがそのような例外の送信に同意している場合に生成されます。
以下のデータを含んでいます。