Konfigurieren der Nachrichtenprotokollierung

In diesem Thema wird beschrieben, wie Sie die Nachrichtenprotokollierung für verschiedene Szenarien konfigurieren können.

Aktivieren der Nachrichtenprotokollierung

Windows Communication Foundation (WCF) protokolliert standardmäßig keine Nachrichten. Zum Aktivieren der Nachrichtenprotokollierung müssen Sie der System.ServiceModel.MessageLogging Ablaufverfolgungsquelle einen Ablaufverfolgungslistener hinzufügen und Attribute für das <messagelogging> Element in der Konfigurationsdatei festlegen.

Das folgende Beispiel zeigt, wie Sie die Protokollierung aktivieren und zusätzliche Optionen angeben.

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel.MessageLogging">
      <listeners>
         <add name="messages"
              type="System.Diagnostics.XmlWriterTraceListener"
              initializeData="c:\logs\messages.svclog" />
        </listeners>
    </source>
  </sources>
</system.diagnostics>

<system.serviceModel>
  <diagnostics>
    <messageLogging
         logEntireMessage="true"
         logMalformedMessages="false"
         logMessagesAtServiceLevel="true"
         logMessagesAtTransportLevel="false"
         maxMessagesToLog="3000"
         maxSizeOfMessageToLog="2000"/>
  </diagnostics>
</system.serviceModel>

Weitere Informationen zu den Einstellungen für die Nachrichtenprotokollierung finden Sie unter "Empfohlene Einstellungen für die Ablaufverfolgung" und "Nachrichtenprotokollierung".

Sie können add verwenden, um den Name und Typ des Listeners anzugeben, den Sie verwenden möchten. In der Beispielkonfiguration heißt der Listener "messages" und fügt den standardmäßigen .NET Framework-Ablaufverfolgungslistener (System.Diagnostics.XmlWriterTraceListener) als zu verwendenden Typ hinzu. Bei Verwendung System.Diagnostics.XmlWriterTraceListenermüssen Sie den Speicherort und den Namen der Ausgabedatei in der Konfigurationsdatei angeben. Dazu legen Sie initializeData den Namen der Protokolldatei fest. Andernfalls löst das System eine Ausnahme aus. Sie können auch einen benutzerdefinierten Listener implementieren, der Protokolle an eine Standarddatei ausgibt.

Hinweis

Da die Nachrichtenprotokollierung auf Speicherplatz zugreift, sollten Sie die Anzahl der Nachrichten einschränken, die für einen bestimmten Dienst auf den Datenträger geschrieben werden. Wenn der Nachrichtengrenzwert erreicht ist, wird ein Protokoll auf Informationsniveau erstellt, und alle Aktivitäten zur Nachrichtenprotokollierung werden beendet.

Die Protokollierungsebene sowie die zusätzlichen Optionen werden im Abschnitt "Protokollierungsebene und Optionen" erläutert.

Das switchValue-Attribut eines source ist nur für die Nachverfolgung gültig. Wenn Sie wie folgt ein switchValue Attribut für die System.ServiceModel.MessageLogging Tracequelle angeben, hat dies keine Wirkung.

<source name="System.ServiceModel.MessageLogging" switchValue="Verbose">
</source>

Wenn Sie die Tracing-Quelle deaktivieren möchten, sollten Sie stattdessen die logMessagesAtServiceLevel, logMalformedMessages und logMessagesAtTransportLevel Attribute des messageLogging Elements verwenden. Sie sollten all diese Attribute auf false festlegen. Dies kann mithilfe der Konfigurationsdatei im vorherigen Codebeispiel, über die Benutzeroberfläche des Konfigurations-Editors oder mithilfe von WMI erfolgen. Weitere Informationen zum Konfigurations-Editor-Tool finden Sie unter Configuration Editor Tool (SvcConfigEditor.exe). Weitere Informationen zu WMI finden Sie unter Verwenden der Windows-Verwaltungsinstrumentation für die Diagnose.

Protokollierungsebenen und -optionen

Bei eingehenden Nachrichten erfolgt die Protokollierung unmittelbar nach dem Erstellen der Nachricht, unmittelbar bevor die Nachricht zum Benutzercode auf Dienstebene gelangt und wenn falsch formatierte Nachrichten erkannt werden.

Bei ausgehenden Nachrichten erfolgt die Protokollierung unmittelbar, nachdem die Nachricht den Benutzercode verlassen hat, und unmittelbar bevor die Nachricht an die Leitung wechselt.

WCF protokolliert Nachrichten auf zwei verschiedenen Ebenen, Dienst und Transport. Falsch formatierte Nachrichten werden ebenfalls protokolliert. Die drei Kategorien sind voneinander unabhängig und können separat in der Konfiguration aktiviert werden.

Sie können die Protokollierungsebene steuern, indem Sie die logMessagesAtServiceLevel, logMalformedMessages und logMessagesAtTransportLevel Attribute des messageLogging Elements festlegen.

Dienstebene

