Vorgehensweise: Erstellen, Initialisieren und Konfigurieren von AblaufverfolgungsschalternHow to: Create, Initialize and Configure Trace Switches

Mit Ablaufverfolgungsschaltern können Sie die Ablaufverfolgungsausgabe aktivieren, deaktivieren und filtern.Trace switches enable you to enable, disable, and filter tracing output.

Erstellen und Initialisieren eines AblaufverfolgungsschaltersCreating and initializing a trace switch

Damit Sie Ablaufverfolgungsschalter verwenden können, müssen Sie diese zunächst erstellen und in Ihrem Code platzieren.In order to use trace switches, you must first create them and place them in your code. Es gibt zwei vordefinierte Klassen, aus denen Sie Schalterobjekte erstellen können: die System.Diagnostics.BooleanSwitch-Klasse und die System.Diagnostics.TraceSwitch-Klasse.There are two predefined classes from which you can create switch objects: the System.Diagnostics.BooleanSwitch class and the System.Diagnostics.TraceSwitch class. Sie verwenden die BooleanSwitch-Klasse, wenn Sie nur wissen möchten, ob eine Ablaufverfolgungsmeldung angezeigt oder wird oder nicht. TraceSwitch verwenden Sie, wenn Sie zwischen Ebenen für die Ablaufverfolgung unterscheiden möchten.You 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. Wenn Sie eine TraceSwitch-Instanz verwenden, können Sie eigene Debugmeldungen definieren und diese verschiedenen Ablaufverfolgungsebenen zuordnen.If you use a TraceSwitch, you can define your own debugging messages and associate them with different trace levels. Sie können beide Typen von Schaltern mit Ablaufverfolgung oder Debuggen verwenden.You can use both types of switches with either tracing or debugging. In der Standardeinstellung ist ein BooleanSwitch deaktiviert und ein TraceSwitch auf die Ebene TraceLevel.Off festgelegt.By default, a BooleanSwitch is disabled and a TraceSwitch is set to level TraceLevel.Off. Ablaufverfolgungsschalter können in jedem beliebigen Teil Ihres Codes erstellt und platziert werden, in dem sie möglicherweise verwendet werden.Trace switches can be created and placed in any part of your code that might use them.

Obwohl Sie Ablaufverfolgungsebenen und weitere Konfigurationsoptionen in Code festlegen können, empfiehlt es sich, dass Sie die Konfigurationsdatei verwenden, um den Zustand Ihrer Schalter zu verwalten.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. Grund hierfür ist, dass Sie flexibler sind, wenn Sie die Konfiguration Ihrer Schalter im Konfigurationssystem verwalten, denn Sie können verschiedene Schalter und Änderungsebenen ein-und ausschalten, ohne Ihre Anwendung erneut zu kompilieren.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.

So erstellen und initialisieren Sie einen AblaufverfolgungsschalterTo create and initialize a trace switch

  1. Definieren Sie einen Schalter entweder mit dem Typ System.Diagnostics.BooleanSwitch oder mit dem Typ System.Diagnostics.TraceSwitch, und legen Sie den Namen und die Beschreibung des Schalters fest.Define a switch as either type System.Diagnostics.BooleanSwitch or type System.Diagnostics.TraceSwitch and set the name and description of the switch.

  2. Konfigurieren Sie Ihren Ablaufverfolgungsschalter.Configure your trace switch. Weitere Informationen finden Sie unter Konfigurieren von Ablauf Verfolgungs Schaltern.For more information, see Configuring trace switches.

    Im folgenden Code werden zwei Schalter erstellt, jeweils ein Schalter jedes Typs: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");  
    

Konfigurieren von AblaufverfolgungsschalternConfiguring trace switches

