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 einen Ablaufverfolgungslistener zur System.ServiceModel.MessageLogging-Ablaufverfolgungsquelle hinzufügen und in der Konfigurationsdatei Attribute für das <messagelogging>-Element festlegen.
Das folgende Beispiel zeigt, wie die Protokollierung aktiviert und zusätzliche Optionen angegeben werden.
<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 Ablaufverfolgung und Nachrichtenprotokollierung.
Mit add können Sie den Namen und den Typ des Listeners angeben, den Sie verwenden möchten. In unserer Beispielkonfiguration haben wir den Listener "messages" genannt und den standardmäßigen Ablaufverfolgungslistener .NET Framework (System.Diagnostics.XmlWriterTraceListener) als zu verwendenden Typ angegeben. Wenn Sie System.Diagnostics.XmlWriterTraceListener verwenden, müssen Sie den Speicherort und den Namen der Ausgabedatei in der Konfigurationsdatei angeben. Legen Sie dafür initializeData auf den Namen der Protokolldatei fest. Andernfalls löst das System eine Ausnahme aus. Sie können auch einen benutzerdefinierten Listener implementieren, der Protokolle in einer Standarddatei ausgibt.
Warnung
Da die Nachrichtenprotokollierung Speicherplatz verbraucht, beschränken Sie die Anzahl der Nachrichten, die auf die Festplatte geschrieben werden, auf einen bestimmten Dienst. Wenn die Nachrichtengrenze erreicht wird, wird eine Ablaufverfolgung auf Informationsebene erstellt und alle Nachrichtenprotokollierungsaktionen werden angehalten.
Die Protokollierungsebene sowie die zusätzlichen Optionen werden im Abschnitt Protokollieren von Ebenen und Optionen (möglicherweise in englischer Sprache) erläutert.
Das switchValue-Attribut von source ist nur für die Ablaufverfolgung gültig. Wenn Sie ein switchValue-Attribut für die System.ServiceModel.MessageLogging-Ablaufverfolgungsquelle wie folgt angeben, hat dies keine Auswirkungen.
<source name="System.ServiceModel.MessageLogging" switchValue="Verbose">
Wenn Sie die Ablaufverfolgungsquelle deaktivieren möchten, verwenden Sie stattdessen das logMessagesAtServiceLevel, logMalformedMessages-Attribut und das logMessagesAtTransportLevel-Attribut des messageLogging-Elements. Sie sollten all diese Attribute auf false festlegen. Dieser Schritt kann anhand der Konfigurationsdatei im vorigen Beispielcode über die Benutzeroberfläche des Configuration Editor oder über WMI durchgeführt werden. Weitere Informationen über das Configuration 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.
Protokollieren von Ebenen und Optionen
Für eingehende Nachrichten erfolgt die Protokollierung direkt nach dem Erstellen der Nachricht, unmittelbar bevor die Nachricht Benutzercode auf der Dienstebene erhält und wenn falsch formatierte Nachrichten erkannt werden.
Für ausgehende Nachrichten erfolgt die Protokollierung unmittelbar nachdem die Nachricht den Benutzercode verlassen hat und unmittelbar bevor die Nachricht abgesendet wird.
WCF protokolliert Nachrichten auf zwei verschiedenen Ebenen, Dienst und Transport. Falsch formatierte Nachrichten werden auch protokolliert. Die drei Kategorien sind unabhängig voneinander und können in der Konfiguration getrennt aktiviert werden.
Sie können die Protokollierungsebene steuern, indem Sie das logMessagesAtServiceLevel, logMalformedMessages-Attribut und das logMessagesAtTransportLevel-Attribut 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, die zu den Filtern passen, protokolliert. Andernfalls werden alle Nachrichten auf Dienstebene protokolliert. Auf dieser Ebene werden auch Infrastrukturnachrichten (Transaktionen, Peerkanal und Sicherheit) protokolliert, mit Ausnahme von mit zuverlässigem Messaging erstellten Nachrichten. Bei per Streaming übertragenen Nachrichten werden nur die Header protokolliert. Außerdem werden sichere Nachrichten auf dieser Ebene entschlüsselt protokolliert.
Transportschicht
Auf dieser Ebene protokollierte Nachrichten können vor oder nach dem Transport codiert oder decodiert werden. Wenn Filter definiert wurden, werden nur Nachrichten, die zu den Filtern passen, protokolliert. Andernfalls werden alle Nachrichten auf der Transportschicht protokolliert. Auf dieser Ebene werden alle Infrastrukturnachrichten protokolliert, einschließlich zuverlässiger Messagingnachrichten. Bei per Streaming übertragenen Nachrichten werden nur die Header protokolliert. Außerdem werden sichere Nachrichten auf dieser Ebene verschlüsselt protokolliert, außer bei Verwendung eines sicheren Transports wie HTTPS.
Falsch formatierte Ebene
Falsch formatierte Nachrichten sind Nachrichten, die vom WCF-Stapel in irgendeiner Phase der Verarbeitung abgelehnt werden. Falsch formatierte Nachrichten werden unverändert protokolliert: verschlüsselt, wenn sie bereits verschlüsselt sind, mit nicht ordnungsgemäßem XML usw. maxSizeOfMessageToLog definierte die zu protokollierende Nachrichtengröße als CDATA. Standardmäßig entspricht maxSizeOfMessageToLog dem Wert "256 K". Weitere Informationen zu diesem Attribut finden Sie unter Weitere Optionen (möglicherweise in englischer Sprache).
Weitere Optionen
Zusätzlich zu den Protokollierungsebenen kann der Benutzer die folgenden Optionen angeben:
- Gesamte Nachricht protokollieren (logEntireMessage-Attribut): Dieser Wert gibt an, ob die ganze Meldung (Nachrichtenheader und Text) protokolliert wird. Der Standardwert lautet false, das bedeutet, dass nur der Nachrichtenheader protokolliert wird. Diese Einstellung beeinflusst die Nachrichtenprotokollierung auf Dienst- und Transportebene.
- Max. zu protokollierende Nachrichten (maxMessagesToLog-Attribut): Dieser Wert gibt die maximale Anzahl von zu protokollierenden Nachrichten an. Alle Nachrichten (Dienst, Transport und falsch formatierte Nachrichten) werden zu diesem Kontingent gezählt. Wenn das Kontingent erreicht wird, wird eine Ablaufverfolgung ausgegeben und keine weitere Nachricht protokolliert. Der Standardwert ist 10000.
- Max. Größe der zu protokollierenden Nachrichten (maxSizeOfMessageToLog-Attribut): Dieser Wert gibt die maximale Größe einer zu protokollierenden Nachricht in Byte an. Nachrichten, die das Größenlimit überschreiten, werden nicht protokolliert, und für diese Nachricht werden keine weiteren Aktivitäten durchgefü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 Dienst- und auf Transportebene ist 256 K, während der Standardwert für falsch formatierte Nachrichten 4 K ist. Vorsicht: Die Nachrichtengröße, die zum Vergleich mit maxSizeOfMessageToLog berechnet wird, ist die Nachrichtengröße im Speicher zum Zeitpunkt vor der Serialisierung. Diese Größe kann von der tatsächlichen Länge der Nachrichtenzeichenfolge, die protokolliert wird, abweichen. In vielen Fällen überschreitet sie die tatsächliche Größe. Demzufolge werden Nachrichten möglicherweise nicht protokolliert. Um dieser Tatsache Rechnung zu tragen, können Sie das maxSizeOfMessageToLog-Attribut um 10 % größer angeben als die erwartete Nachrichtengröße. Wenn falsch formatierte Nachrichten protokolliert werden, kann die tatsächliche Festplattenspeichergröße, die von Nachrichtenprotokollen genutzt wird, die Größe des durch maxSizeOfMessageToLog angegebenen Werts um das Fünffache übersteigen.
Wenn in der Konfigurationsdatei kein Ablaufverfolgungslistener definiert ist, wird unabhängig von der angegebenen Protokollierungsebene keine Protokollierungsausgabe generiert.
Die Nachrichtenprotokollierungsoptionen, wie die in diesem Abschnitt beschriebenen Attribute, können zur Laufzeit mit der Windows-Verwaltungsinstrumentation (WMI) geändert werden. Dies kann durch Zugreifen auf die AppDomainInfo-Instanz erfolgen, die folgende boolesche Eigenschaften verfügbar macht: LogMessagesAtServiceLevel, LogMessagesAtTransportLevel und LogMalformedMessages. Wenn Sie einen Ablaufverfolgungslistener für die Nachrichtenprotokollierung konfigurieren, diese Optionen jedoch in der Konfiguration auf false festlegen, können Sie sie später, wenn die Anwendung ausgeführt wird, auf true ändern. Dadurch wird die Nachrichtenprotokollierung zur Laufzeit wirksam aktiviert. Entsprechend können Sie die Nachrichtenprotokollierung, wenn Sie sie in der Konfigurationsdatei aktivieren, 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 unidirektionale Anforderung, auf der Dienstmodell- oder Transportschicht oder im Falle einer falsch formatierten Nachricht.
Für falsch formatierte Nachrichten ist source mit Malformed identisch. Andernfalls verfügt die Quelle über die folgenden Werte auf der Grundlage des Kontexts.
Für Anforderung/Antwort
| Anforderung senden | Anforderung empfangen | Antwort senden | Antwort empfangen | |
|---|---|---|---|---|
Dienstmodellebene |
Dienst Ebene Senden Anforderung |
Dienst Ebene Empfangen Anforderung |
Dienst Ebene Senden Antworten |
Dienst Ebene Empfangen Antworten |
Transportschicht |
Transport Senden |
Transport Empfangen |
Transport Senden |
Transport Empfangen |
Für unidirektionale Anforderung
| Anforderung senden | Anforderung empfangen | |
|---|---|---|
Dienstmodellebene |
Dienst Ebene Senden Datagramm |
Dienst Ebene Empfangen Datagramm |
Transportschicht |
Transport Senden |
Transport Empfangen |
Nachrichtenfilter
Nachrichtenfilter werden im messageLogging-Konfigurationselement des diagnostics-Konfigurationsabschnitts definiert. Sie werden auf der Dienst- und Transportebene angewendet. Wenn mindestens ein Filter definiert ist, werden nur Nachrichten protokolliert, die mindestens einem der Filter entsprechen. Wenn kein Filter definiert wird, werden alle Nachrichten protokolliert.
Filter unterstützen die gesamte Xpath-Syntax und werden in der Reihenfolge angewendet, in der sie in der Konfigurationsdatei angezeigt werden. Ein syntaktisch falscher Filter führt zu einer Konfigurationsausnahme.
Filter bieten unter Verwendung des nodeQuota-Attributs auch ein Sicherheitsfeature, das die maximale Anzahl der Knoten im XPath DOM, die im Hinblick auf den Filter geprüft werden, beschränkt.
Im Folgenden finden Sie ein Beispiel für das Konfigurieren eines Filters, 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 Text einer Nachricht angewendet werden. Filter, die versuchen, den Text einer Nachricht zu bearbeiten, werden aus der Liste von Filtern entfernt. Außerdem wird ein entsprechendes Ereignis ausgegeben. Der folgende Filter würde z. B. aus der Filtertabelle entfernt werden.
<add xmlns:s="https://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 nützlich sein, um vor der Protokollierung anwendungsspezifische PII-Elemente von Nachrichten zu filtern. Das folgende Beispiel veranschaulicht eine benutzerdefinierte Listenerkonfiguration.
<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>
Das type-Attribut sollte auf einen vollqualifizierten Assemblynamen festgelegt werden.
Siehe auch
Konzepte
Empfohlene Einstellungen für Ablaufverfolgung und Nachrichtenprotokollierung