Auf dieser Ebene protokollierte Nachrichten sind im Begriff, (beim Empfangen) Benutzercode einzugeben oder (beim Senden) zu belassen. Wenn Filter definiert wurden, werden nur Nachrichten protokolliert, die den Filtern entsprechen. Andernfalls werden alle Nachrichten auf Dienstebene protokolliert. Infrastrukturnachrichten (Transaktionen, Peerkanal und Sicherheit) werden ebenfalls auf dieser Ebene protokolliert, mit Ausnahme von Reliable Messaging-Nachrichten. Bei gestreamten Nachrichten werden nur die Header protokolliert. Außerdem werden sichere Nachrichten auf dieser Ebene entschlüsselt protokolliert.

Transportebene

Nachrichten, die auf dieser Ebene protokolliert werden, können für oder nach dem Transport auf dem Draht codiert oder decodiert werden. Wenn Filter definiert wurden, werden nur Nachrichten protokolliert, die den Filtern entsprechen. Andernfalls werden alle Nachrichten auf der Transportebene protokolliert. Alle Infrastrukturnachrichten werden auf dieser Ebene protokolliert, einschließlich zuverlässiger Nachrichten. Bei gestreamten Nachrichten werden nur die Header protokolliert. Darüber hinaus werden sichere Nachrichten auf dieser Ebene als verschlüsselt protokolliert, außer wenn ein sicherer Transport wie HTTPS verwendet wird.

Falsch formatierte Ebene

Fehlerhaft formatierte Nachrichten sind Nachrichten, die während des Verarbeitungsprozesses vom WCF-Stapel abgelehnt werden. Falsch formatierte Nachrichten werden unverändert protokolliert: verschlüsselt, wenn sie bereits verschlüsselt sind, mit nicht ordnungsgemäßem XML usw. maxSizeOfMessageToLog definiert die Größe der Nachricht, die als CDATA protokolliert werden soll. Standardmäßig ist maxSizeOfMessageToLog auf 256K festgelegt. Weitere Informationen zu diesem Attribut finden Sie im Abschnitt "Weitere Optionen".

Weitere Optionen

Zusätzlich zu den Protokollierungsebenen kann der Benutzer die folgenden Optionen angeben:

• Log Entire Message (logEntireMessage Attribut): Dieser Wert gibt an, ob die gesamte Nachricht (Nachrichtenkopf und Textkörper) protokolliert wird. Der Standardwert ist false, was bedeutet, dass nur der Header protokolliert wird. Diese Einstellung wirkt sich auf Dienst- und Transportnachrichtenprotokollierungsebenen aus.

• Max. zu protokollierende Nachrichten (maxMessagesToLog Attribut): Dieser Wert gibt die maximale Anzahl der zu protokollierenden Nachrichten an. Alle Nachrichten (Dienst-, Transport- und falsch formatierte Nachrichten) werden auf dieses Kontingent gezählt. Wenn das Kontingent erreicht wird, wird eine Ablaufverfolgung ausgegeben und keine weitere Nachricht protokolliert. Der Standardwert ist 10.000.

• Maximale Größe der zu protokollierenden Nachricht (maxSizeOfMessageToLog Attribut): Dieser Wert gibt die maximale Größe von Nachrichten an, die in Bytes protokolliert werden sollen. Nachrichten, die den Größengrenzwert überschreiten, werden nicht protokolliert, und für diese Nachricht wird keine andere Aktivität ausgeführt. Diese Einstellung wirkt sich auf alle Nachverfolgungsebenen aus. Wenn die ServiceModel-Ablaufverfolgung aktiviert ist, wird am ersten Protokollierungspunkt (ServiceModelSend* oder TransportReceive) zur Benachrichtigung des Benutzers eine Ablaufverfolgung auf Warnungsebene ausgegeben. Der Standardwert für Nachrichten auf Dienstebene und Transportebene beträgt 256 KB, während der Standardwert für falsch formatierte Nachrichten 4K ist.

  Vorsicht

  Die berechnete Nachrichtengröße, die mit maxSizeOfMessageToLog verglichen wird, ist die Nachrichtengröße im Arbeitsspeicher vor der Serialisierung. Diese Größe kann sich von der tatsächlichen Länge der protokollierten Nachrichtenzeichenfolge unterscheiden und ist in vielen Fällen größer als die tatsächliche Größe. Daher werden Nachrichten möglicherweise nicht protokolliert. Sie können diesen Umstand berücksichtigen, indem Sie das Attribut maxSizeOfMessageToLog so spezifizieren, dass es 10% größer als die erwartete Nachrichtengröße ist. Wenn falsch formatierte Nachrichten protokolliert werden, kann der tatsächlich vom Nachrichtenprotokoll verwendete Speicherplatz bis zu fünfmal so groß sein wie der Wert, der durch maxSizeOfMessageToLog angegeben wurde.

Wenn kein Trace Listener in der Konfigurationsdatei definiert ist, wird unabhängig von der angegebenen Log-Ebene keine Protokollierungsausgabe generiert.

