TraceSwitch 類別

定義

命名空間:

System.Diagnostics

組件:

System.Diagnostics.TraceSource.dll

來源:

TraceSwitch.cs

提供多層級參數來控制追蹤和偵錯輸出，而不需重新編譯程序代碼。

public ref class TraceSwitch : System::Diagnostics::Switch

public class TraceSwitch : System.Diagnostics.Switch

type TraceSwitch = class
    inherit Switch

Public Class TraceSwitch
Inherits Switch

繼承

Object

Switch

TraceSwitch

範例

下列程式代碼範例會建立新的 TraceSwitch，並使用 參數來判斷是否要列印錯誤訊息。 參數會在類別層級建立。 如果 Level 屬性設定為 TraceLevel.Error 或更新版本，MyMethod 會寫入第一個錯誤訊息。 不過，如果 Level 小於 TraceLevel.Verbose，MyMethod 不會寫入第二個錯誤訊息。

   // Class-level declaration.
   /* Create a TraceSwitch to use in the entire application.*/
private:
   static TraceSwitch^ mySwitch = gcnew TraceSwitch( "General", "Entire Application" );

public:
   static void MyMethod()
   {
      // Write the message if the TraceSwitch level is set to Error or higher.
      if ( mySwitch->TraceError )
         Console::WriteLine( "My error message." );
      
      // Write the message if the TraceSwitch level is set to Verbose.
      if ( mySwitch->TraceVerbose )
         Console::WriteLine( "My second error message." );
   }

   static void main()
   {
      // Run the method that prints error messages based on the switch level.
      MyMethod();
   }

//Class-level declaration.
/* Create a TraceSwitch to use in the entire application.*/
static TraceSwitch mySwitch = new TraceSwitch("General", "Entire Application");

static public void MyMethod()
{
    // Write the message if the TraceSwitch level is set to Error or higher.
    if (mySwitch.TraceError)
        Console.WriteLine("My error message.");

    // Write the message if the TraceSwitch level is set to Verbose.
    if (mySwitch.TraceVerbose)
        Console.WriteLine("My second error message.");
}

public static void Main(string[] args)
{
    // Run the method that prints error messages based on the switch level.
    MyMethod();
}

' Class-level declaration.
' Create a TraceSwitch to use in the entire application. 
Private Shared mySwitch As New TraceSwitch("General", "Entire Application")    

Public Shared Sub MyMethod()
    ' Write the message if the TraceSwitch level is set to Error or higher.
    If mySwitch.TraceError Then
        Console.WriteLine("My error message.")
    End If 
    ' Write the message if the TraceSwitch level is set to Verbose.
    If mySwitch.TraceVerbose Then
        Console.WriteLine("My second error message.")
    End If
End Sub

Public Shared Sub Main()
    ' Run the method that prints error messages based on the switch level.
    MyMethod()
End Sub

備註

您可以使用追蹤參數，根據訊息的重要性來篩選出訊息。 TraceSwitch 類別提供 TraceError、TraceWarning、TraceInfo和 TraceVerbose 屬性，以測試參數層級。 Level 屬性會取得或設定參數的 TraceLevel。

您可以在程式代碼中建立 TraceSwitch，並將層級直接設定為檢測特定程式代碼區段。

在僅限 .NET Framework 應用程式中，您也可以透過應用程式組態檔設定 TraceSwitch 層級，然後在應用程式中使用已設定的 TraceSwitch 層級。 在應用程式組態檔中，您可以新增或移除參數、設定參數的值，或清除應用程式先前設定的所有參數。 組態檔的格式應該像下列範例所示：

<configuration>  
  <system.diagnostics>  
    <switches>  
      <add name="mySwitch" value="1" />  
    </switches>  
  </system.diagnostics>  
</configuration>  

此組態區段會定義一個 TraceSwitch，其中 DisplayName 設定為 mySwitch，而 Level 設定為 1，其對應於列舉值 TraceLevel.Error。

注意

您也可以使用文字來指定參數的值。 例如，BooleanSwitch的 true，或代表列舉值的文字，例如 TraceSwitch的 Error。 行 <add name="mySwitch" value="Error" /> 相當於 <add name="mySwitch" value="1" />。

在您的應用程式中，您可以建立具有相同名稱的 TraceSwitch，以使用已設定的交換器層級，如下列範例所示：

