配置消息日志记录

本主题介绍如何为不同方案配置消息日志记录。

启用消息日志记录

默认情况下，Windows Communication Foundation （WCF） 不会记录消息。 若要激活消息日志记录，必须将跟踪侦听器添加到 System.ServiceModel.MessageLogging 跟踪源，并为配置文件中的元素设置属性 <messagelogging> 。

以下示例演示如何启用日志记录并指定其他选项。

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

有关消息日志记录设置的详细信息，请参阅 跟踪和消息日志记录的建议设置。

可用于 add 指定要使用的侦听器的名称和类型。 在示例配置中，侦听器名为“messages”，并将标准 .NET Framework 跟踪侦听器 （System.Diagnostics.XmlWriterTraceListener） 添加为要使用的类型。 如果使用 System.Diagnostics.XmlWriterTraceListener，则必须在配置文件中指定输出文件位置和名称。 通过将 initializeData 设置为日志文件的名称来完成。 否则，系统将引发异常。 还可以实现向默认文件发出日志的自定义侦听器。

日志记录级别以及其他选项在“日志记录级别和选项”部分中进行了讨论。

switchValue属性在source中仅对跟踪有效。 如果为switchValue跟踪源指定System.ServiceModel.MessageLogging属性，如下所示，则它不起作用。

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

如果要禁用跟踪源，则应改用logMessagesAtServiceLevel元素的logMalformedMessages和logMessagesAtTransportLevelmessageLogging属性。 应将所有这些属性设置为 false。 这可以通过在前面的代码示例中使用配置文件、通过配置编辑器 UI 接口或使用 WMI 来完成。 有关配置编辑器工具的详细信息，请参阅配置编辑器工具（SvcConfigEditor.exe）。 有关 WMI 的详细信息，请参阅 使用 Windows Management Instrumentation 进行诊断。

日志记录的级别和选项

对于传入消息，日志记录在消息形成后立即发生，在消息到达服务级别的用户代码之前，以及检测到格式不正确的消息时立即进行。

对于传出消息，日志记录会在消息离开用户代码后立即进行，并在消息进入线路之前立即进行。

WCF 记录两个不同级别的消息：服务和传输。 格式错误的消息也会被记录。 这三个类别彼此独立，可以在配置中单独激活。

可以通过设置logMessagesAtServiceLevel、logMalformedMessages和logMessagesAtTransportLevel属性来控制messageLogging元素的日志记录级别。

服务级别

在这个层上记录的消息是关于进入用户代码（在接收时）或离开用户代码（在发送时）的情况。 如果已定义筛选器，则只会记录与筛选器匹配的消息。 否则将记录服务级别上的所有消息。 基础结构消息（事务、对等通道和安全性）也在此级别上记录，但可靠传递消息除外。 对于经过流处理的消息，则只记录标头。 此外，安全消息在此级别上按解密记录。

传输级别

在这个层上记录的消息已准备好进行编码以便在网络上传输，或已准备好在经过网络传输后进行解码。 如果已定义筛选器，则只会记录与筛选器匹配的消息。 否则，将记录传输层中的所有消息。 所有基础设施消息都记录在此层，包括可靠消息传递。 对于经过流处理的消息，则只记录标头。 此外，安全消息将记录为在此级别加密，除非使用安全传输（如 HTTPS）。

“格式不正确”级别

格式不正确的消息是 WCF 堆栈在任何处理阶段都拒绝的消息。 格式错误的消息将被如实记录：已加密（如果是加密的）、带有不适当的 XML 等。 maxSizeOfMessageToLog 定义了要记录为 CDATA 的消息的大小。 默认情况下， maxSizeOfMessageToLog 等于 256K。 有关此属性的详细信息，请参阅“其他选项”部分。

其他选项

除了日志记录级别，用户还可以指定以下选项：

