Trace 類別

定義

提供一組可協助您追蹤程式碼執行的方法與屬性。Provides a set of methods and properties that help you trace the execution of your code. 此類別無法獲得繼承。This class cannot be inherited.

public ref class Trace sealed
public sealed class Trace
type Trace = class
Public NotInheritable Class Trace
繼承
Trace

範例

下列範例會使用 Trace 來指出程式執行的開頭和結尾。The following example uses Trace to indicate the beginning and the end of a program's execution. 此範例也會使用 Trace.IndentTrace.Unindent 方法來區別追蹤輸出。The example also uses the Trace.Indent and Trace.Unindent methods to distinguish the tracing output. 如需使用的更完整範例 Trace ,請參閱 如何:將追蹤語句加入至應用程式程式碼For a more complete example of the use of Trace, see How to: Add Trace Statements to Application Code.

// Specify /DTRACE when compiling.

#using <System.dll>
using namespace System;
using namespace System::Diagnostics;

int main()
{
   #if defined(TRACE)
   Trace::Listeners->Add( gcnew TextWriterTraceListener( Console::Out ) );
   Trace::AutoFlush = true;
   Trace::Indent();
   Trace::WriteLine( "Entering Main" );
   #endif
   Console::WriteLine( "Hello World." );
   #if defined(TRACE)
   Trace::WriteLine( "Exiting Main" );
   Trace::Unindent();
   #endif
   return 0;
}
// Specify /d:TRACE when compiling.

using System;
using System.Diagnostics;

class Test
{
    static void Main()
    {
       Trace.Listeners.Add(new TextWriterTraceListener(Console.Out));
       Trace.AutoFlush = true;
       Trace.Indent();
       Trace.WriteLine("Entering Main");
       Console.WriteLine("Hello World.");
       Trace.WriteLine("Exiting Main");
       Trace.Unindent();
    }
}
' Specify /d:TRACE=True when compiling.

Imports System.Diagnostics

Class Test
    
    Shared Sub Main()
    
        Trace.Listeners.Add(New TextWriterTraceListener(Console.Out))
        Trace.AutoFlush = True
        Trace.Indent()
        Trace.WriteLine("Entering Main")
        Console.WriteLine("Hello World.")
        Trace.WriteLine("Exiting Main")
        Trace.Unindent()
        
    End Sub

End Class

備註

您可以使用類別中的屬性和方法 Trace 來檢測發行組建。You can use the properties and methods in the Trace class to instrument release builds. 檢測可讓您監視應用程式在實際執行設定中執行的健康情況。Instrumentation allows you to monitor the health of your application running in real-life settings. 追蹤可協助您找出問題並加以修正,而不會干擾執行中的系統。Tracing helps you isolate problems and fix them without disturbing a running system.

這個類別會提供方法來顯示 Assert 對話方塊,併發出永遠為的判斷提示 FailThis class provides methods to display an Assert dialog box, and to emit an assertion that will always Fail. 此類別提供下列變化的寫入方法: WriteWriteLineWriteIfWriteLineIfThis class provides write methods in the following variations: Write, WriteLine, WriteIf, and WriteLineIf.

BooleanSwitchTraceSwitch 類別提供動態控制追蹤輸出的方法。The BooleanSwitch and TraceSwitch classes provide means to dynamically control the tracing output. 您可以修改這些參數的值,而不需要重新編譯應用程式。You can modify the values of these switches without recompiling your application. 如需使用設定檔設定參數的詳細資訊,請參閱 Switch 類別和 how To:建立、初始化和設定追蹤參數 主題。For information on using the configuration file to set a switch, see the Switch class and the How to: Create, Initialize and Configure Trace Switches topic.

