<trace> の <listeners> の <add> 要素

[アーティクル]
08/16/2008

更新 : 2007 年 11 月

Listeners コレクションにリスナを追加します。

<configuration> 要素
   <system.diagnostics> 要素
     <trace> 要素
       <trace> の <listeners> 要素
         <trace> の <listeners> の <add> 要素

<add name="name" 
     type="trace listener class name, Version, Culture, PublicKeyToken"
     initializeData="data"/>

属性と要素

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

属性

属性	説明
type	必須属性リスナの型を指定します。「完全修飾型名の指定」に指定されている要件に合った文字列を使用する必要があります。
initializeData	省略可能属性指定したクラスのコンストラクタに渡す文字列。
name	省略可能属性リスナの名前を指定します。

type

必須属性

リスナの型を指定します。「完全修飾型名の指定」に指定されている要件に合った文字列を使用する必要があります。

initializeData

省略可能属性

指定したクラスのコンストラクタに渡す文字列。

name

省略可能属性

リスナの名前を指定します。

子要素

なし。

親要素

要素	説明
configuration	共通言語ランタイムおよび .NET Framework アプリケーションで使用されるすべての構成ファイルのルート要素です。
listeners	メッセージを収集、格納、およびルーティングするリスナを指定します。リスナは、トレース出力を適切なターゲットに転送します。
system.diagnostics	ASP.NET 構成セクションのルート要素を指定します。
trace	トレースメッセージを収集、格納、およびルーティングするリスナを保持します。

解説

Debug クラスおよび Trace クラスは、同じ Listeners コレクションを共有します。これらのクラスの一方のコレクションにリスナオブジェクトを追加すると、もう一方のクラスは同じリスナを使用します。リスナクラスは、TraceListener クラスの派生クラスです。

トレースリスナの name 属性を指定しない場合は、トレースリスナの Name は、既定で空の文字列 ("") に設定されます。アプリケーションにリスナが 1 つしかない場合、名前を指定しなくてもリスナを追加でき、名前に空の文字列を指定してリスナを削除できます。ただし、アプリケーションに複数のリスナがある場合は、各トレースリスナの一意の名前を指定する必要があります。これにより、Listeners および 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" に設定すると、トレースとデバッグの出力を Console.Error に書き込みます。"false" に設定すると、Console.Out に書き込みます。
System.Diagnostics.DelimitedListTraceListener	DelimitedListTraceListener が出力を書き込むファイルの名前。
System.Diagnostics.EventLogTraceListener	既存のイベントログソースの名前。
System.Diagnostics.EventSchemaTraceListener	EventSchemaTraceListener が出力を書き込むファイルの名前。
System.Diagnostics.TextWriterTraceListener	TextWriterTraceListener が出力を書き込むファイルの名前。
System.Diagnostics.XmlWriterTraceListener	XmlWriterTraceListener が出力を書き込むファイルの名前。

使用例

<add> 要素を使用して Listeners コレクションにリスナ MyListener および MyEventListener を追加する方法を次の例に示します。MyListener は、MyListener.log というファイルを作成し、そのファイルに出力を書き込みます。MyEventListener は、イベントログにエントリを作成します。

<configuration>
   <system.diagnostics>
      <trace autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
            <add name="MyEventListener"
                 type="System.Diagnostics.EventLogTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"                 initializeData="MyConfigEventLog"/>
            <add name="configConsoleListener"
                 type="System.Diagnostics.ConsoleTraceListener, system, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>