If you use methods in the Debug class to print debugging information and check your logic with assertions, you can make your code more robust without affecting the performance and code size of your shipping product.

This class provides methods to display an Assert dialog box, and to emit an assertion that will always fail. This class provides write methods in the following variations: Write, WriteLine, WriteIf, and WriteLineIf.

The BooleanSwitch and TraceSwitch classes provide ways to dynamically control the tracing output. You can modify the values of these switches without recompiling your application. For information about using the configuration file to set a switch, see the Switch class and the Trace Switches topic.

You can customize the tracing output's target by adding TraceListener instances to, or removing instances from, the Listeners collection. The Listeners collection is shared by both the Debug and the Trace classes; adding a trace listener to either class adds the listener to both. By default, the DefaultTraceListener class emits trace output.

Note

Adding a trace listener to the Listeners collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the Debug methods in try/catch blocks to detect and handle any exceptions from trace listeners.

You can modify the level of indentation by using the Indent method or the IndentLevel property. To modify the indentation amount, use the IndentSize property. You can specify whether to automatically flush the output buffer after each write operation by setting the AutoFlush property to true.

To set the AutoFlush and IndentSize for Debug, you can edit the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example.

<configuration>
  <system.diagnostics>
    <trace autoflush="true" indentsize="7" />
  </system.diagnostics>
</configuration>

The ConditionalAttribute attribute is applied to the methods of Debug. Compilers that support ConditionalAttribute ignore calls to these methods unless "DEBUG" is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether ConditionalAttribute is supported and the syntax for defining a conditional compilation symbol.

Note
In Visual Studio C# and Visual Basic projects, by default, the "DEBUG" conditional compilation symbol is defined for debug builds, and the "TRACE" symbol is defined for both debug and release builds. For information about how to disable this behavior, see the Visual Studio documentation. For information about conditional debugging in Visual C++, see The Debug Class in Visual C++.

To define the "DEBUG" conditional compilation symbol in C#, add the /d:DEBUG option to the compiler command line when you compile your code using a command line, or add #define DEBUG to the top of your file. In Visual Basic, add the /d:DEBUG=True option to the compiler command line or add #Const DEBUG=True to the file.

The following example uses Debug to indicate the beginning and end of a program's execution. The example also uses the Indent and Unindent methods to distinguish the tracing output.

' Specify /d:DEBUG=True when compiling.

Imports System
Imports System.Data
Imports System.Diagnostics

Class Test

    Shared Sub Main()

        Debug.Listeners.Add(New TextWriterTraceListener(Console.Out))
        Debug.AutoFlush = True
        Debug.Indent()
        Debug.WriteLine("Entering Main")
        Console.WriteLine("Hello World.")
        Debug.WriteLine("Exiting Main")
        Debug.Unindent()

    End Sub

End Class

// Specify /d:DEBUG when compiling.

using System;
using System.Data;
using System.Diagnostics;

class Test
{
    static void Main()
    {
       Debug.Listeners.Add(new TextWriterTraceListener(Console.Out));
       Debug.AutoFlush = true;
       Debug.Indent();
       Debug.WriteLine("Entering Main");
       Console.WriteLine("Hello World.");
       Debug.WriteLine("Exiting Main"); 
       Debug.Unindent();
    }
}

// Specify /DDEBUG when compiling.

#using <System.dll>
using namespace System;
using namespace System::Diagnostics;

int main( void )
{
   #if defined(DEBUG)
   Debug::Listeners->Add( gcnew TextWriterTraceListener( Console::Out ) );
   Debug::AutoFlush = true;
   Debug::Indent();
   Debug::WriteLine( "Entering Main" );
   #endif
   Console::WriteLine( "Hello World." );
   #if defined(DEBUG)
   Debug::WriteLine( "Exiting Main" );
   Debug::Unindent();
   #endif
   return 0;
}

.NET Framework

.NET Framework Client Profile

Portable Class Library

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role not supported), Windows Server 2003 SP2

This type is thread safe.

Reference

Si utiliza los métodos de la clase Debug para imprimir la información de depuración y comprobar la lógica con aserciones, puede hacer que el código sea más sólido sin que ello repercuta en el rendimiento y en el tamaño del código del producto de distribución.

Esta clase proporciona métodos para mostrar un cuadro de diálogo Assert y emitir una aserción que siempre produzca un error. Esta clase proporciona métodos de escritura en las variaciones siguientes: Write, WriteLine, WriteIf y WriteLineIf.

Las clases BooleanSwitch y TraceSwitch proporcionan medios para controlar de forma dinámica los resultados de la traza. Se pueden cambiar los valores de estos modificadores sin volver a compilar la aplicación. Para obtener información acerca de cómo utilizar el archivo de configuración para establecer un modificador, vea la clase Switch y el tema Modificadores de seguimiento.

