方法 : トレース スイッチを設定する

更新 : 2007 年 11 月

アプリケーションを配布した後でも、アプリケーションにトレース スイッチを設定することによって、トレース出力を有効または無効にできます。スイッチを設定することは、初期化後に外部ソースから値を変更することを意味します。スイッチ オブジェクトの値は、構成ファイルを使用して変更できます。トレース スイッチの設定では、トレース スイッチをオンまたはオフにしたり、レベルを設定したりすることにより、リスナに渡すメッセージの量と種類を決定できます。

スイッチは、.config ファイルを使用して設定します。Web アプリケーションの場合は、プロジェクトに関連付けられた Web.config ファイルになります。Windows アプリケーションの場合、このファイルの名前は "(アプリケーション名).exe.config" になります。このファイルは、実行可能ファイルと同じフォルダに存在している必要があります。

アプリケーションが、初めてスイッチのインスタンスを作成するコードを実行するときに、構成ファイルで名前付きスイッチについてのトレース レベル情報がチェックされます。トレース システムは、アプリケーションがスイッチを最初に作成するときに、特定のスイッチごとに 1 回だけ、構成ファイルを検査します。

配置されたアプリケーションでは、アプリケーションが実行されていないときにスイッチ オブジェクトを再設定することで、トレース コードを有効にできます。この作業では、通常、スイッチ オブジェクトのオンとオフを切り替えるか、またはトレース レベルを変更し、その後アプリケーションを再起動します。

スイッチのインスタンスを作成するときに、displayName および description という 2 つの引数を指定して、このインスタンスを初期化します。コンストラクタの displayName 引数は、Switch クラス インスタンスの Switch.DisplayName プロパティを設定します。displayName は、.config ファイルでスイッチを設定するために使用する名前です。description 引数は、スイッチおよびスイッチによって制御されるメッセージについての簡単な説明を返します。

設定するスイッチの名前を指定する以外に、スイッチの値も指定する必要があります。この値には整数型の値を指定します。BooleanSwitch では、値 0 は Off に対応し、ゼロ以外のすべての値は On に対応します。TraceSwitch では、0、1、2、3、および 4 は、それぞれ Off、Error、Warning、Info、および Verbose に対応します。4 を超える数値はすべて Verbose として扱われ、0 未満の数値はすべて Off として扱われます。

メモ :
.NET Framework Version 2.0 では、テキストを使用してスイッチの値を指定できます。たとえば、BooleanSwitch に対して true を指定したり、TraceSwitch に対して列挙値を表す Error などのテキストを指定したりできます。<add name="myTraceSwitch" value="Error" /> 行は、<add name="myTraceSwitch" value="1" /> に相当します。

エンド ユーザーがアプリケーションのトレース スイッチを設定できるようにするには、アプリケーションのスイッチについての詳細な説明を提供する必要があります。どのスイッチが何を制御するか、およびスイッチのオンとオフをどのように切り替えるかを詳細に記述する必要があります。また、コメントとして適切なヘルプが含まれた .config ファイルをエンド ユーザーに提供する必要もあります。

トレース スイッチを作成および設定するには

1. コードにスイッチを作成します。詳細については、「方法 : トレース スイッチを作成し初期化する」を参照してください。

2. プロジェクトに構成ファイル (app.config または Web.config) が含まれていない場合は、[プロジェクト] メニューの [新しい項目の追加] をクリックします。

   • Visual Basic: [新しい項目の追加] ダイアログ ボックスの [アプリケーション構成ファイル] を選択します。

     アプリケーションの構成ファイルが作成され、表示されます。これは、ルート要素が <configuration>. の XML ドキュメントです。

   • Visual C#: [新しい項目の追加] ダイアログ ボックスの [XML ファイル] を選択します。このファイルに app.config という名前を付けます。次に、XML エディタで、XML 宣言の後に次の XML を追加します。

     <configuration>
     </configuration>
     

     プロジェクトがコンパイルされると、app.config ファイルがプロジェクト出力フォルダにコピーされ、名前が applicationname.exe.config に変更されます。

3. <configuration> タグと </configuration> タグの間に、適切な XML を追加してスイッチを構成します。DisplayName プロパティを DataMessageSwitch に設定した BooleanSwitch、および DisplayName プロパティを TraceLevelSwitch に設定した TraceSwitch の例を次に示します。

   <system.diagnostics>
      <switches>
         <add name="DataMessagesSwitch" value="0" />
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

   この設定では、両方のスイッチがオフになります。

4. 前の例の DataMessagesSwitch などの BooleanSwitch をオンにする必要がある場合は、Value を 0 以外の任意の整数に変更します。

5. 前の例の TraceLevelSwitch などの TraceSwitch をオンにする必要がある場合は、Value を適切なレベル設定 (1 ～ 4) に変更します。

6. どの値を変更すると適切にスイッチを変更できるかをエンド ユーザーが理解しやすいように、.config ファイルにコメントを追加します。

   コメントを含むコードの完成例を次に示します。

   <system.diagnostics>
      <switches>
         <!-- This switch controls data messages. In order to receive data 
            trace messages, change value="0" to value="1" -->
         <add name="DataMessagesSwitch" value="0" />
         <!-- This switch controls general messages. In order to 
            receive general trace messages change the value to the 
            appropriate level. "1" gives error messages, "2" gives errors 
            and warnings, "3" gives more detailed error information, and 
            "4" gives verbose trace information -->
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

参照

処理手順

方法 : アプリケーション コードにトレース ステートメントを追加する

概念

実装とトレースの概要

トレース スイッチ

参照

トレースおよびデバッグ設定のスキーマ

その他の技術情報

アプリケーションのトレースとインストルメント