Diagnóstico de errores con asistentes de depuraciones administradasDiagnosing Errors with Managed Debugging Assistants

Los asistentes de depuración administrada (MDA) son ayudas para la depuración que funcionan en conjunción con Common Language Runtime (CLR) para proporcionar información sobre estado en tiempo de ejecución.Managed debugging assistants (MDAs) are debugging aids that work in conjunction with the common language runtime (CLR) to provide information on runtime state. Los asistentes generan mensajes informativos sobre eventos en tiempo de ejecución que de otra forma no pueden interceptar.The assistants generate informational messages about runtime events that you cannot otherwise trap. Puede utilizar MDA para aislar errores de la aplicación difíciles de encontrar que aparecen al realizar la transición entre código administrado y no administrado.You can use MDAs to isolate hard-to-find application bugs that occur when transitioning between managed and unmanaged code. Puede habilitar o deshabilitar todos los MDA si agrega una clave al Registro de Windows o establece una variable de entorno.You can enable or disable all MDAs by adding a key to the Windows registry or by setting an environment variable. Puede habilitar MDA específicos mediante los valores de configuración de la aplicación.You can enable specific MDAs by using application configuration settings. Puede establecer opciones de configuración adicionales para algunos MDA concretos en el archivo de configuración de la aplicación.You can set additional configuration settings for some individual MDAs in the application's configuration file. Dado que estos archivos de configuración se analizan cuando se carga el motor en tiempo de ejecución, debe habilitar el MDA antes de que se inicie la aplicación administrada.Because these configuration files are parsed when the runtime is loaded, you must enable the MDA before the managed application starts. No puede habilitarlo para aplicaciones que ya se han iniciado.You cannot enable it for applications that have already started.

Nota

Cuando se habilita un asistente para la depuración administrada (MDA), está activo aunque el código no se esté ejecutando en un depurador.When an MDA is enabled, it is active even when your code is not executing under a debugger. Si se genera un evento MDA cuando un depurador no está presente, el mensaje del evento se presenta en un cuadro de diálogo de excepción no controlada, aunque no se trata de una excepción no controlada.If an MDA event is raised when a debugger is not present, the event message is presented in an unhandled exception dialog box, although it is not an unhandled exception. Para evitar el cuadro de diálogo, quite las opciones que habilitan MDA cuando el código no se está ejecutando en un entorno de depuración.To avoid the dialog box, remove the MDA-enabling settings when your code is not executing in a debugging environment.

Nota

Cuando el código se ejecuta en el entorno de desarrollo integrado (IDE) de Visual Studio, puede evitar el cuadro de diálogo de excepciones que aparece con determinados eventos de MDA.When your code is executing in the Visual Studio integrated development environment (IDE), you can avoid the exception dialog box that appears for specific MDA events. Para ello, en el menú Depurar, haga clic en Excepciones.To do that, on the Debug menu, click Exceptions. (Si el menú Depurar no contiene el comando Excepciones, haga clic en Personalizar en el menú Herramientas para agregarlo). En el cuadro de diálogo Excepciones, expanda la lista Asistentes para la depuración administrada y, después, desactive la casilla Producida de cada MDA.(If the Debug menu does not contain an Exceptions command, click Customize on the Tools menu to add it.) In the Exceptions dialog box, expand the Managed Debugging Assistants list, and then clear the Thrown check box for the individual MDA. Por ejemplo, para evitar el cuadro de diálogo de excepciones de contextSwitchDeadlock, desactive la casilla Producida situada junto a su nombre en la lista Asistentes para la depuración administrada.For example, to avoid the exception dialog box for a contextSwitchDeadlock clear the Thrown check box next to its name in the Managed Debugging Assistants list. También puede usar este cuadro de diálogo para habilitar la presentación de los cuadros de diálogo de excepciones de MDA.You can also use this dialog box to enable the display of MDA exception dialog boxes.

La tabla siguiente muestra los MDA incluidos con .NET Framework.The following table lists the MDAs that ship with the .NET Framework.