Para personalizar el destino de los resultados de la traza, agregue o quite instancias de TraceListener de la colección Listeners. La colección Listeners es compartida por las clases Debug y Trace; si agrega un agente de escucha de traza a cualquiera de las clases, éste se agrega a ambas. De forma predeterminada, la clase DefaultTraceListener emite resultados de seguimiento.

Nota

Al agregar un agente de escucha de seguimiento a la colección Listeners se puede originar una excepción que se producirá mientras tiene lugar la traza, si el recurso utilizado por el agente de escucha de traza no está disponible. Las condiciones y la excepción producidas dependen del agente de escucha de seguimiento y no se pueden enumerar en este tema. Puede ser útil para llamar a los métodos Debug en bloques try/catch para detectar y administrar cualquier excepción de los agentes de escucha de seguimiento.

Se puede modificar el nivel de sangría con el método Indent o la propiedad IndentLevel. Para modificar la cantidad de aplicar sangría, utilice la propiedad IndentSize. Es posible especificar si hay que vaciar de forma automática el búfer de resultados después de cada operación de escritura; para ello, hay que establecer la propiedad AutoFlush en true.

Con el fin de establecer las propiedades AutoFlush e IndentSize para Debug, se puede modificar el archivo de configuración que corresponde al nombre de la aplicación. El archivo de configuración debería tener el formato que se muestra en el siguiente ejemplo.

<configuration>
  <system.diagnostics>
    <trace autoflush="true" indentsize="7" />
  </system.diagnostics>
</configuration>

El atributo ConditionalAttribute se aplica a los métodos de Debug. Los compiladores que admiten ConditionalAttribute omiten las llamadas a estos métodos a menos que se defina "DEBUG" como símbolo de compilación condicional. Consulte la documentación de un compilador para determinar si se admite ConditionalAttribute y la sintaxis para definir un símbolo de compilación condicional.

Nota

De forma predeterminada, en los proyectos de Visual Studio C# y Visual Basic se define el símbolo de compilación condicional "DEBUG" para las versiones de depuración y el símbolo "TRACE" para las versiones de depuración y de lanzamiento. Para obtener información sobre cómo deshabilitar este comportamiento, vea la documentación de Visual Studio. Para obtener información acerca de la depuración condicional en Visual C++, vea Debug (Clase) (C++/CLI).

Para definir el símbolo de compilación condicional "DEBUG" en C# y J#, agregue la opción /d:DEBUG a la línea de comandos del compilador cuando compile su código mediante una línea de comandos, o bien agregue #define DEBUG a la parte superior del archivo. En Visual Basic, agregue la opción /d:DEBUG=True a la línea de comandos del compilador o agregue #Const DEBUG=True al archivo.

En el siguiente ejemplo se utiliza Debug para indicar el comienzo y el fin de la ejecución de un programa. También se utilizan los métodos Indent y Unindent para distinguir los resultados de la traza.

' Specify /d:DEBUG=True when compiling.

Imports System
Imports System.Data
Imports System.Diagnostics

Class Test

    Shared Sub Main()

        Debug.Listeners.Add(New TextWriterTraceListener(Console.Out))
        Debug.AutoFlush = True
        Debug.Indent()
        Debug.WriteLine("Entering Main")
        Console.WriteLine("Hello World.")
        Debug.WriteLine("Exiting Main")
        Debug.Unindent()

    End Sub

End Class

// Specify /d:DEBUG when compiling.

using System;
using System.Data;
using System.Diagnostics;

class Test
{
    static void Main()
    {
       Debug.Listeners.Add(new TextWriterTraceListener(Console.Out));
       Debug.AutoFlush = true;
       Debug.Indent();
       Debug.WriteLine("Entering Main");
       Console.WriteLine("Hello World.");
       Debug.WriteLine("Exiting Main"); 
       Debug.Unindent();
    }
}

// Specify /DDEBUG when compiling.

#using <System.dll>
using namespace System;
using namespace System::Diagnostics;

int main( void )
{
   #if defined(DEBUG)
   Debug::Listeners->Add( gcnew TextWriterTraceListener( Console::Out ) );
   Debug::AutoFlush = true;
   Debug::Indent();
   Debug::WriteLine( "Entering Main" );
   #endif
   Console::WriteLine( "Hello World." );
   #if defined(DEBUG)
   Debug::WriteLine( "Exiting Main" );
   Debug::Unindent();
   #endif
   return 0;
}

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 o posterior, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (no se admite Server Core), Windows Server 2008 R2 (se admite Server Core con SP1 o posterior), Windows Server 2003 SP2

Este tipo es seguro para la ejecución de subprocesos.

Referencia