您可以藉由在 TraceListener 集合中加入或移除實例,來自訂追蹤輸出的目標 ListenersYou can customize the tracing output's target by adding TraceListener instances to or removing instances from the Listeners collection. Listeners集合是由和類別共用, DebugTrace 將追蹤接聽程式加入至這兩個類別都會將接聽程式新增至兩者。The Listeners collection is shared by both the Debug and the Trace classes; adding a trace listener to either class adds the listener to both. 根據預設,追蹤輸出會使用類別發出 DefaultTraceListenerBy default, trace output is emitted using the DefaultTraceListener class.

注意

如果無法使用追蹤接聽程式所使用的資源,則將追蹤接聽程式加入至 Listeners 集合可能會在追蹤時擲回例外狀況。Adding a trace listener to the Listeners collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. 擲回的條件和例外狀況取決於追蹤接聽項,而且無法在本主題中列舉。The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. Trace在區塊中呼叫方法 try / catch 來偵測並處理來自追蹤接聽程式的任何例外狀況,可能會很有用。It may be useful to place calls to the Trace methods in try/catch blocks to detect and handle any exceptions from trace listeners.

注意

如果您將追蹤接聽程式加入至部分信任的程式碼,您將會收到 SecurityException 例外狀況,因為加入追蹤接聽項需要 UnmanagedCode 許可權。If you add trace listeners to partially trusted code, you will get a SecurityException exception, because adding trace listeners requires UnmanagedCode permission. 若要追蹤 Visual Studio 的沙箱中執行的部分信任程式碼,請勿加入追蹤接聽項。To trace partially trusted code that is running in a sandbox in Visual Studio, do not add trace listeners. 相反地,請 Trace Debug 在 [ 輸出 ] 視窗中查看和訊息。Instead, view the Trace and Debug messages in the Output window.

Trace類別提供屬性,以取得或設定的層級 IndentIndentSize 和是否要 AutoFlush 在每次寫入之後進行。The Trace class provides properties to get or set the level of Indent, the IndentSize, and whether to AutoFlush after each write.

若要設定 AutoFlushIndentSize Trace ,您可以編輯對應至您的應用程式名稱的設定檔。To set the AutoFlush and IndentSize for Trace, you can edit the configuration file that corresponds to the name of your application. 設定檔的格式應該如下列範例所示:The configuration file should be formatted like the following example:

<configuration>  
  <system.diagnostics>  
    <trace autoflush="false" indentsize="3" />  
  </system.diagnostics>  
</configuration>  

ConditionalAttribute屬性會套用至的方法 TraceThe ConditionalAttribute attribute is applied to the methods of Trace. ConditionalAttribute除非「追蹤」定義為條件式編譯符號,否則支援略過這些方法呼叫的編譯器。Compilers that support ConditionalAttribute ignore calls to these methods unless "TRACE" is defined as a conditional compilation symbol. 請參閱編譯器的檔,以判斷是否 ConditionalAttribute 支援,以及定義條件式編譯符號的語法。Refer to a compiler's documentation to determine whether ConditionalAttribute is supported and the syntax for defining a conditional compilation symbol.

注意

在 Visual Studio 專案中,根據預設,會針對 debug 組建定義 "DEBUG" 條件式編譯符號,並針對 debug 和 release 組建定義 "TRACE" 符號。In Visual Studio projects, by default, the "DEBUG" conditional compilation symbol is defined for debug builds, and the "TRACE" symbol is defined for both debug and release builds. 如需有關如何停用此行為的詳細資訊,請參閱 Visual Studio 檔。For information about how to disable this behavior, see the Visual Studio documentation.

若要在 c # 中定義「追蹤」條件式編譯符號,請在 /d:TRACE 使用命令列編譯器代碼時,將選項新增至編譯器命令列,或新增 #define TRACE 至檔案頂端。To define the "TRACE" conditional compilation symbol in C#, add the /d:TRACE option to the compiler command line when you compile your code using a command line, or add #define TRACE to the top of your file. 在 Visual Basic 中,將 /d:TRACE=True 選項新增至編譯器命令列或新增 #Const TRACE=True 至檔案。In Visual Basic, add the /d:TRACE=True option to the compiler command line or add #Const TRACE=True to the file.

