Freigeben über

Vorgehensweise: Erstellen, Initialisieren und Konfigurieren von Ablaufverfolgungsschaltern

  • Artikel

Hinweis

Dieser Artikel gilt für das .NET Framework. Er gilt nicht für neuere Implementierungen von .NET, einschließlich .NET 6 und höherer Versionen.

Mit Ablaufverfolgungsschaltern können Sie die Ablaufverfolgungsausgabe aktivieren, deaktivieren und filtern.

Erstellen und Initialisieren eines Ablaufverfolgungsschalters

Damit Sie Ablaufverfolgungsschalter verwenden können, müssen Sie diese zunächst erstellen und in Ihrem Code platzieren. Es gibt zwei vordefinierte Klassen, aus denen Sie Schalterobjekte erstellen können: die System.Diagnostics.BooleanSwitch-Klasse und die System.Diagnostics.TraceSwitch-Klasse. 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. Wenn Sie eine TraceSwitch-Instanz verwenden, können Sie eigene Debugmeldungen definieren und diese verschiedenen Ablaufverfolgungsebenen zuordnen. Sie können beide Typen von Schaltern mit Ablaufverfolgung oder Debuggen verwenden. In der Standardeinstellung ist ein BooleanSwitch deaktiviert und ein TraceSwitch auf die Ebene TraceLevel.Off festgelegt. Ablaufverfolgungsschalter können in jedem beliebigen Teil Ihres Codes erstellt und platziert werden, in dem sie möglicherweise verwendet werden.

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

So erstellen und initialisieren Sie einen Ablaufverfolgungsschalter

  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.

  2. Konfigurieren Sie Ihren Ablaufverfolgungsschalter. Weitere Informationen finden Sie unter Konfigurieren von Ablaufverfolgungsschaltern.

    Im folgenden Code werden zwei Schalter erstellt, jeweils ein Schalter jedes Typs:

    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 bereitgestellt wurde, können weiterhin Ablaufverfolgungsausgabe aktivieren oder deaktivieren, indem Sie die Ablaufverfolgungsschalter in der Anwendung konfigurieren. Konfigurieren eines Schalters bedeutet, dass sein Wert aus einer externen Quelle geändert wird, nachdem er initialisiert wurde. Sie können die Werte der Schalterobjekte mithilfe der Konfigurationsdatei ändern. 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.

Ihre Schalter werden über die .config-Datei konfiguriert. Für eine 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 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. Das Ablaufverfolgungssystem durchsucht die Konfigurationsdatei für jeden Schalter nur ein Mal – wenn die Anwendung den Schalter erstmalig erstellt.

In einer bereitgestellten Anwendung aktivieren Sie Ablaufverfolgungscode, indem Sie Schalterobjekte neu konfigurieren, wenn die Anwendung nicht ausgeführt wird. Üblicherweise gehört hierzu Aktivieren oder Deaktivieren der Schalterobjekte oder Ändern der Ablaufverfolgungsebenen und dann Neustarten Ihrer Anwendung.

Wenn Sie eine Instanz eines Schalters erstellen, initialisieren Sie diesen auch, indem Sie zwei Argumente angeben: ein displayName-Argument und ein description-Argument. Das displayName-Argument des Konstruktors legt die Switch.DisplayName-Eigenschaft der Switch-Klasseninstanz fest. 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.

Zusätzlich zum Angeben des Namens eines Schalters, der konfiguriert werden soll, müssen Sie auch einen Wert für den Schalter angeben. Dieser Wert ist eine ganze Zahl. Für BooleanSwitch entspricht der Wert 0 Deaktiviert, und ein Wert ungleich 0 entspricht Aktiviert. Für TraceSwitch entsprechen 0,1,2,3 bzw. 4 Deaktiviert, Fehler, Warnung, Info bzw. Ausführlich. Jede Zahl, die größer als 4 ist, wird als Ausführlich, und jede Anzahl, die kleiner als 0 ist, wird als Deaktiviert angesehen.

Hinweis

In .NET Framework 2.0 können Sie Text verwenden, um den Wert eines Schalters anzugeben. Beispielsweise true für einen BooleanSwitch oder den Text, der einem Enumerationswert entspricht, etwa Error, für einen TraceSwitch. Die Zeile <add name="myTraceSwitch" value="Error" /> ist gleichbedeutend mit <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. Sie sollten ausführlich beschreiben, welche Schalter welche Vorgänge steuern und wie die Schalter aktiviert und deaktiviert werden. Außerdem sollten Sie Ihren Endbenutzern eine .config-Datei bereitstellen, die entsprechende Hilfen in den Kommentaren enthält.

So konfigurieren Sie Ablaufverfolgungsschalter

  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.

  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.

    • Visual Basic: Klicken Sie im Dialogfeld Neues Element hinzufügen auf Anwendungskonfigurationsdatei.

      Die Anwendungskonfigurationsdatei wird erstellt und geöffnet. Diese Datei ist ein XML-Dokument mit dem Stammelement <configuration>.

    • Visual C#: Klicken Sie im Dialogfeld Neues Element hinzufügen auf XML-Datei. Nennen Sie diese Datei app.config. Fügen Sie im XML-Editor folgenden Code nach der XML-Deklaration hinzu:

      <configuration>
</configuration>

      Nachdem das Projekt kompiliert ist, wird die Datei „app.config“ in den Projektausgabeordner kopiert und in „Anwendungsname.exe.config“ umbenannt.

  3. Fügen Sie nach dem <configuration>-Tag, aber vor dem </configuration>-Tag, die entsprechende XML ein, um die Schalter zu konfigurieren. In den folgenden Beispielen werden ein BooleanSwitch mit einer DisplayName-Eigenschaft von DataMessageSwitch und ein TraceSwitch mit einer DisplayName-Eigenschaft von TraceLevelSwitch veranschaulicht.

    <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, wie DataMessagesSwitch im vorhergehenden Beispiel, aktivieren möchten, ändern Sie den Wert in eine beliebige ganze Zahl ungleich 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).

  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.

    Im folgenden Beispiel wird gezeigt, wie der endgültige Code einschließlich der Kommentare aussehen könnte:

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

Weitere Informationen