Gewusst wie: Erstellen, Initialisieren und Konfigurieren von Tracing-Schaltern

Mit Schaltern zur Ablaufverfolgung können Sie die Ablaufverfolgungsausgabe aktivieren, deaktivieren und filtern.

Erstellen und Initialisieren eines Trace-Schalters

Um Ablaufverfolgungsschalter nutzen zu können, müssen Sie sie zuerst erstellen und in Ihrem Code platzieren. Es gibt zwei vordefinierte Klassen, aus denen Sie Switch-Objekte erstellen können: die System.Diagnostics.BooleanSwitch Klasse und die System.Diagnostics.TraceSwitch Klasse. Sie würden verwenden BooleanSwitch , wenn Sie sich nur darum kümmern, ob eine Ablaufverfolgungsnachricht angezeigt wird. Sie würden verwenden TraceSwitch , wenn Sie zwischen Ablaufverfolgungsebenen diskriminieren möchten. Wenn Sie ein TraceSwitchBeispiel verwenden, können Sie eigene Debugnachrichten definieren und sie verschiedenen Ablaufverfolgungsebenen zuordnen. Sie können beide Arten von Schaltern mit Tracing oder Debugging verwenden. Standardmäßig ist ein BooleanSwitch Wert deaktiviert und ein TraceSwitch Wert auf Ebene TraceLevel.Offfestgelegt. Ablaufverfolgungsschalter können erstellt und in einem beliebigen Teil Ihres Codes platziert werden, der sie möglicherweise verwendet.

Obwohl Sie Tracing-Ebenen und andere Konfigurationsoptionen im Code festlegen können, empfehlen wir, dass Sie die Konfigurationsdatei zum Verwalten des Zustands Ihrer Switches verwenden. Dies liegt daran, dass Die Verwaltung der Konfiguration Ihrer Switches im Konfigurationssystem Ihnen eine größere Flexibilität bietet – Sie können verschiedene Schalter aktivieren und deaktivieren und Ebenen ändern, ohne Ihre Anwendung neu zu kompilieren.

So erstellen und initialisieren Sie einen Trace-Schalter

1. Definieren Sie einen Schalter als Typ System.Diagnostics.BooleanSwitch oder Typ System.Diagnostics.TraceSwitch , und legen Sie den Namen und die Beschreibung der Option fest.

2. Konfigurieren Sie den Traceschalter. Weitere Informationen finden Sie unter Konfigurieren von Ablaufverfolgungsschaltern.

   Der folgende Code erstellt zwei Schalter, einen der einzelnen Typen:

   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 Ablaufverfolgungsschaltern

Nachdem Ihre Anwendung verteilt wurde, können Sie die Ablaufverfolgungsausgabe weiterhin aktivieren oder deaktivieren, indem Sie die Ablaufverfolgungsschalter in Ihrer Anwendung konfigurieren. Das Konfigurieren eines Schalters bedeutet, dass der Wert aus einer externen Quelle geändert wird, nachdem er initialisiert wurde. Sie können die Werte der Switch-Objekte mithilfe der Konfigurationsdatei ändern. Sie konfigurieren einen Trace-Schalter, um ihn ein- oder auszuschalten oder seine Ebene festzulegen, um die Art und Menge der Nachrichten zu bestimmen, die er an die Listener übergibt.

Ihre Switches werden mithilfe der .config Datei konfiguriert. Bei einer Webanwendung ist dies die Web.config Datei, die dem Projekt zugeordnet ist. In einer Windows-Anwendung heißt diese Datei (Anwendungsname).exe.config. In einer bereitgestellten Anwendung muss sich diese Datei im selben Ordner wie die ausführbare Datei befinden.

Wenn Ihre Anwendung den Code ausführt, der eine Instanz eines Switches zum ersten Mal erstellt, überprüft sie die Konfigurationsdatei auf Informationen auf Ablaufverfolgungsebene über den benannten Switch. Das Ablaufverfolgungssystem untersucht die Konfigurationsdatei nur einmal für einen bestimmten Switch – das erste Mal, wenn die Anwendung den Switch erstellt.

In einer bereitgestellten Anwendung aktivieren Sie Tracing-Code, indem Sie die Switch-Objekte neu konfigurieren, wenn Ihre Anwendung nicht ausgeführt wird. In der Regel müssen Sie die Schalterobjekte ein- bzw. ausschalten oder die Protokollierungsebenen ändern, und dann die Anwendung neu starten.

