如何:创建、初始化和配置跟踪开关How to: Create, Initialize and Configure Trace Switches

跟踪开关用于启用、禁用和筛选跟踪输出。Trace switches enable you to enable, disable, and filter tracing output.

创建和初始化跟踪开关Creating and initializing a trace switch

为了使用跟踪开关,必须首先创建跟踪开关并将其放置在代码中。In order to use trace switches, you must first create them and place them in your code. 有两种预定义的类可用于创建开关对象:System.Diagnostics.BooleanSwitch 类和 System.Diagnostics.TraceSwitch 类。There are two predefined classes from which you can create switch objects: the System.Diagnostics.BooleanSwitch class and the System.Diagnostics.TraceSwitch class. 如果您只关心跟踪消息是否出现,应使用 BooleanSwitch;如果您需要区别不同的跟踪级别,应使用 TraceSwitchYou would use BooleanSwitch if you care only about whether or not a tracing message appears; you would use TraceSwitch if you want to discriminate between levels of tracing. 如果使用 TraceSwitch,则可以定义您自己的调试消息并将其与不同的跟踪级别相关联。If you use a TraceSwitch, you can define your own debugging messages and associate them with different trace levels. 您可以将这两种开关用于跟踪或调试。You can use both types of switches with either tracing or debugging. 默认情况下,将禁用 BooleanSwitch,并将 TraceSwitch 设置为 TraceLevel.Off 级别。By default, a BooleanSwitch is disabled and a TraceSwitch is set to level TraceLevel.Off. 可在任何需要使用跟踪开关的位置创建和放置跟踪开关。Trace switches can be created and placed in any part of your code that might use them.

虽然可以在代码中设置跟踪级别和其他配置选项,但最好使用配置文件来管理开关的状态。Although you can set trace levels and other configuration options in code, we recommend that you use the configuration file to manage the state of your switches. 这是因为,通过配置系统管理开关配置可获得较大的灵活性,您无需重新编译应用程序,就可以打开和关闭各个开关并更改级别。This is because managing the configuration of your switches in the configuration system gives you greater flexibility — you can turn on and off various switches and change levels without recompiling your application.

若要创建和初始化跟踪开关To create and initialize a trace switch

  1. 将开关定义为 System.Diagnostics.BooleanSwitch 类型或 System.Diagnostics.TraceSwitch 类型并设置开关的名称和说明。Define a switch as either type System.Diagnostics.BooleanSwitch or type System.Diagnostics.TraceSwitch and set the name and description of the switch.

  2. 配置跟踪开关。Configure your trace switch. 有关详细信息,请参阅配置跟踪开关For more information, see Configuring trace switches.

    以下代码创建两个开关,每种类型一个开关:The following code creates two switches, one of each type:

    Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")  
    Dim generalSwitch As New TraceSwitch("General", "Entire application")  
    
    System.Diagnostics.BooleanSwitch dataSwitch =   
       new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");  
    System.Diagnostics.TraceSwitch generalSwitch =   
       new System.Diagnostics.TraceSwitch("General",   
       "Entire application");  
    

配置跟踪开关Configuring trace switches

分发应用程序后,你仍可以通过在应用程序中配置跟踪开关来启用或禁用跟踪输出。After your application has been distributed, you can still enable or disable trace output by configuring the trace switches in your application. 配置一个开关意味着在其初始化后,从外部源中更改其值。Configuring a switch means changing its value from an external source after it has been initialized. 可以使用配置文件更改开关对象的值。You can change the values of the switch objects using the configuration file. 配置跟踪开关,可以将其打开和关闭,或设置其级别,从而确定它传递到侦听器的消息量和消息类型。You configure a trace switch to turn it on and off, or to set its level, determining the amount and type of messages it passes along to listeners.

使用 .config 文件配置开关。Your switches are configured using the .config file. 对于 Web 应用程序,这是与项目关联的 Web.config 文件。For a Web application, this is the Web.config file associated with the project. 在 Windows 应用程序中,此文件名为(应用程序名称).exe.config。在已部署的应用程序中,此文件必须与可执行文件驻留在相同的文件夹中。In a Windows application, this file is named (application name).exe.config. In a deployed application, this file must reside in the same folder as the executable.

应用程序执行首次创建交换机的实例的代码时,它会检查有关命名开关跟踪级别信息的配置文件。When your application executes the code that creates an instance of a switch for the first time, it checks the configuration file for trace-level information about the named switch. 跟踪系统仅为任一特定的开关检查一次配置文件 — 即应用程序首次创建开关时。The tracing system examines the configuration file only once for any particular switch — the first time your application creates the switch.

在已部署的应用程序中,应用程序未运行时重新配置开关对象可启用跟踪代码。In a deployed application, you enable trace code by reconfiguring switch objects when your application is not running. 通常,这涉及到打开和关闭开关对象或更改跟踪级别,然后重新启动应用程序。Typically this involves turning the switch objects on and off or by changing the tracing levels, and then restarting your application.

创建开关实例时,还可以通过指定 displayName 和 description 这两个参数来初始化此实例。When you create an instance of a switch, you also initialize it by specifying two arguments: a displayName argument and a description argument. 构造函数的 displayName 参数设置 Switch 类实例的 Switch.DisplayName 属性。The displayName argument of the constructor sets the Switch.DisplayName property of the Switch class instance. displayName 是用于在 .config 文件中配置开关的名称,description 参数应返回开关及其所控制的消息的简要说明。The displayName is the name that is used to configure the switch in the .config file, and the description argument should return a brief description of the switch and what messages it controls.