asynchronousThreadAbortasynchronousThreadAbort bindingFailurebindingFailure
callbackOnCollectedDelegatecallbackOnCollectedDelegate contextSwitchDeadlockcontextSwitchDeadlock
dangerousThreadingAPIdangerousThreadingAPI dateTimeInvalidLocalFormatdateTimeInvalidLocalFormat
dirtyCastAndCallOnInterfacedirtyCastAndCallOnInterface disconnectedContextdisconnectedContext
dllMainReturnsFalsedllMainReturnsFalse exceptionSwallowedOnCallFromComexceptionSwallowedOnCallFromCom
failedQIfailedQI fatalExecutionEngineErrorfatalExecutionEngineError
gcManagedToUnmanagedgcManagedToUnmanaged gcUnmanagedToManagedgcUnmanagedToManaged
illegalPrepareConstrainedRegionillegalPrepareConstrainedRegion invalidApartmentStateChangeinvalidApartmentStateChange
invalidCERCallinvalidCERCall invalidFunctionPointerInDelegateinvalidFunctionPointerInDelegate
invalidGCHandleCookieinvalidGCHandleCookie invalidIUnknowninvalidIUnknown
invalidMemberDeclarationinvalidMemberDeclaration invalidOverlappedToPinvokeinvalidOverlappedToPinvoke
invalidVariantinvalidVariant jitCompilationStartjitCompilationStart
loaderLockloaderLock loadFromContextloadFromContext
marshalCleanupErrormarshalCleanupError marshalingmarshaling
memberInfoCacheCreationmemberInfoCacheCreation moduloObjectHashcodemoduloObjectHashcode
nonComVisibleBaseClassnonComVisibleBaseClass notMarshalablenotMarshalable
openGenericCERCallopenGenericCERCall overlappedFreeErroroverlappedFreeError
pInvokeLogpInvokeLog pInvokeStackImbalancepInvokeStackImbalance
raceOnRCWCleanupraceOnRCWCleanup reentrancyreentrancy
releaseHandleFailedreleaseHandleFailed reportAvOnComReleasereportAvOnComRelease
streamWriterBufferedDataLoststreamWriterBufferedDataLost virtualCERCallvirtualCERCall

De forma predeterminada, .NET Framework activa un subconjunto de MDA para todos los depuradores administrados.By default, the .NET Framework activates a subset of MDAs for all managed debuggers. Para ver el valor predeterminado en Visual Studio, haga clic en Excepciones en el menú Depurar, y expanda la lista Asistentes para la depuración administrada.You can view the default set in Visual Studio by clicking Exceptions on the Debug menu and expanding the Managed Debugging Assistants list.

Habilitar y deshabilitar MDAEnabling and Disabling MDAs

Puede habilitar y deshabilitar los MDA mediante una clave del Registro, una variable de entorno o valores de configuración de la aplicación.You can enable and disable MDAs by using a registry key, an environment variable, and application configuration settings. La clave del Registro o la variable de entorno tienen que estar habilitadas para utilizar los valores de configuración de la aplicación.You must enable either the registry key or the environment variable to use the application configuration settings.

En Visual Studio 2005 y versiones posteriores, cuando se habilita el proceso de hospedaje, no se pueden deshabilitar los MDA que están en el conjunto predeterminado ni habilitar los MDA que no están en el conjunto predeterminado.In Visual Studio 2005 and later versions, when the hosting process is enabled, you cannot disable MDAs that are in the default set or enable MDAs that are not in the default set. De forma predeterminada, el proceso de hospedaje está habilitado, por lo que debe deshabilitarse explícitamente.The hosting process is enabled by default, so it must be explicitly disabled.

Para deshabilitar el proceso de hospedaje en Visual Studio, haga lo siguiente:To disable the hosting process in Visual Studio, do the following:

  1. En el Explorador de soluciones, seleccione un proyecto.In Solution Explorer, select a project.

  2. En el menú Proyecto, haga clic en Propiedades.On the Project menu, click Properties.

    Aparece la ventana Diseñador de proyectos.The Project Designer window appears.

  3. Haga clic en la pestaña Depurar.Click the Debug tab.

  4. En la sección Habilitar depuradores, desactive la casilla Habilitar el proceso de hospedaje de Visual Studio.In the Enable Debuggers section, clear the Enable the Visual Studio hosting process check box.

Sin embargo, deshabilitar el proceso de hospedaje puede afectar al rendimiento.However, disabling the hosting process can affect performance. Para que no sea necesario deshabilitar los MDA, no permita que Visual Studio muestre el cuadro de diálogo MDA cuando se reciba una notificación de MDA.You can avoid the need to disable MDAs by preventing Visual Studio from displaying the MDA dialog box whenever an MDA notification is received. Para ello, haga clic en Excepciones en el menú Depurar, expanda la lista Asistentes para la depuración administrada y, después, active o desactive la casilla Producida del MDA individual.To do that, click Exceptions on the Debug menu, expand the Managed Debugging Assistants list, and then select or clear the Thrown check box for the individual MDA.

Habilitar y deshabilitar MDA utilizando una clave del RegistroEnabling and Disabling MDAs by Using a Registry Key