Wenn Sie eine Instanz eines Schalters erstellen, initialisieren Sie sie auch, indem Sie zwei Argumente angeben: ein displayName-Argument und ein Beschreibungsargument . Das DisplayName-Argument des Konstruktors legt die Switch.DisplayName Eigenschaft der Switch Klasseninstanz fest. Der displayName ist der Name, der zum Konfigurieren des Schalters in der datei .config verwendet wird, und das Beschreibungsargument sollte eine kurze Beschreibung des Schalters und dessen Steuerelemente zurückgeben.

Zusätzlich zum Angeben des Namens einer zu konfigurierenden Option müssen Sie auch einen Wert für den Switch angeben. Dieser Wert ist eine ganze Zahl. Für BooleanSwitch entspricht ein Wert von 0 Aus und ein beliebiger von null verschiedener Wert entspricht Ein. Für TraceSwitch, 0,1,2,3 und 4 entsprechen Off, Error, Warning, Info und Ausführlich. Jede Zahl, die größer als 4 ist, wird als Verbose behandelt, und jede Zahl, die kleiner als 0 ist, wird als Off behandelt.

Damit Endbenutzer die Ablaufverfolgungsschalter einer Anwendung konfigurieren können, müssen Sie detaillierte Dokumentation zu den Schaltern in Ihrer Anwendung bereitstellen. Sie sollten detailliert angeben, welche Schalter steuern, was und wie sie aktiviert und deaktiviert werden sollen. Außerdem sollten Sie Ihren Endbenutzern eine .config Datei mit entsprechender Hilfe in den Kommentaren bereitstellen.

So konfigurieren Sie Ablaufverfolgungsschalter

1. Um Ablaufverfolgungsschalter verwenden zu können, müssen Sie sie zuerst erstellen und in Ihrem Code platzieren, wie im Abschnitt Erstellen und Initialisieren eines Ablaufverfolgungsschalters beschrieben.

2. Wenn Ihr Projekt keine Konfigurationsdatei (app.config oder Web.config) enthält, wählen Sie dann im Menü "Projekt " die Option "Neues Element hinzufügen" aus.

   • Visual Basic: Wählen Sie im Dialogfeld " Neues Element hinzufügen " die Option Anwendungskonfigurationsdatei aus.

     Die Anwendungskonfigurationsdatei wird erstellt und geöffnet. Dies ist ein XML-Dokument, dessen Stammelement <configuration>.

   • Visual C#: Wählen Sie im Dialogfeld " Neues Element hinzufügen " die Option "XML-Datei" aus. Nennen Sie diese Datei app.config. Fügen Sie im XML-Editor nach der XML-Deklaration den folgenden XML-Code hinzu:

     <configuration>
     </configuration>
     

     Wenn Ihr Projekt kompiliert wird, wird die app.config-Datei in den Projektausgabeordner kopiert und in applicationname.exe.config umbenannt.

3. Fügen Sie nach dem <configuration> Tag, aber vor dem </configuration> Tag die entsprechende XML-Datei hinzu, um Ihre Switches zu konfigurieren. Die folgenden Beispiele zeigen einen BooleanSwitch mit einer DisplayName-Eigenschaft von DataMessageSwitch und einen TraceSwitch mit einer DisplayName-Eigenschaft von TraceLevelSwitch.

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

   In dieser Konfiguration sind beide Schalter deaktiviert.

4. Wenn Sie einen BooleanSwitch aktivieren müssen, wie im vorherigen Beispiel gezeigt, ändern Sie den Wert in eine andere ganze Zahl als 0.

5. Wenn Sie einen TraceSwitch aktivieren müssen, wie im vorherigen Beispiel gezeigt, ändern Sie den Wert in die entsprechende Leveleinstellung (1 bis 4).

6. Fügen Sie der .config-Datei Kommentare hinzu, damit der Endbenutzer klar verstehen kann, welche Werte geändert werden müssen, um die Schalter entsprechend zu konfigurieren.

   Das folgende Beispiel zeigt, wie der endgültige Code, einschließlich Kommentaren, aussehen kann:

   <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 auch

• Ablaufverfolgungs- und Instrumentierungsanwendungen
• Vorgehensweise: Hinzufügen von Ablaufverfolgungsanweisungen zu Anwendungscode
• Ablaufverfolgungsschalter
• Schema für Tracing- und Debugging-Einstellungen