Come fare per: Creare, inizializzare e configurare interruttori di traccia

Gli interruttori di traccia consentono di abilitare, disabilitare e filtrare l'output di traccia.

Creazione e inizializzazione di un interruttore di traccia

Per utilizzare gli interruttori di traccia, è necessario prima crearli e inserirli nel codice. Esistono due classi predefinite da cui è possibile creare oggetti switch: la System.Diagnostics.BooleanSwitch classe e la System.Diagnostics.TraceSwitch classe . Si utilizzerebbe BooleanSwitch se ci si preoccupa solo del fatto che un messaggio di traccia venga visualizzato o meno; si utilizzerebbe TraceSwitch se si desidera discriminare tra i livelli di tracciamento. Se si usa un TraceSwitchoggetto , è possibile definire i propri messaggi di debug e associarli a diversi livelli di traccia. È possibile utilizzare entrambi i tipi di interruttori con tracciamento o debug. Per impostazione predefinita, un BooleanSwitch oggetto è disabilitato e un TraceSwitch oggetto è impostato sul livello TraceLevel.Off. Gli interruttori di traccia possono essere creati e inseriti in qualsiasi parte del codice che potrebbe utilizzarli.

Sebbene sia possibile impostare i livelli di traccia e altre opzioni di configurazione nel codice sorgente, consigliamo di utilizzare il file di configurazione per gestire lo stato degli interruttori. Ciò è dovuto al fatto che la gestione della configurazione dei commutatori nel sistema di configurazione offre maggiore flessibilità. È possibile attivare e disattivare vari commutatori e modificare i livelli senza ricompilare l'applicazione.

Per creare e inizializzare un interruttore di traccia

1. Definire un'opzione come tipo System.Diagnostics.BooleanSwitch o tipo 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 di 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 degli interruttori di traccia

Dopo aver distribuito l'applicazione, è comunque possibile abilitare o disabilitare l'output di traccia configurando le opzioni di traccia nell'applicazione. Configurare un interruttore consiste nel modificarne il valore da un'origine esterna dopo che è stato inizializzato. È possibile modificare i valori degli oggetti switch usando il file di configurazione. È possibile configurare un'opzione di traccia per attivarla e disattivarla o per impostarne il livello, determinando la quantità e il tipo di messaggi passati ai listener.

I tuoi switch sono configurati usando il file .config. Per un'applicazione Web, si tratta del file Web.config associato al progetto. In un'applicazione Windows questo file è denominato (nome applicazione).exe.config. In un'applicazione distribuita, questo file deve trovarsi nella stessa cartella del file eseguibile.

Quando l'applicazione esegue il codice che crea un'istanza di un interruttore per la prima volta, controlla il file di configurazione per le informazioni a livello di traccia sullo switch denominato. Il sistema di traccia esamina il file di configurazione una sola volta per qualsiasi opzione specifica, ovvero la prima volta che l'applicazione crea l'opzione.

In un'applicazione distribuita si abilita il codice di traccia riconfigurando gli oggetti switch quando l'applicazione non è in esecuzione. In genere ciò comporta l'attivazione e l'spegnimento degli oggetti switch o la modifica dei livelli di traccia e quindi il riavvio dell'applicazione.

Quando si crea un'istanza di un interruttore, è necessario inizializzarla specificando due argomenti: un argomento displayName e un argomento description. L'argomento displayName del costruttore imposta la Switch.DisplayName proprietà dell'istanza della Switch classe . DisplayName è il nome utilizzato per configurare l'opzione nel file .config e l'argomento description deve restituire una breve descrizione dell'opzione e i messaggi che controlla.

Oltre a specificare il nome di un'opzione da configurare, è necessario specificare anche un valore per l'opzione. Questo valore è un valore Integer. Per BooleanSwitch, il valore 0 corrisponde a Off e qualsiasi valore diverso da zero corrisponde a On. Per TraceSwitch, rispettivamente 0,1,2,3 e 4 corrispondono Off, Error, Warning, Info e Verbose. Qualsiasi numero maggiore di 4 viene considerato Verbose e qualsiasi numero minore di zero viene considerato Off.

Per consentire agli utenti finali di configurare le opzioni di traccia di un'applicazione, è necessario fornire documentazione dettagliata sulle opzioni nell'applicazione. È consigliabile specificare quali commutatori controllano cosa e come attivarli e disattivarli. È anche consigliabile fornire all'utente finale un file di .config con la Guida appropriata nei commenti.

Per configurare gli interruttori di traccia

1. Per usare le opzioni di traccia, è prima necessario crearle e inserirle nel codice come descritto nella sezione Creazione e inizializzazione di un commutatore 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.

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

   • Visual C#: Nella finestra di dialogo Aggiungi nuovo elemento scegliere File XML. Assegnare al file il nomeapp.config. Nell'editor XML, dopo la dichiarazione XML, aggiungere il codice XML seguente:

     <configuration>
     </configuration>
     

     Quando il progetto viene compilato, il file app.config viene copiato nella cartella di output del progetto e rinominato applicationname.exe.config.

3. Dopo il tag <configuration> ma prima del tag </configuration>, aggiungere il codice XML appropriato per configurare i switch. Negli esempi seguenti viene illustrato un 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 disattivate.

4. Se è necessario attivare un BooleanSwitch, come mostrato in DataMessagesSwitch, modificare il Value impostandolo su un numero intero diverso da 0.

5. Se è necessario attivare un traceSwitch, ad esempio TraceLevelSwitch illustrato nell'esempio precedente, modificare l'impostazione Valore impostando il livello appropriato (da 1 a 4).

6. Aggiungere commenti al file di .config in modo che l'utente finale abbia una chiara comprensione dei valori da modificare per configurare le opzioni in modo appropriato.

   L'esempio seguente mostra come potrebbe essere visualizzato il codice finale, inclusi i 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>
   

Vedere anche

• Tracciamento e strumentazione delle applicazioni
• Procedura: Aggiungere istruzioni di traccia al codice dell'applicazione
• Interruttori di traccia
• Schema delle impostazioni di traccia e debug