private:
    static TraceSwitch^ appSwitch = gcnew TraceSwitch("mySwitch",
        "Switch in config file");

public:
    static void Main(array<String^>^ args)
    {
        //...
        Console::WriteLine("Trace switch {0} configured as {1}",
        appSwitch->DisplayName, appSwitch->Level.ToString());
        if (appSwitch->TraceError)
        {
            //...
        }
    }

private static TraceSwitch appSwitch = new TraceSwitch("mySwitch",
    "Switch in config file");

public static void Main(string[] args)
{
    //...
    Console.WriteLine("Trace switch {0} configured as {1}",
    appSwitch.DisplayName, appSwitch.Level.ToString());
    if (appSwitch.TraceError)
    {
        //...
    }
}

Private Shared appSwitch As new TraceSwitch("mySwitch", _
    "Switch in config file")

Public Shared Sub Main(args As String())
    '...
    Console.WriteLine("Trace switch {0} configured as {1}",
    appSwitch.DisplayName, appSwitch.Level.ToString())
    If appSwitch.TraceError = True  Then
        '...
    End If
End Sub

在 .NET Core 和 .NET 5+ 應用程式中，新參數的 Level 預設為 TraceLevel.Off。

在 .NET Framework 應用程式中，參數 Level 屬性預設為組態檔中指定的值。 如果 TraceSwitch 建構函式在組態檔中找不到初始參數設定，新參數 Level 預設為 TraceLevel.Off。

您必須啟用追蹤或偵錯，才能使用 參數。 下列語法是編譯程序專屬的。 如果您使用 C# 或 Visual Basic 以外的編譯程式，請參閱編譯程式的檔。

• 若要在 C# 中啟用偵錯，請在編譯程式代碼時，將 /d:DEBUG 旗標新增至編譯程式命令行，或將 #define DEBUG 新增至檔案頂端。 在 Visual Basic 中，將 /d:DEBUG=True 旗標新增至編譯程式命令行。

• 若要在 C# 中啟用追蹤，請在編譯程式代碼時，將 /d:TRACE 旗標新增至編譯程式命令行，或將 #define TRACE 新增至檔案頂端。 在 Visual Basic 中，將 /d:TRACE=True 旗標新增至編譯程式命令行。

注意

隔離使用 TraceSwitch 類別時，不需要這些偵錯和追蹤編譯程序參數。 它們只需要與條件式編譯的 Trace 或 Debug 方法搭配使用。

如需偵測應用程式的詳細資訊，請參閱 Debug 和 Trace。 如需設定與使用追蹤參數的詳細資訊，請參閱 追蹤參數。

注意

若要改善效能，您可以在類別中 staticTraceSwitch 成員。

建構函式

TraceSwitch(String, String, String)	使用參數的指定顯示名稱、描述和預設值，初始化 TraceSwitch 類別的新實例。
TraceSwitch(String, String)	使用指定的顯示名稱和描述，初始化 TraceSwitch 類別的新實例。

屬性

Attributes	取得應用程式組態檔中定義的自定義參數屬性。 (繼承來源 Switch)
DefaultValue	取得建構函式中指派的預設值。 (繼承來源 Switch)
Description	取得參數的描述。 (繼承來源 Switch)
DisplayName	取得用來識別參數的名稱。 (繼承來源 Switch)
Level	取得或設定決定參數允許之訊息的追蹤層級。
SwitchSetting	取得或設定這個參數的目前設定。 (繼承來源 Switch)
TraceError	取得值，指出參數是否允許錯誤處理訊息。
TraceInfo	取得值，指出參數是否允許參考訊息。
TraceVerbose	取得值，指出參數是否允許所有訊息。
TraceWarning	取得值，指出參數是否允許警告訊息。
Value	取得或設定 參數的值。 (繼承來源 Switch)

方法

Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetSupportedAttributes()	取得 參數支援的自定義屬性。 (繼承來源 Switch)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
OnSwitchSettingChanged()	更新並更正此參數的層級。
OnValueChanged()	將 SwitchSetting 屬性設定為與 Value 屬性相等的整數。
Refresh()	重新整理追蹤組態數據。 (繼承來源 Switch)
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)

另請參閱

• Switch
• BooleanSwitch
• TraceLevel
• Debug
• Trace