• 记录整个消息（logEntireMessage 属性）：此值指定是否记录整个消息（消息头和正文）。 默认值为 false，这意味着仅记录日志头。 此设置会影响服务和传输消息日志记录级别。

• 要记录的最大消息数（maxMessagesToLog 属性）：此值指定要记录的最大消息数。 所有消息（服务、传输和格式不正确的消息）都计入此配额。 达到配额后，将输出跟踪信息，并且不会记录其他的信息。 默认值为 10000。

• 记录消息的最大大小（maxSizeOfMessageToLog 属性）：此值以字节为单位，指定要记录的消息的最大大小。 不会记录超出大小限制的消息，也不会为该消息执行其他活动。 此设置会影响所有跟踪级别。 如果 ServiceModel 跟踪处于打开状态，则会在第一个日志记录点（ServiceModelSend* 或 TransportReceive）发出警告级跟踪以通知用户。 服务级别和传输级别消息的默认值为 256K，而格式不正确的消息的默认值为 4K。

  谨慎

  要与 maxSizeOfMessageToLog 比较的消息大小是序列化前内存中的消息大小。 此大小可能与记录的消息字符串的实际长度不同，并且在许多情况下大于实际大小。 因此，可能不会记录消息。 可以通过将 maxSizeOfMessageToLog 属性指定为比预期消息大小大 10% 来考虑这一事实。 此外，如果记录格式不正确的消息，则消息日志使用的实际磁盘空间最多可以达到指定 maxSizeOfMessageToLog值的 5 倍。

如果在配置文件中未定义跟踪侦听器，则无论指定的日志记录级别如何，都不会生成日志记录输出。

可以使用 Windows Management Instrumentation（WMI）在运行时更改消息日志记录选项，例如本节中所述的属性。 这可以通过访问 AppDomainInfo 实例来完成，该实例公开这些布尔属性： LogMessagesAtServiceLevel， LogMessagesAtTransportLevel和 LogMalformedMessages。 因此，如果您为消息日志记录配置了跟踪侦听器，但在配置中将这些选项设置为 false，则可以在应用程序运行时将其更改为 true。 这会在运行时有效地启用消息日志记录。 同样，如果在配置文件中启用消息日志记录，则可以使用 WMI 在运行时禁用它。 有关详细信息，请参阅 使用 Windows Management Instrumentation 进行诊断。

消息日志中的source字段指定消息记录的上下文：在发送/接收请求消息时，在请求-回复或单向请求的情况下，在服务模型或传输层，或者在格式不正确的消息情况下。

对于格式不正确的消息， source 等于 Malformed。 否则，源数据在上下文中具有以下值。

对于请求/答复：

对于单向请求：

消息筛选器

消息筛选器在messageLogging配置节的diagnostics配置元素中定义。 它们应用于服务和传输层级。 定义一个或多个筛选器时，只会记录与至少一个筛选器匹配的消息。 如果未定义筛选器，则所有消息都通过。

筛选器支持完整的 XPath 语法，并按它们在配置文件中显示的顺序应用。 语法不正确的筛选器会导致配置异常。

筛选器还通过使用nodeQuota属性提供了一种安全功能，该属性限制了可在XPath DOM中检查以匹配筛选器的最大节点数。

以下示例演示如何配置仅记录具有 SOAP 标头节的消息的筛选器。

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

筛选器不能应用于消息正文。 试图更改邮件正文的筛选器将从筛选器列表中删除。 此外还会发出一个指示此事的事件。 例如，将从筛选器表中删除以下筛选器。

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

配置自定义侦听器

还可以使用其他选项配置自定义侦听器。 若要在记录之前将特定于应用程序的 PII 元素从消息中筛选出来，自定义侦听器可能很有用。 以下示例演示自定义侦听器配置。

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

请您注意，type 属性应该设置为该类型的限定程序集名称。

另请参阅

• <messageLogging>
• 消息日志记录
• 跟踪和消息日志记录的推荐设置