<trace> 適用之 <listeners> 的 <add> 項目

發行項
08/21/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"/>

屬性和項目

下列章節會說明屬性 (Attribute)、子項目和父項目。

屬性

屬性	描述
type	必要屬性。指定接聽程式的類型。您必須使用符合指定完整的型別名稱中指定之需求的字串。
initializeData	選擇性屬性。傳遞至指定類別的建構函式的字串。
name	選擇性屬性。指定接聽程式的名稱。

type

必要屬性。

指定接聽程式的類型。您必須使用符合指定完整的型別名稱中指定之需求的字串。

initializeData

選擇性屬性。

傳遞至指定類別的建構函式的字串。

name

選擇性屬性。

指定接聽程式的名稱。

子項目

無。

父項目

項目	描述
configuration	每一個組態檔中的根 (Root) 項目是由 Common Language Runtime 和 .NET Framework 應用程式所使用的。
listeners	指定收集、存放及傳送訊息的接聽程式。接聽程式將追蹤輸出導向至適當的目標。
system.diagnostics	指定 ASP.NET 組態區段的根項目。
trace	包含收集、存放和傳送追蹤訊息的接聽程式。

備註

Debug 和 Trace 類別共用一個 Listeners 集合。如果您將接聽程式物件加入至其中一個類別的集合，另一個類別會使用相同的接聽程式。接聽程式類別是從 TraceListener 類別衍生而來。

如果您未指定追蹤接聽程式的 name 屬性，追蹤接聽程式的 Name 預設為空字串 empty string ("")。如果您的應用程式僅有一個接聽程式，可以不必指定名稱就新增，並為名稱指定空字串以移除。然而，如果您的應用程式有超過一個接聽程式，則應為每個追蹤接聽程式指定唯一的名稱，此可讓您辨識並管理 Listeners 和 Listeners 集合中個別的追蹤接聽程式。

注意事項：
加入多個具有相同型別與相同名稱的追蹤接聽程式，結果只有一個該型別和名稱的追蹤接聽程式會加入至 Listeners 集合。不過，您可以經由程式設計方式將多個完全相同的接聽程式加入至 Listeners 集合中。

initializeData 屬性的值視您建立的接聽程式類型而定。並非所有的接聽程式都會要求您指定 initializeData。

注意事項：
當您使用 initializeData 屬性時，可能會收到下列編譯器警告訊息：「'initializeData' 屬性未宣告」。這項警告出現的原因是驗證組態設定時其對象是基底型別 TraceListener，但此基底型別無法識別 initializeData 屬性。如果追蹤接聽程式實作中包含採用參數的建構函式，您通常可以忽略這項警告。

下表顯示 .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> 項目，將接聽程式 MyListener 和 MyEventListener 加入至 Listeners 集合。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>