ConditionalAttribute c + + 編譯器不支援。ConditionalAttribute is not supported by the C++ compiler. 若要提供對等的功能,您必須在區塊中括住方法的呼叫 Trace #if defined(TRACE) ... #endif ,並將 /DTRACE 選項新增至編譯器命令列,或加入 #define TRACE 至檔案。To provide equivalent functionality, you must enclose calls to the methods of Trace in an #if defined(TRACE) ... #endif block, and add the /DTRACE option to the compiler command line or add #define TRACE to the file.

屬性

AutoFlush

取得或設定每次寫入後是否應該在 Listeners 上呼叫 Flush()Gets or sets whether Flush() should be called on the Listeners after every write.

CorrelationManager

取得這項追蹤的執行緒相關管理員。Gets the correlation manager for the thread for this trace.

IndentLevel

取得或設定縮排層級。Gets or sets the indent level.

IndentSize

取得或設定縮排的空格數目。Gets or sets the number of spaces in an indent.

Listeners

取得正在監視追蹤輸出的接聽程式集合。Gets the collection of listeners that is monitoring the trace output.

UseGlobalLock

取得或設定值,這個值表示是否應該使用全域鎖定。Gets or sets a value indicating whether the global lock should be used.

方法

Assert(Boolean)

檢查條件;如果條件為 false,則顯示訊息方塊,該方塊會顯示呼叫堆疊。Checks for a condition; if the condition is false, displays a message box that shows the call stack.

Assert(Boolean, String)

檢查條件;如果條件為 false,則輸出指定的訊息,並顯示訊息方塊,該方塊會顯示呼叫堆疊。Checks for a condition; if the condition is false, outputs a specified message and displays a message box that shows the call stack.

Assert(Boolean, String, String)

檢查條件;如果條件為 false,則輸出兩個指定的訊息,並顯示訊息方塊,該方塊會顯示呼叫堆疊。Checks for a condition; if the condition is false, outputs two specified messages and displays a message box that shows the call stack.

Close()

清除輸出緩衝區,然後關閉 ListenersFlushes the output buffer, and then closes the Listeners.

Equals(Object)

判斷指定的物件是否等於目前的物件。Determines whether the specified object is equal to the current object.

(繼承來源 Object)
Fail(String)

發出指定的錯誤訊息。Emits the specified error message.

Fail(String, String)

會發出錯誤訊息以及詳細的錯誤訊息。Emits an error message, and a detailed error message.

Flush()

清除輸出緩衝區,讓緩衝的資料寫入 ListenersFlushes the output buffer, and causes buffered data to be written to the Listeners.

GetHashCode()

做為預設雜湊函式。Serves as the default hash function.

(繼承來源 Object)
GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(繼承來源 Object)
Indent()

將目前的 IndentLevel 加一。Increases the current IndentLevel by one.

MemberwiseClone()

建立目前 Object 的淺層複製。Creates a shallow copy of the current Object.

(繼承來源 Object)
Refresh()

重新整理追蹤組態資料。Refreshes the trace configuration data.

ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(繼承來源 Object)
TraceError(String)

使用指定的訊息,將錯誤訊息寫入 Listeners 集合中的追蹤接聽項。Writes an error message to the trace listeners in the Listeners collection using the specified message.

TraceError(String, Object[])

使用指定的物件陣列和格式化資訊,將錯誤訊息寫入 Listeners 集合中的接聽項。Writes an error message to the trace listeners in the Listeners collection using the specified array of objects and formatting information.

TraceInformation(String)

使用指定的訊息,將告知性訊息寫入 Listeners 集合中的追蹤接聽程式。Writes an informational message to the trace listeners in the Listeners collection using the specified message.

TraceInformation(String, Object[])

使用指定的物件陣列和格式化資訊,將告知性訊息寫入 Listeners 集合中的追蹤接聽程式。Writes an informational message to the trace listeners in the Listeners collection using the specified array of objects and formatting information.