Puede habilitar MDA agregando la subclave HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\MDA (tipo REG_SZ, valor 1) al Registro de Windows.You can enable MDAs by adding the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\MDA subkey (type REG_SZ, value 1) in the Windows registry. Copie el ejemplo siguiente en un archivo de texto denominado MDAEnable.reg. Abra el Editor del Registro de Windows (RegEdit.exe) y desde el menú Archivo elija Importar.Copy the following example into a text file named MDAEnable.reg. Open the Windows Registry Editor (RegEdit.exe) and from the File menu choose Import. Seleccione el archivo MDAEnable.reg para habilitar los MDA en ese equipo.Select the MDAEnable.reg file to enable MDAs on that computer. Si se establece la subclave en un valor de cadena de 1 (no en un valor DWORD de 1), se habilita la lectura de la configuración de MDA del archivo NombreAplicación.sufijo.mda.config.Setting the subkey to string value of 1 (not DWORD value of 1) enables the reading of MDA settings from the ApplicationName.suffix.mda.config file. (Por ejemplo, el archivo de configuración de MDA para el Bloc de notas [notepad] se llamaría notepad.exe.mda.config).(For example the MDA configuration file for Notepad would be named notepad.exe.mda.config)

Windows Registry Editor Version 5.00  

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework]  
"MDA"="1"  

Si el equipo ejecuta una aplicación de 32 bits en un sistema operativo de 64 bits, la clave de MDA debe establecerse de la forma siguiente:If the computer is running a 32-bit application on a 64-bit operating system, then the MDA key should be set like the following:

      Windows Registry Editor Version 5.00   

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework]  
"MDA"="1"  

Para obtener más información, vea Habilitar y deshabilitar MDA usando valores de configuración específicos de la aplicación.See Enabling and Disabling MDAs by Using Application-Specific Configuration Settings for more information. La variable de entorno COMPLUS_MDA puede invalidar la configuración del Registro.The registry setting can be overridden by the COMPLUS_MDA environment variable. Vea Habilitar y deshabilitar MDA usando una variable de entorno para obtener más información.See Enabling and Disabling MDAs by Using an Environment Variable for more information.

Para deshabilitar MDA, establezca la subclave MDA en 0 (cero) utilizando el Editor del Registro de Windows.To disable MDAs, set the MDA subkey to 0 (zero) using the Windows Registry Editor.

De forma predeterminada, algunos MDA están habilitados cuando se ejecuta una aplicación asociada a un depurador, incluso sin agregar la clave del Registro.By default, some MDAs are enabled when you run an application that is attached to a debugger, even without adding the registry key. Ejemplos de estos asistentes son pInvokeStackImbalance e invalidApartmentStateChange.Examples of such assistants are pInvokeStackImbalance and invalidApartmentStateChange. Puede deshabilitar estos asistentes ejecutando el archivo MDADisable.reg como se explica anteriormente en esta sección.You can disable these assistants by running the MDADisable.reg file as described earlier in this section.

Habilitar y deshabilitar MDA utilizado una variable de entornoEnabling and Disabling MDAs by Using an Environment Variable

La activación de MDA también puede controlarse mediante la variable de entorno COMPLUS_MDA, que reemplaza la clave del Registro.MDA activation can also controlled by the environment variable COMPLUS_MDA, which overrides the registry key. La cadena COMPLUS_MDA es una lista delimitada por puntos y comas de nombres de MDA u otras cadenas de control especiales, y no distingue entre mayúsculas y minúsculas.The COMPLUS_MDA string is a case-insensitive, semicolon-delimited list of MDA names or other special control strings. Al iniciar bajo un depurador administrado o no administrado se habilita de forma predeterminada un conjunto de MDA.Starting under a managed or unmanaged debugger enables a set of MDAs by default. Esto se realiza anteponiendo implícitamente al valor de la variable de entorno o de la clave del Registro la lista delimitada por puntos y comas de los MDA habilitados de manera predeterminada bajo depuradores.This is done by implicitly prepending the semicolon-delimited list of MDAs enabled by default under debuggers to the value of the environment variable or registry key. Las cadenas de control especiales son las siguientes:The special control strings are the following:

  • 0 - Desactiva todos los MDA.0 - Deactivates all MDAs.

  • 1: lee la configuración de MDA de NombreAplicación.mda.config.1 - Reads MDA settings from ApplicationName.mda.config.

  • managedDebugger - Activa explícitamente todos los MDA que se activan implícitamente cuando se inicia un ejecutable administrado bajo un depurador.managedDebugger - Explicitly activates all MDAs that are implicitly activated when a managed executable is started under a debugger.

  • unmanagedDebugger - Activa explícitamente todos los MDA que se activan implícitamente cuando se inicia un ejecutable no administrado bajo un depurador.unmanagedDebugger - Explicitly activates all MDAs that are implicitly activated when an unmanaged executable is started under a debugger.

