TraceSwitch 类

定义

命名空间:

System.Diagnostics

程序集:

System.Diagnostics.TraceSource.dll

Source:

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