Nachdem Ihre Anwendung bereitgestellt wurde, können weiterhin Ablaufverfolgungsausgabe aktivieren oder deaktivieren, indem Sie die Ablaufverfolgungsschalter in der Anwendung konfigurieren.After your application has been distributed, you can still enable or disable trace output by configuring the trace switches in your application. Konfigurieren eines Schalters bedeutet, dass sein Wert aus einer externen Quelle geändert wird, nachdem er initialisiert wurde.Configuring a switch means changing its value from an external source after it has been initialized. Sie können die Werte der Schalterobjekte mithilfe der Konfigurationsdatei ändern.You can change the values of the switch objects using the configuration file. Sie konfigurieren einen Ablaufverfolgungsschalter so, dass er aktiviert oder deaktiviert oder dass seine Ebene festgelegt wird. Dabei bestimmen Sie den Umfang und die Art der Meldungen, die der Schalter an Listener weiterleitet.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.

Ihre Schalter werden über die .config-Datei konfiguriert.Your switches are configured using the .config file. Für eine Webanwendung ist dies die "Web.config"-Datei, die dem Projekt zugeordnet ist.For a Web application, this is the Web.config file associated with the project. In einer Windows-Anwendung hat diese Datei den Namen (Anwendungsname) .exe.config. In einer bereitgestellten Anwendung muss sich diese Datei im selben Ordner befinden wie die ausführbare Datei.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.

Wenn die Anwendung den Code, der eine Instanz eines Schalters erstellt, zum ersten Mal ausführt, prüft sie die Konfigurationsdatei auf Ablaufverfolgungsebenen-Informationen zu dem angegebenen Schalter.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. Das Ablaufverfolgungssystem durchsucht die Konfigurationsdatei für jeden Schalter nur ein Mal – wenn die Anwendung den Schalter erstmalig erstellt.The tracing system examines the configuration file only once for any particular switch — the first time your application creates the switch.

In einer bereitgestellten Anwendung aktivieren Sie Ablaufverfolgungscode, indem Sie Schalterobjekte neu konfigurieren, wenn die Anwendung nicht ausgeführt wird.In a deployed application, you enable trace code by reconfiguring switch objects when your application is not running. Üblicherweise gehört hierzu Aktivieren oder Deaktivieren der Schalterobjekte oder Ändern der Ablaufverfolgungsebenen und dann Neustarten Ihrer Anwendung.Typically this involves turning the switch objects on and off or by changing the tracing levels, and then restarting your application.

Wenn Sie eine Instanz eines Schalters erstellen, initialisieren Sie diesen auch, indem Sie zwei Argumente angeben: ein displayName-Argument und ein description-Argument.When you create an instance of a switch, you also initialize it by specifying two arguments: a displayName argument and a description argument. Das displayName-Argument des Konstruktors legt die Switch.DisplayName-Eigenschaft der Switch-Klasseninstanz fest.The displayName argument of the constructor sets the Switch.DisplayName property of the Switch class instance. Der displayName ist der Name, der verwendet wird, um den Schalter in der CONFIG-Datei zu konfigurieren, und das description-Argument sollte eine kurze Beschreibung des Schalters sowie die Information zurückgeben, welche Meldungen er steuert.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.

Zusätzlich zum Angeben des Namens eines Schalters, der konfiguriert werden soll, müssen Sie auch einen Wert für den Schalter angeben.In addition to specifying the name of a switch to configure, you must also specify a value for the switch. Dieser Wert ist eine ganze Zahl.This value is an Integer. Für BooleanSwitch entspricht der Wert 0 Deaktiviert, und ein Wert ungleich 0 entspricht Aktiviert.For BooleanSwitch, a value of 0 corresponds to Off, and any nonzero value corresponds to On. Für TraceSwitch entsprechen 0,1,2,3 bzw. 4 Deaktiviert, Fehler, Warnung, Info bzw. Ausführlich.For TraceSwitch, 0,1,2,3, and 4 correspond Off, Error, Warning, Info, and Verbose, respectively. Jede Zahl, die größer als 4 ist, wird als Ausführlich, und jede Anzahl, die kleiner als 0 ist, wird als Deaktiviert angesehen.Any number greater than 4 is treated as Verbose, and any number less than zero is treated as Off.

Hinweis