Si hay ajustes contradictorios, los más recientes reemplazan los ajustes anteriores:If there are conflicting settings, the most recent settings override previous settings:

  • COMPLUS_MDA=0 deshabilita todos los MDA, incluidos los habilitados implícitamente bajo un depurador.COMPLUS_MDA=0 disables all MDAs, including those implicitly enabled under a debugger.

  • COMPLUS_MDA=gcUnmanagedToManaged habilita gcUnmanagedToManaged además de los MDA habilitados implícitamente bajo un depurador.COMPLUS_MDA=gcUnmanagedToManaged enables gcUnmanagedToManaged in addition to any MDAs that are implicitly enabled under a debugger.

  • COMPLUS_MDA=0;gcUnmanagedToManaged habilita gcUnmanagedToManaged pero deshabilita los MDA que, de otro modo, estarían habilitados implícitamente bajo un depurador.COMPLUS_MDA=0;gcUnmanagedToManaged enables gcUnmanagedToManaged but disables MDAs that would otherwise be implicitly enabled under a debugger.

Habilitar y deshabilitar MDA utilizando valores de configuración específicos de la aplicaciónEnabling and Disabling MDAs by Using Application-Specific Configuration Settings

Puede habilitar, deshabilitar y configurar individualmente algunos asistentes en el archivo de configuración de MDA para la aplicación.You can enable, disable, and configure some assistants individually in the MDA configuration file for the application. Para habilitar el uso de un archivo de configuración de la aplicación para configurar los MDA, es necesario establecer la clave del Registro MDA o la variable de entorno COMPLUS_MDA.To enable the use of an application configuration file for configuring MDAs, either the MDA registry key or the COMPLUS_MDA environment variable must be set. El archivo de configuración de la aplicación se encuentra normalmente en el mismo directorio que el archivo ejecutable (.exe) de la aplicación.The application configuration file is typically located in the same directory as the application's executable (.exe) file. El nombre de archivo toma el formato NombreAplicación.mda.config; por ejemplo, notepad.exe.mda.config. Los asistentes que están habilitados en el archivo de configuración de la aplicación pueden tener atributos o elementos diseñados específicamente para controlar el comportamiento de los citados asistentes.The file name takes the form ApplicationName.mda.config; for example, notepad.exe.mda.config. Assistants that are enabled in the application configuration file may have attributes or elements specifically designed to control that assistant's behavior. El ejemplo siguiente muestra cómo habilitar y configurar la serialización.The following example shows how to enable and configure the marshaling.

<mdaConfig>  
  <assistants>  
    <marshaling>  
      <methodFilter>  
        <match name="*"/>  
      </methodFilter>  
      <fieldFilter>  
        <match name="*"/>  
      </fieldFilter>  
    </marshaling>  
  </assistants>  
</mdaConfig>  

El MDA de Marshaling emite información sobre el tipo administrado cuyas referencias se calculan a un tipo no administrado para cada transición de administrado a no administrado en la aplicación.The Marshaling MDA emits information about the managed type that is being marshaled to an unmanaged type for each managed-to-unmanaged transition in the application. El MDA de Marshaling también puede filtrar los nombres de los campos de método y estructura proporcionados en los elementos secundarios <methodFilter> y <fieldFilter>, respectivamente.The Marshaling MDA can also filter the names of the method and structure fields supplied in the <methodFilter> and <fieldFilter> child elements, respectively.

En el siguiente ejemplo se muestra cómo habilitar varios MDA utilizando su configuración predeterminada.The following example shows how to enable multiple MDAs by using their default settings.

<mdaConfig>  
  <assistants>  
    <illegalPrepareConstrainedRegion />  
    <invalidCERCall />  
    <openGenericCERCall />  
    <virtualCERCall />  
  </assistants>  
</mdaConfig>  

Importante

Cuando se especifica más de un asistente en un archivo de configuración, se deben enumerar en orden alfabético.When you specify more than one assistant in a configuration file, you must list them in alphabetical order. Por ejemplo, si se desea habilitar los MDA virtualCERCall e invalidCERCall, se debe agregar la entrada <invalidCERCall /> antes que la entrada <virtualCERCall />.For example, if you want to enable both the virtualCERCall and the invalidCERCall MDAs, you must add the <invalidCERCall /> entry before the <virtualCERCall /> entry. Si las entradas no están en orden alfabético, se muestra un mensaje de excepción no controlada de archivo de configuración no válido.If the entries are not in alphabetical order, an unhandled invalid configuration file exception message is displayed.

Salida del MDAMDA Output

El resultado del MDA es similar al ejemplo siguiente, que muestra el resultado del MDA pInvokeStackImbalance.MDA output is similar to the following example, which shows the output from the pInvokeStackImbalance MDA.

A call to PInvoke function 'MDATest!MDATest.Program::StdCall' has unbalanced the stack. This is likely because the managed PInvoke signature does not match the unmanaged target signature. Check that the calling convention and parameters of the PInvoke signature match the target unmanaged signature.

Vea tambiénSee Also

Depurar, trazar y generar perfilesDebugging, Tracing, and Profiling