TraceWarning(String)

使用指定的訊息,將警告訊息寫入 Listeners 集合中的追蹤接聽項。Writes a warning message to the trace listeners in the Listeners collection using the specified message.

TraceWarning(String, Object[])

使用指定的物件陣列和格式化資訊,將警告訊息寫入 Listeners 集合中的追蹤接聽項。Writes a warning message to the trace listeners in the Listeners collection using the specified array of objects and formatting information.

Unindent()

將目前的 IndentLevel 減少一。Decreases the current IndentLevel by one.

Write(Object)

將物件的 ToString() 方法值寫入 Listeners 集合中的追蹤接聽項。Writes the value of the object's ToString() method to the trace listeners in the Listeners collection.

Write(Object, String)

將物件之 ToString() 方法的分類名稱和值寫入 Listeners 集合中的追蹤接聽項。Writes a category name and the value of the object's ToString() method to the trace listeners in the Listeners collection.

Write(String)

將訊息寫入 Listeners 集合中的追蹤接聽項。Writes a message to the trace listeners in the Listeners collection.

Write(String, String)

將分類名稱和訊息寫入 Listeners 集合中的追蹤接聽項。Writes a category name and a message to the trace listeners in the Listeners collection.

WriteIf(Boolean, Object)

如果條件為 true,則將物件的 ToString() 方法值寫入 Listeners 集合中的追蹤接聽項。Writes the value of the object's ToString() method to the trace listeners in the Listeners collection if a condition is true.

WriteIf(Boolean, Object, String)

如果條件為 true,則將物件之 ToString() 方法的分類名稱和值寫入 Listeners 集合中的追蹤接聽項。Writes a category name and the value of the object's ToString() method to the trace listeners in the Listeners collection if a condition is true.

WriteIf(Boolean, String)

如果條件為 true,則將訊息寫入 Listeners 集合中的追蹤接聽項。Writes a message to the trace listeners in the Listeners collection if a condition is true.

WriteIf(Boolean, String, String)

如果條件是 true,則將分類名稱和訊息寫入 Listeners 集合中的追蹤接聽項。Writes a category name and message to the trace listeners in the Listeners collection if a condition is true.

WriteLine(Object)

將物件的 ToString() 方法值寫入 Listeners 集合中的追蹤接聽項。Writes the value of the object's ToString() method to the trace listeners in the Listeners collection.

WriteLine(Object, String)

將物件之 ToString() 方法的分類名稱和值寫入 Listeners 集合中的追蹤接聽項。Writes a category name and the value of the object's ToString() method to the trace listeners in the Listeners collection.

WriteLine(String)

將訊息寫入 Listeners 集合中的追蹤接聽項。Writes a message to the trace listeners in the Listeners collection.

WriteLine(String, String)

將分類名稱和訊息寫入 Listeners 集合中的追蹤接聽項。Writes a category name and message to the trace listeners in the Listeners collection.

WriteLineIf(Boolean, Object)

如果條件為 true,則將物件的 ToString() 方法值寫入 Listeners 集合中的追蹤接聽項。Writes the value of the object's ToString() method to the trace listeners in the Listeners collection if a condition is true.

WriteLineIf(Boolean, Object, String)

如果條件為 true,則將物件之 ToString() 方法的分類名稱和值寫入 Listeners 集合中的追蹤接聽項。Writes a category name and the value of the object's ToString() method to the trace listeners in the Listeners collection if a condition is true.

WriteLineIf(Boolean, String)

如果條件為 true,則將訊息寫入 Listeners 集合中的追蹤接聽項。Writes a message to the trace listeners in the Listeners collection if a condition is true.

WriteLineIf(Boolean, String, String)

如果條件是 true,則將分類名稱和訊息寫入 Listeners 集合中的追蹤接聽項。Writes a category name and message to the trace listeners in the Listeners collection if a condition is true.

適用於

執行緒安全性

此型別具備執行緒安全。This type is thread safe.

另請參閱