除了指定要配置的开关名称,还必须指定此开关的值。In addition to specifying the name of a switch to configure, you must also specify a value for the switch. 此值是一个整数。This value is an Integer. 对于 BooleanSwitch,0 值对应“关闭”,而任何非零值对应“打开”。For BooleanSwitch, a value of 0 corresponds to Off, and any nonzero value corresponds to On. 对于 TraceSwitch,0、1、2、3 和 4 分别对应“关闭”、“错误”、“警告”、“信息”和“详细”。For TraceSwitch, 0,1,2,3, and 4 correspond Off, Error, Warning, Info, and Verbose, respectively. 任何大于 4 的数字将被视为“详细”,而任何小于零的数字将被视为“关闭”。Any number greater than 4 is treated as Verbose, and any number less than zero is treated as Off.

备注

在 .NET Framework 2.0 版中,你可以使用文本指定开关值。In the .NET Framework version 2.0, you can use text to specify the value for a switch. 例如,为 BooleanSwitch 指定 true 或表示枚举值的文本,例如为 TraceSwitch 指定 ErrorFor example, true for a BooleanSwitch or the text representing an enumeration value such as Error for a TraceSwitch. <add name="myTraceSwitch" value="Error" /> 等于 <add name="myTraceSwitch" value="1" />The line <add name="myTraceSwitch" value="Error" /> is equivalent to <add name="myTraceSwitch" value="1" />.

为了使最终用户能够配置应用程序的跟踪开关,你必须提供关于应用程序中开关的详细文档。In order for end users to be able to configure an application's trace switches, you must provide detailed documentation on the switches in your application. 应该详细说明哪些开关控制哪些内容以及如何将其打开和关闭。You should detail which switches control what and how to turn them on and off. 应向你的最终用户提供 .config 文件,此文件在注释中具有适当的帮助。You should also provide your end user with a .config file that has appropriate Help in the comments.

配置跟踪开关To configure trace switches

  1. 要使用跟踪开关,必须根据创建和初始化跟踪开关中所述的内容首先创建跟踪开关,然后将它们放入代码中。In order to use trace switches, you must first create them and place them in your code as described in the section Creating and initializing a trace switch.

  2. 如果项目不包含配置文件(app.config 或 Web.config),则从“项目”菜单中选择“添加新项”。If your project does not contain a configuration file (app.config or Web.config), then from the Project menu, select Add New Item.

    • Visual Basic: 在 "添加新项" 对话框中,选择 "应用程序配置文件"。Visual Basic: In the Add New Item dialog box, choose Application Configuration File.

      创建并打开应用程序配置文件。The application configuration file is created and opened. 这是一个根元素为 <configuration>. 的 XML 文档This is an XML document whose root element is <configuration>.

    • 视觉C#对象: 在 "添加新项" 对话框中,选择 " XML 文件"。Visual C#: In the Add New Item dialog box, choose XML File. 将此文件命名为 app.config。XML 编辑器中,在 XML 声明后,添加以下 XML:Name this file app.config. In the XML editor, after the XML declaration, add the following XML:

      <configuration>  
      </configuration>  
      

      编译项目后,app.config 文件会被复制到项目输出文件夹中,并重命名为 applicationname.exe.config。When your project is compiled, the app.config file is copied to the project output folder and is renamed applicationname.exe.config.

  3. <configuration> 标记之后但在 </configuration> 标记前面,添加适当的 XML 以配置开关。After the <configuration> tag but before the </configuration> tag, add the appropriate XML to configure your switches. 以下示例演示了一个 DisplayName 属性为 DataMessageSwitch 的 BooleanSwitch,以及一个 DisplayName 属性为 TraceLevelSwitch 的 TraceSwitch。The following examples demonstrate a BooleanSwitch with a DisplayName property of DataMessageSwitch and a TraceSwitch with a DisplayName property of TraceLevelSwitch.

    <system.diagnostics>  
       <switches>  
          <add name="DataMessagesSwitch" value="0" />  
          <add name="TraceLevelSwitch" value="0" />  
       </switches>  
    </system.diagnostics>  
    

    在此配置中,两个开关均为关闭。In this configuration, both switches are off.

  4. 如果需要开启 BooleanSwitch,如前面示例中所示的 DataMessagesSwitch,请将“Value”更改为 0 以外的任何整数。If you need to turn on a BooleanSwitch, such as DataMessagesSwitch shown in the previous example, change the Value to any integer other than 0.

  5. 如果需要开启 TraceSwitch,如前面示例中所示的 TraceLevelSwitch,请将“Value”更改为适当的级别设置 (1-4)。If you need to turn on a TraceSwitch, such as TraceLevelSwitch shown in the previous example, change the Value to the appropriate level setting (1 to 4).

  6. 将注释添加到 .config 文件,以便最终用户清楚地了解适当地配置开关所需更改的值。Add comments to the .config file so the end user has a clear understanding of what values to change to configure the switches appropriately.

    以下示例显示最终代码(包括注释):The following example shows how the final code, including comments, might look:

    <system.diagnostics>  
       <switches>  
          <!-- This switch controls data messages. In order to receive data   
             trace messages, change value="0" to value="1" -->  
          <add name="DataMessagesSwitch" value="0" />  
          <!-- This switch controls general messages. In order to   
             receive general trace messages change the value to the   
             appropriate level. "1" gives error messages, "2" gives errors   
             and warnings, "3" gives more detailed error information, and   
             "4" gives verbose trace information -->  
          <add name="TraceLevelSwitch" value="0" />  
       </switches>  
    </system.diagnostics>  
    

请参阅See also