Procedura: Creare, inizializzare e configurare opzioni di traccia

Le opzioni di traccia consentono di abilitare, disabilitare e filtrare l'output di traccia.

Creazione e inizializzazione di un'opzione di traccia

Per usare le opzioni di traccia, è necessario prima di tutto crearle e inserirle nel codice. Sono presenti due classi predefinite da cui è possibile creare oggetti opzione: System.Diagnostics.BooleanSwitch e System.Diagnostics.TraceSwitch. Si utilizza l'oggetto BooleanSwitch solo se è necessario stabilire se i messaggi di traccia vengono visualizzati; l'oggetto TraceSwitch viene invece utilizzato se è necessario distinguere tra i livelli di traccia. Se si utilizza un oggetto TraceSwitch è possibile definire messaggi di debug personalizzati e associarli a diversi livelli di traccia. È possibile usare entrambi i tipi di opzioni sia per la traccia sia per il debug. Per impostazione predefinita, un oggetto BooleanSwitch è disabilitato e un oggetto TraceSwitch è impostato sul livello TraceLevel.Off. È possibile creare e inserire opzioni di traccia in un punto qualsiasi del codice in cui possano essere usate.

Nonostante sia possibile impostare i livelli di traccia e altre opzioni di configurazione all'interno del codice, è consigliabile utilizzare il file di configurazione per gestire lo stato delle opzioni. Questo perché la gestione della configurazione delle opzioni nel sistema di configurazione consente una maggiore flessibilità: è infatti possibile attivare e disattivare diverse opzioni e modificare i livelli senza ricompilare l'applicazione.

Per creare e inizializzare un'opzione di traccia

1. Definire un'opzione di tipo System.Diagnostics.BooleanSwitch o System.Diagnostics.TraceSwitch e impostare il nome e la descrizione dell'opzione.

2. Configurare l'opzione di traccia. Per altre informazioni, vedere Configurazione delle opzioni di traccia.

   Il codice seguente crea due opzioni, una per ogni tipo:

   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");
   

Configurazione di opzioni di traccia

Una volta distribuita l'applicazione, è ancora possibile attivare o disabilitare l'output di traccia configurando le opzioni di traccia dell'applicazione. Configurare un'opzione significa modificarne il valore da un'origine esterna una volta inizializzata. È possibile modificare i valori degli oggetti opzione mediante il file di configurazione. Si configura un'opzione di traccia per attivarla e disabilitarla oppure per impostarne il livello, determinando la quantità e il tipo di messaggi da inviare ai listener.

Le opzioni vengono configurate tramite il file CONFIG. In caso di applicazioni Web si tratta del file Web.config associato al progetto. Nelle applicazioni Windows il file è denominato (nome applicazione).exe.config. Nelle applicazioni distribuite il file deve trovarsi nella stessa cartella dell'eseguibile.

Quando l'applicazione esegue il codice che crea un'istanza di un'opzione per la prima volta, viene verificata la presenza nel file di configurazione di informazioni sul livello di traccia relative all'opzione denominata. Il file di configurazione viene esaminato dal sistema di tracciatura solo una volta per ogni opzione, la prima volta che l'opzione in questione viene creata dall'applicazione.

In un'applicazione distribuita, il codice di traccia viene abilitato riconfigurando gli oggetti opzione quando l'applicazione non è in esecuzione. In genere questo implica l'attivazione e la disattivazione degli oggetti opzione o la modifica dei livelli di traccia, quindi il riavvio dell'applicazione.

Quando si crea un'istanza di un'opzione, la si inizializza anche specificando due argomenti: un argomento displayName e un argomento description. L'argomento displayName del costruttore imposta la proprietà Switch.DisplayName dell'istanza della classe Switch. L'argomento displayName rappresenta il nome usato per configurare l'opzione nel file CONFIG, mentre l'argomento description restituisce una breve descrizione dell'opzione e dei messaggi che controlla.

Oltre a specificare il nome di un'opzione da configurare, è necessario specificare un valore per l'opzione. Tale valore deve essere Integer. Per BooleanSwitch, un valore pari a 0 corrisponde a Off, mentre un valore diverso da 0 corrisponde a On. Per la classe TraceSwitch, 0,1,2,3 e 4 corrispondono rispettivamente a Off, Error, Warning, Info e Verbose. Tutti i numeri maggiori di 4 vengono considerati come Verbose, tutti i numeri minori di zero vengono considerati Off.

Per consentire all'utente finale di configurare un'opzione di traccia di un'applicazione, è necessario fornire una documentazione dettagliata delle opzioni nell'applicazione. Devono essere descritte in dettaglio le opzioni, ciò che controllano e le modalità di attivazione e disattivazione. È inoltre necessario fornire all'utente finale un file CONFIG dotato di una Guida adeguata nei commenti.

Per configurare opzioni di traccia

1. Per usare le opzioni di traccia, è necessario prima di tutto crearle e inserirle nel codice, come descritto nella sezione Creazione e inizializzazione di un'opzione di traccia.

2. Se il progetto non contiene un file di configurazione (app.config o Web.config), scegliere Aggiungi nuovo elemento dal menu Progetto.

   • Visual Basic: nella finestra di dialogo Aggiungi nuovo elemento scegliere File di configurazione dell'applicazione.

     Verrà creato e aperto il file di configurazione dell'applicazione. Si tratta di un documento XML il cui elemento radice è <configuration>.

   • Visual C#: nella finestra di dialogo Aggiungi nuovo elemento fare clic su File XML. Denominare il file app.config. Nell'editor XML, dopo la dichiarazione XML, aggiungere il codice XML seguente:

     <configuration>
     </configuration>
     

     Una volta compilato il progetto, il file app.config viene copiato nella cartella di output del progetto e rinominato nomeapplicazione.exe.config.

3. Dopo il tag <configuration>, ma prima del tag </configuration>, aggiungere il codice XML appropriato per la configurazione delle opzioni. Gli esempi seguenti illustrano un oggetto BooleanSwitch con una proprietà DisplayName di DataMessageSwitch e un oggetto TraceSwitch con una proprietà DisplayName di TraceLevelSwitch.

   <system.diagnostics>
      <switches>
         <add name="DataMessagesSwitch" value="0" />
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

   In questa configurazione entrambe le opzioni sono disabilitate.

4. Se è necessario attivare un BooleanSwitch, come DataMessagesSwitch illustrato nell'esempio precedente, impostare Value su qualsiasi intero diverso da 0.

5. Se è necessario attivare un TraceSwitch, come TraceLevelSwitch illustrato nell'esempio precedente, impostare Value sul livello appropriato (da 1 a 4).

6. Aggiungere commenti al file CONFIG in modo che l'utente possa comprendere chiaramente quali valori modificare per configurare correttamente le opzioni.

   L'esempio seguente mostra come può apparire il codice finale, comprensivo di commenti:

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

Vedi anche

• Traccia e strumentazione di applicazioni
• Procedura: aggiungere istruzioni di traccia al codice dell'applicazione
• Opzioni di traccia
• Schema delle impostazioni di traccia e debug