In .NET Framework 2.0 können Sie Text verwenden, um den Wert eines Schalters anzugeben.In the .NET Framework version 2.0, you can use text to specify the value for a switch. Beispielsweise true für einen BooleanSwitch oder den Text, der einem Enumerationswert entspricht, etwa Error, für einen TraceSwitch.For example, true for a BooleanSwitch or the text representing an enumeration value such as Error for a TraceSwitch. Die Zeile <add name="myTraceSwitch" value="Error" /> ist gleichbedeutend mit <add name="myTraceSwitch" value="1" />.The line <add name="myTraceSwitch" value="Error" /> is equivalent to <add name="myTraceSwitch" value="1" />.

Damit Endbenutzer die Möglichkeit haben, die Ablaufverfolgungsschalter einer Anwendung konfigurieren zu können, müssen Sie eine detaillierte Dokumentation zu den Schaltern in Ihrer Anwendung bereitstellen.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. Sie sollten ausführlich beschreiben, welche Schalter welche Vorgänge steuern und wie die Schalter aktiviert und deaktiviert werden.You should detail which switches control what and how to turn them on and off. Außerdem sollten Sie Ihren Endbenutzern eine .config-Datei bereitstellen, die entsprechende Hilfen in den Kommentaren enthält.You should also provide your end user with a .config file that has appropriate Help in the comments.

So konfigurieren Sie AblaufverfolgungsschalterTo configure trace switches

  1. Um Ablaufverfolgungsschalter zu verwenden, müssen Sie diese zuerst erstellen und sie, wie im Abschnitt Erstellen und Initialisieren eines Ablaufverfolgungsschalters beschrieben, in Ihrem Code platzieren.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. Enthält Ihr Projekt keine Konfigurationsdatei („app.config“ oder „Web.config“), dann wählen Sie im Menü Projekt den Befehl Neues Element hinzufügen aus.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: Klicken Sie im Dialogfeld Neues Element hinzufügen auf Anwendungskonfigurationsdatei.Visual Basic: In the Add New Item dialog box, choose Application Configuration File.

      Die Anwendungskonfigurationsdatei wird erstellt und geöffnet.The application configuration file is created and opened. Diese Datei ist ein XML-Dokument mit dem Stammelement <configuration>.This is an XML document whose root element is <configuration>.

    • Visual C#: Klicken Sie im Dialogfeld Neues Element hinzufügen auf XML-Datei.Visual C#: In the Add New Item dialog box, choose XML File. Benennen Sie diese Datei app.config. Fügen Sie im XML-Editor nach der XML-Deklaration den folgenden XML-Code hinzu:Name this file app.config. In the XML editor, after the XML declaration, add the following XML:

      <configuration>  
      </configuration>  
      

      Nachdem das Projekt kompiliert ist, wird die Datei „app.config“ in den Projektausgabeordner kopiert und in „Anwendungsname.exe.config“ umbenannt.When your project is compiled, the app.config file is copied to the project output folder and is renamed applicationname.exe.config.

  3. Fügen Sie nach dem <configuration>-Tag, aber vor dem </configuration>-Tag, die entsprechende XML ein, um die Schalter zu konfigurieren.After the <configuration> tag but before the </configuration> tag, add the appropriate XML to configure your switches. In den folgenden Beispielen werden ein BooleanSwitch mit einer DisplayName-Eigenschaft von DataMessageSwitch und ein TraceSwitch mit einer DisplayName-Eigenschaft von TraceLevelSwitch veranschaulicht.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 dieser Konfiguration sind beide Schalter deaktiviert.In this configuration, both switches are off.

  4. Wenn Sie einen BooleanSwitch, wie DataMessagesSwitch im vorhergehenden Beispiel, aktivieren möchten, ändern Sie den Wert in eine beliebige ganze Zahl ungleich 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. Wenn Sie einen TraceSwitch, wie TraceLevelSwitch im vorhergehenden Beispiel, aktivieren möchten, ändern Sie den Wert in die entsprechende Ebeneneinstellung (1 bis 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. Fügen Sie der .config-Datei Kommentare hinzu , damit der Benutzer genau weiß, welche Werte geändert werden müssen, damit die Schalter geeignet konfiguriert sind.Add comments to the .config file so the end user has a clear understanding of what values to change to configure the switches appropriately.

    Im folgenden Beispiel wird gezeigt, wie der endgültige Code einschließlich der Kommentare aussehen könnte: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>  
    

Siehe auchSee also