Nachrichtenprotokollierungsoptionen, z. B. die in diesem Abschnitt beschriebenen Attribute, können zur Laufzeit mithilfe der Windows-Verwaltungsinstrumentation (WMI) geändert werden. Dies kann durch Den Zugriff auf die AppDomainInfo-Instanz erfolgen, die diese booleschen Eigenschaften verfügbar macht: LogMessagesAtServiceLevel, , LogMessagesAtTransportLevelund LogMalformedMessages. Wenn Sie einen Ablaufverfolgungslistener für die Nachrichtenprotokollierung konfigurieren, diese Optionen in der Konfiguration jedoch auf false festlegen, können Sie sie später, wenn die Anwendung ausgeführt wird, zu true ändern. Dadurch wird die Nachrichtenprotokollierung zur Laufzeit effektiv aktiviert. Wenn Sie die Nachrichtenprotokollierung in Ihrer Konfigurationsdatei aktivieren, können Sie sie zur Laufzeit mit WMI deaktivieren. Weitere Informationen finden Sie unter Verwenden der Windows-Verwaltungsinstrumentation für die Diagnose.

Das source Feld in einem Nachrichtenprotokoll gibt an, in welchem Kontext die Nachricht protokolliert wird: beim Senden/Empfangen einer Anforderungsnachricht, für eine Anforderungsantwort oder eine 1-Wege-Anforderung, bei Dienstmodell oder Transportebene oder im Fall einer falsch formatierten Nachricht.

Bei falsch formatierten Nachrichten source ist gleich Malformed. Andernfalls enthält die Quelle die folgenden Werte basierend auf dem Kontext.

Für Anforderung/Antwort:

Ebene	Anforderung senden	Anfrage empfangen	Antwort senden	Antwort empfangen
Servicemodell-Ebene	Dienstleistung Niveau Senden Anfrage	Dienstleistung Niveau Empfangen Anfrage	Dienstleistung Niveau Senden Antwort	Dienstleistung Niveau Empfangen Antwort
Transportschicht	Transport Senden	Transport Empfangen	Transport Senden	Transport Empfangen

Für unidirektionale Anforderung:

Ebene	Anforderung senden	Anfrage empfangen
Servicemodell-Ebene	Dienstleistung Niveau Senden Datagramm	Dienstleistung Niveau Empfangen Datagramm
Transportschicht	Transport Senden	Transport Empfangen

Nachrichtenfilter

Nachrichtenfilter werden im messageLogging Konfigurationselement des diagnostics Konfigurationsabschnitts definiert. Sie werden auf Dienst- und Transportebene angewendet. Wenn mindestens ein Filter definiert ist, werden nur Nachrichten protokolliert, die mindestens einem der Filter entsprechen. Wenn kein Filter definiert ist, werden alle Nachrichten durchlaufen.

Filter unterstützen die vollständige XPath-Syntax und werden in der Reihenfolge angewendet, in der sie in der Konfigurationsdatei angezeigt werden. Ein syntaktisch falscher Filter führt zu einer Konfigurations exception.

Filter bieten auch ein Sicherheitsfeature mithilfe des nodeQuota Attributs, das die maximale Anzahl von Knoten im XPath-DOM begrenzt, die untersucht werden können, um dem Filter zu entsprechen.

Das folgende Beispiel zeigt, wie Sie einen Filter konfigurieren, der nur Nachrichten aufzeichnet, die über einen SOAP-Headerabschnitt verfügen.

<messageLogging logEntireMessage="true"
    logMalformedMessages="true"
    logMessagesAtServiceLevel="true"
    logMessagesAtTransportLevel="true"
    maxMessagesToLog="420">
    <filters>
        <add nodeQuota="10" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
                 /soap:Envelope/soap:Header
        </add>
     </filters>
</messageLogging>

Filter können nicht auf den Textkörper einer Nachricht angewendet werden. Filter, die versuchen, den Textkörper einer Nachricht zu bearbeiten, werden aus der Liste der Filter entfernt. Außerdem wird ein entsprechendes Ereignis ausgegeben. Der folgende Filter würde z. B. aus der Filtertabelle entfernt.

<add xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">/s:Envelope/s:Body[contains(text(), "Hello")]</add>

Konfigurieren eines benutzerdefinierten Listeners

Sie können auch einen benutzerdefinierten Listener mit zusätzlichen Optionen konfigurieren. Ein benutzerdefinierter Listener kann beim Filtern anwendungsspezifischer PII-Elemente aus Nachrichten vor der Protokollierung hilfreich sein. Im folgenden Beispiel wird eine benutzerdefinierte Listenerkonfiguration veranschaulicht.

<system.diagnostics>
   <sources>
     <source name="System.ServiceModel.MessageLogging">
           <listeners>
             <add name="MyListener"
                    type="YourCustomListener"
                    initializeData="c:\logs\messages.svclog"
                    maxDiskSpace="1000"/>
           </listeners>
     </source>
   </sources>
</system.diagnostics>

Beachten Sie, dass das type Attribut auf einen qualifizierten Assemblynamen des Typs festgelegt werden soll.

Siehe auch

• <messageLogging>
• Nachrichtenprotokollierung
• Empfohlene Einstellungen für Ablaufverfolgung und Nachrichtenprotokollierung