Configurazione della registrazione dei messaggi

In questo argomento viene descritto come configurare la registrazione dei messaggi per diversi scenari.

Abilitazione della registrazione dei messaggi

Windows Communication Foundation (WCF) non registra i messaggi per impostazione predefinita. Per attivare la registrazione dei messaggi, è necessario aggiungere un listener di traccia all'origine System.ServiceModel.MessageLogging di traccia e impostare gli attributi per l'elemento <messagelogging> nel file di configurazione.

Nell'esempio seguente viene illustrato come abilitare la registrazione e specificare opzioni aggiuntive.

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

Per altre informazioni sulle impostazioni di registrazione dei messaggi, vedere Impostazioni consigliate per la traccia e la registrazione dei messaggi.

È possibile usare add per specificare il nome e il tipo del listener che si vuole usare. Nella configurazione di esempio il listener è denominato "messages" e aggiunge il listener di traccia standard di .NET Framework (System.Diagnostics.XmlWriterTraceListener) come tipo da usare. Se si usa System.Diagnostics.XmlWriterTraceListener, è necessario specificare il percorso e il nome del file di output nel file di configurazione. Questa operazione viene eseguita impostando initializeData sul nome del file di log. In caso contrario, il sistema genera un'eccezione. È anche possibile implementare un listener personalizzato che genera log in un file predefinito.

Annotazioni

Poiché la registrazione dei messaggi accede allo spazio su disco, è necessario limitare il numero di messaggi scritti su disco per un determinato servizio. Quando viene raggiunto il limite di messaggi, viene generata una traccia a livello di informazioni e tutte le attività di registrazione dei messaggi vengono interrotte.

Il livello di registrazione, nonché le opzioni aggiuntive, sono descritte nella sezione Livello di registrazione e opzioni.

L'attributo switchValue di un source è valido solo per il tracciamento. Se si specifica un attributo switchValue per la fonte di traccia System.ServiceModel.MessageLogging come indicato di seguito, non avrà alcun effetto.

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

Se si desidera disabilitare l'origine di traccia, è necessario usare invece gli logMessagesAtServiceLevelattributi , logMalformedMessagese logMessagesAtTransportLevel dell'elemento messageLogging . È necessario impostare tutti questi attributi su false. Questa operazione può essere eseguita usando il file di configurazione nell'esempio di codice precedente, tramite l'interfaccia dell'interfaccia utente dell'editor di configurazione o tramite WMI. Per altre informazioni sullo strumento Editor di configurazione, vedere Strumento editor di configurazione (SvcConfigEditor.exe). Per altre informazioni su WMI, vedere Uso di Strumentazione gestione Windows per la diagnostica.

Livelli e opzioni di registrazione

Per i messaggi in arrivo, la registrazione avviene immediatamente dopo il formato del messaggio, immediatamente prima che il messaggio arrivi al codice utente a livello di servizio e quando vengono rilevati messaggi in formato non valido.

Per i messaggi in uscita, la registrazione avviene immediatamente dopo che il messaggio lascia il codice utente e immediatamente prima che il messaggio venga inviato in transito.

WCF registra i messaggi a due livelli diversi, servizio e trasporto. Vengono registrati anche messaggi con errori di formato. Le tre categorie sono indipendenti l'una dall'altra e possono essere attivate separatamente nella configurazione.

È possibile controllare il livello di registrazione impostando gli logMessagesAtServiceLevelattributi , logMalformedMessagese logMessagesAtTransportLevel dell'elemento messageLogging .

Livello di servizio

