<source> の <listeners> の <add> 要素

2011-08-09

トレースソース用の Listeners コレクションにリスナーを追加します。

<add name="name" 
  type="TraceListenerClassName, Version, Culture, PublicKeyToken"
  initializeData="data"/>

属性および要素

以降のセクションでは、属性、子要素、および親要素について説明します。

属性

属性	説明
type	必須の属性です。リスナーの型を指定します。「完全修飾型名の指定」で指定されている要件を満たす文字列を使用する必要があります。
initializeData	省略可能な属性です。指定したクラスのコンストラクターに渡す文字列。文字列を受け取るコンストラクターがクラスにない場合は、ConfigurationException がスローされます。
name	省略可能な属性です。リスナーの名前を指定します。
traceOutputOptions	省略可能な属性です。トレースリスナーの TraceOutputOptions プロパティ値を指定します。
[カスタム属性]	省略可能な属性です。このリスナーの GetSupportedAttributes メソッドで識別されるリスナー固有の属性の値を指定します。 Delimiter は、DelimitedListTraceListener クラスに固有の追加属性の例です。

子要素

要素	説明
<source> の <listeners> の <add> の <filter> 要素	トレースソースの Listeners コレクション内のリスナーにフィルターを追加します。

親要素

要素	説明
configuration	共通言語ランタイムおよび .NET Framework アプリケーションで使用されるすべての構成ファイルのルート要素です。
system.diagnostics	メッセージを収集、格納、およびルーティングするトレースリスナーとトレーススイッチを設定するレベルを指定します。
sources	トレースメッセージを開始するトレースソースを保持します。
source	トレースメッセージを開始するトレースソースを指定します。
listeners	メッセージを収集、格納、およびルーティングするリスナーを指定します。

解説

.NET Framework に付属のリスナークラスは、TraceListener クラスの派生クラスです。

トレースリスナーの name 属性を指定しない場合は、トレースリスナーの Name プロパティは、既定で空の文字列 ("") に設定されます。アプリケーションにリスナーが 1 つしかない場合、名前を指定しなくてもリスナーを追加でき、名前に空の文字列を指定してリスナーを削除できます。ただし、アプリケーションに複数のリスナーがある場合は、各トレースリスナーの一意の名前を指定する必要があります。これにより、TraceSource.Listeners コレクション内の個別のトレースリスナーを識別および管理できます。

メモ
同じ名前を持つ同じ型のトレースリスナーを複数追加すると、その型と名前を持つトレースリスナーが 1 つだけ Listeners コレクションに追加されます。ただし、プログラムを使用すると、複数の同一のリスナーを Listeners コレクションに追加できます。

initializeData 属性の値は、作成するリスナーの型によって異なります。 initializeData を指定する必要のないトレースリスナーもあります。

メモ
initializeData 属性を使用すると、"initializeData 属性は宣言されていません" というコンパイラの警告が表示される場合があります。この警告は、initializeData 属性を認識しない TraceListener 抽象基本クラスに対して構成設定が検証されたために発生します。通常、パラメーターを受け取るコンストラクターのあるトレースリスナーの実装では、この警告を無視してもかまいません。

initializeData 属性を使用すると、"initializeData 属性は宣言されていません" というコンパイラの警告が表示される場合があります。この警告は、initializeData 属性を認識しない TraceListener 抽象基本クラスに対して構成設定が検証されたために発生します。通常、パラメーターを受け取るコンストラクターのあるトレースリスナーの実装では、この警告を無視してもかまいません。

.NET Framework に付属するトレースリスナーを次の表に示し、各リスナーの initializeData 属性の値を説明します。

トレースリスナークラス	initializeData 属性の値
System.Diagnostics.ConsoleTraceListener	ConsoleTraceListener コンストラクターの useErrorStream 値。 initializeData 属性を "true" に設定すると、トレース出力とデバッグ出力を標準エラー出力ストリームに書き込みます。"false" に設定すると、標準出力ストリームに書き込みます。
System.Diagnostics.DelimitedListTraceListener	DelimitedListTraceListener が出力を書き込むファイルの名前。
System.Diagnostics.EventLogTraceListener	既存のイベントログソースの名前。
System.Diagnostics.EventSchemaTraceListener	EventSchemaTraceListener が出力を書き込むファイルの名前。
System.Diagnostics.TextWriterTraceListener	TextWriterTraceListener が出力を書き込むファイルの名前。
System.Diagnostics.XmlWriterTraceListener	XmlWriterTraceListener が出力を書き込むファイルの名前。

構成ファイル

この要素は、マシン構成ファイル (Machine.config) およびアプリケーション構成ファイルで使用できます。

使用例

<add> 要素を使用して、リスナー console および textListener をトレースリソース TraceSourceApp の Listeners コレクションに追加する方法を次の例に示します。 textListener リスナーは、トレース出力を myListener.log ファイルに書き込みます。

<configuration>
  <system.diagnostics>
    <sources>
      <source name="TraceSourceApp" switchName="sourceSwitch" 
        switchType="System.Diagnostics.SourceSwitch">
        <listeners>
          <add name="console" 
            type="System.Diagnostics.ConsoleTraceListener"/>
          <add name="textListener"/>
          <remove name="Default"/>
        </listeners>
      </source>
    </sources>
    <sharedListeners>
      <add name="textListener" 
        type="System.Diagnostics.TextWriterTraceListener" 
        initializeData="myListener.log"/>
    </sharedListeners>
    <switches>
      <add name="sourceSwitch" value="Warning"/>
    </switches>
  </system.diagnostics>
</configuration>