Procedimiento para crear, inicializar y configurar modificadores de seguimiento

Los modificadores de seguimiento permiten habilitar, deshabilitar y filtrar la salida del seguimiento.

Crear e inicializar modificadores de seguimiento

Para poder usar los modificadores de seguimiento, primero debe crearlos y colocarlos en el código. Existen dos clases predefinidas desde las que puede crear objetos modificadores: la clase System.Diagnostics.BooleanSwitch y la clase System.Diagnostics.TraceSwitch. Debe usar BooleanSwitch si solo le preocupa si aparece o no un mensaje de seguimiento, y TraceSwitch para distinguir entre los niveles de seguimiento. Si utiliza TraceSwitch, puede definir sus propios mensajes de depuración y asociarlos a diferentes niveles de seguimiento. Puede utilizar ambos tipos de modificadores con el seguimiento o la depuración. De forma predeterminada, BooleanSwitch está deshabilitado y TraceSwitch está establecido en el nivel TraceLevel.Off. Los modificadores de seguimiento pueden crearse y colocarse en cualquier parte del código que pueda utilizarlos.

Aunque puede establecer niveles de seguimiento y otras opciones de configuración en el código, le recomendamos que utilice el archivo de configuración para administrar el estado de los modificadores. El motivo es que administrar la configuración de los modificadores en el sistema de configuración le proporciona mayor flexibilidad: puede activar y desactivar los diversos modificadores y cambiar los niveles sin volver a compilar la aplicación.

Para crear e inicializar modificadores de seguimiento

1. Defina un modificador de tipo System.Diagnostics.BooleanSwitch o tipo System.Diagnostics.TraceSwitch y establezca el nombre y la descripción del modificador.

2. Configure el modificador de seguimiento. Para más información, vea Configuración de modificadores de seguimiento.

   El siguiente código crea dos modificadores, uno de cada 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");  
   

Configuración de modificadores de seguimiento

Después de que se distribuya la aplicación, puede habilitar o deshabilitar el resultado del seguimiento configurando los modificadores de seguimiento de la aplicación. Configurar un modificador consiste en cambiar su valor desde un origen externo después de que se inicialice. Puede cambiar los valores de los objetos modificadores con el archivo de configuración. Puede configurar un modificador de seguimiento para activarlo y desactivarlo, o para establecer su nivel y determinar la cantidad y el tipo de mensajes que pasa a los agentes de escucha.

Los modificadores se configuran con el archivo .config. En una aplicación web, es el archivo Web.config asociado al proyecto. En una aplicación de Windows, este archivo se denomina (nombre de aplicación).exe.config. En una aplicación implementada, este archivo debe residir en la misma carpeta que el ejecutable.

Cuando la aplicación ejecuta el código que crea una instancia de un modificador por primera vez, la aplicación comprueba el archivo de configuración para obtener información de nivel de seguimiento sobre el modificador con nombre. El sistema de seguimiento examina el archivo de configuración una sola vez con cada modificador, la primera vez que la aplicación crea el modificador.

En una aplicación implementada, el código de seguimiento se habilita volviendo a configurar los modificadores cuando la aplicación no se está ejecutando. Normalmente, esto implica activar y desactivar los modificadores cambiando los niveles de seguimiento y, luego, reiniciar la aplicación.

Cuando crea una instancia de un modificador, también la inicializa especificando dos argumentos: un argumento displayName y un argumento description. El argumento displayName del constructor establece la propiedad Switch.DisplayName de la instancia de clase Switch. displayName es el nombre que se usa para configurar el modificador en el archivo .config, y el argumento description debería devolver una breve descripción del modificador e indicar qué mensajes controla.

Además de especificar el nombre de un modificador para configurarlo, también debe especificar un valor para el modificador. El valor es un entero. Para BooleanSwitch, un valor de 0 corresponde a Desactivado, y cualquier valor distinto de cero corresponde a Activado. Para TraceSwitch, 0, 1, 2, 3 y 4 corresponden a Desactivado, Error, Advertencia, Información y Detallado, respectivamente. Todos los números mayores de 4 se tratan como Detallado, y todos los números menores de cero se tratan como Desactivado.

Para que los usuarios finales puedan configurar los modificadores de seguimiento de una aplicación, debe proporcionar documentación detallada sobre los modificadores de la aplicación. Debe detallar qué modificadores controlan qué y cómo activarlos y desactivarlos. También debe proporcionar al usuario final un archivo .config con una ayuda apropiada en los comentarios.

Para configurar modificadores de seguimiento

1. Para usar modificadores de seguimiento, primero debe crearlos y colocarlos en el código como se describe en la sección Crear e inicializar modificadores de seguimiento.

2. Si el proyecto no contiene un archivo de configuración (app.config o Web.config), en el menú Proyecto seleccione Agregar nuevo elemento.

   • Visual Basic: en el cuadro de diálogo Agregar nuevo elemento, elija Archivo de configuración de aplicaciones.

     El archivo de configuración de la aplicación se creará y se abrirá. Se trata de un documento XML cuyo elemento raíz es <configuration>.

   • Visual C#: en el cuadro de diálogo Agregar nuevo elemento elija Archivo XML. Ponga a este archivo el nombre app.config. En el editor XML, después de la declaración de XML, agregue el siguiente código XML:

     <configuration>  
     </configuration>  
     

     Cuando se compila el proyecto, el archivo app.config se copia en la carpeta de salida del proyecto y se cambia su nombre a nombreDeLaAplicación.exe.config.

3. Después de la etiqueta <configuration>, pero antes de la etiqueta </configuration>, agregue el código XML adecuado para configurar los modificadores. En los ejemplos siguientes se muestra un BooleanSwitch con una propiedad DisplayName de DataMessageSwitch y un TraceSwitch con una propiedad DisplayName de TraceLevelSwitch.

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

   En esta configuración, ambos modificadores están desactivados.

4. Si necesita activar BooleanSwitch, como DataMessagesSwitch mostrado en el ejemplo anterior, cambie Value por cualquier entero distinto de 0.

5. Si necesita activar TraceSwitch, como TraceLevelSwitch mostrado en el ejemplo anterior, cambie Value por el ajuste del nivel adecuado (del 1 al 4).

6. Agregue comentarios al archivo .config para que el usuario final entienda claramente qué valores debe cambiar para configurar los modificadores de la manera correcta.

   En el ejemplo siguiente se muestra cómo podría quedar el código final, incluidos los comentarios:

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

Consulte también

• Seguimiento e instrumentación de aplicaciones
• Adición de instrucciones de seguimiento al código de la aplicación
• Modificadores de seguimiento
• Esquema de la configuración de seguimiento y depuración