I messaggi registrati a questo livello stanno per immettere (durante la ricezione) o lasciare (all'invio) il codice utente. Se sono stati definiti filtri, vengono registrati solo i messaggi che corrispondono ai filtri. In caso contrario, vengono registrati tutti i messaggi a livello di servizio. Anche i messaggi dell'infrastruttura (transazioni, canale peer e sicurezza) vengono registrati a questo livello, ad eccezione dei messaggi Reliable Messaging. Nei messaggi trasmessi vengono registrate solo le intestazioni. Inoltre, i messaggi sicuri vengono registrati decrittografati a questo livello.

Livello di trasporto

I messaggi registrati a questo livello sono pronti per essere codificati o decodificati per o dopo il trasporto in transito. Se sono stati definiti filtri, vengono registrati solo i messaggi che corrispondono ai filtri. In caso contrario, vengono registrati tutti i messaggi a livello di trasporto. Tutti i messaggi dell'infrastruttura vengono registrati a questo livello, inclusi i messaggi di messaggistica affidabili. Nei messaggi trasmessi vengono registrate solo le intestazioni. Inoltre, i messaggi sicuri vengono registrati come crittografati a questo livello, tranne se viene usato un trasporto sicuro, ad esempio HTTPS.

Livello in formato non valido

I messaggi in formato non valido sono messaggi rifiutati dallo stack WCF in qualsiasi fase di elaborazione. I messaggi in formato non valido vengono registrati as-is: crittografati in caso affermativo, con codice XML non corretto e così via. maxSizeOfMessageToLog ha definito le dimensioni del messaggio da registrare come CDATA. Per impostazione predefinita, maxSizeOfMessageToLog è uguale a 256K. Per altre informazioni su questo attributo, vedere la sezione Altre opzioni.

Altre opzioni

Oltre ai livelli di registrazione, l'utente può specificare le opzioni seguenti:

Log Entire Message (logEntireMessage attribute): questo valore specifica se viene registrato l'intero messaggio (intestazione e corpo del messaggio). Il valore predefinito è false, vale a dire che viene registrata solo l'intestazione. Questa impostazione influisce sui livelli di registrazione dei messaggi di servizio e trasporto.
Numero massimo di messaggi da registrare (maxMessagesToLog attributo): questo valore specifica il numero massimo di messaggi da registrare. Tutti i messaggi (servizio, trasporto e messaggi in formato non valido) vengono conteggiati per questa quota. Quando viene raggiunta la quota, viene generata una traccia e non viene registrato alcun messaggio aggiuntivo. Il valore predefinito è 10000.
Dimensione massima del messaggio da registrare (maxSizeOfMessageToLog attributo): Questo valore specifica la dimensione massima dei messaggi da registrare in byte. I messaggi che superano il limite di dimensioni non vengono registrati e non viene eseguita alcuna altra attività per tale messaggio. Questa impostazione influisce su tutti i livelli di traccia. Se la traccia ServiceModel è attivata, viene generata una traccia a livello di avviso al primo punto di registrazione (ServiceModelSend* o TransportReceive) per notificare all'utente. Il valore predefinito per i messaggi a livello di servizio e di trasporto è 256K, mentre il valore predefinito per i messaggi in formato non valido è 4K.

Attenzione

La dimensione del messaggio calcolata per confrontare maxSizeOfMessageToLog è la dimensione del messaggio in memoria prima della serializzazione. Questa dimensione può differire dalla lunghezza effettiva della stringa del messaggio che viene registrata e in molte occasioni è maggiore della dimensione effettiva. Di conseguenza, i messaggi potrebbero non essere registrati. È possibile tenere conto di questo fatto specificando l'attributo maxSizeOfMessageToLog per essere 10% maggiore delle dimensioni del messaggio previste. Inoltre, se vengono registrati messaggi in formato non valido, lo spazio su disco effettivo utilizzato dai log dei messaggi può essere fino a 5 volte la dimensione del valore specificato da maxSizeOfMessageToLog.

Se nel file di configurazione non è definito alcun listener di traccia, non viene generato alcun output di registrazione indipendentemente dal livello di registrazione specificato.

Le opzioni di registrazione dei messaggi, ad esempio gli attributi descritti in questa sezione, possono essere modificate in fase di esecuzione usando Strumentazione gestione Windows (WMI). A tale scopo, accedere all'istanza di AppDomainInfo , che espone queste proprietà booleane: LogMessagesAtServiceLevel, LogMessagesAtTransportLevele LogMalformedMessages. Pertanto, se si configura un listener di traccia per la registrazione dei messaggi, ma si impostano queste opzioni su false nella configurazione, è possibile modificarle in un secondo momento in true quando l'applicazione è in esecuzione. Ciò abilita in modo efficace la registrazione dei messaggi in fase di esecuzione. Analogamente, se si abilita la registrazione dei messaggi nel file di configurazione, è possibile disabilitarla in fase di esecuzione usando WMI. Per altre informazioni, vedere Uso di Strumentazione gestione Windows per la diagnostica.

Il source campo in un log dei messaggi specifica in quale contesto viene registrato il messaggio: quando si invia/riceve un messaggio di richiesta, per una richiesta di tipo request-reply o 1-way, a livello di modello di servizio o trasporto oppure nel caso di un messaggio in formato non valido.

Per i messaggi in formato non valido, source è uguale a Malformed. In caso contrario, l'origine ha i valori seguenti in base al contesto.

Per invio di richiesta/risposta:

Strato	Invia richiesta	Richiesta di ricezione	Invia risposta	Ricevi risposta
Livello del modello di servizio	Servizio Livello Invia Richiesta	Servizio Livello Ricevere Richiesta	Servizio Livello Invia Risposta	Servizio Livello Ricevere Risposta
Livello di trasporto	Trasporto Invia	Trasporto Ricevere	Trasporto Invia	Trasporto Ricevere

Per una richiesta unidirezionale:

Strato	Invia richiesta	Richiesta di ricezione
Livello del modello di servizio	Servizio Livello Invia Datagramma	Servizio Livello Ricevere Datagramma
Livello di trasporto	Trasporto Invia	Trasporto Ricevere

Filtri messaggi

I filtri dei messaggi vengono definiti nell'elemento messageLogging di configurazione della diagnostics sezione di configurazione. Vengono applicati a livello di servizio e trasporto. Quando vengono definiti uno o più filtri, vengono registrati solo i messaggi che corrispondono ad almeno uno dei filtri. Se non è definito alcun filtro, tutti i messaggi passano.

I filtri supportano la sintassi XPath completa e vengono applicati nell'ordine in cui vengono visualizzati nel file di configurazione. Un filtro sintatticamente errato genera un'eccezione di configurazione.

I filtri forniscono anche una funzionalità di sicurezza usando l'attributo nodeQuota , che limita il numero massimo di nodi nel DOM XPath che può essere esaminato in modo che corrisponda al filtro.

Nell'esempio seguente viene illustrato come configurare un filtro che registra solo i messaggi con una sezione di intestazione 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>

I filtri non possono essere applicati al corpo di un messaggio. I filtri che tentano di modificare il corpo di un messaggio vengono rimossi dall'elenco di filtri. Viene emesso anche un evento che lo indica. Ad esempio, il filtro seguente verrà rimosso dalla tabella dei filtri.

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

Configurazione di un listener personalizzato

È anche possibile configurare un listener personalizzato con opzioni aggiuntive. Un listener personalizzato può essere utile per filtrare elementi PII specifici dell'applicazione dai messaggi prima della registrazione. Nell'esempio seguente viene illustrata una configurazione del listener personalizzata.

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

È necessario tenere presente che l'attributo type deve essere impostato su un nome di assembly qualificato del tipo.

Vedere anche

Last updated on 2025-06-17

Condividi tramite