Diagnosing Errors with Managed Debugging Assistants

Managed debugging assistants (MDAs) are debugging aids that work in conjunction with the common language runtime (CLR) to provide information on runtime state. The assistants generate informational messages about runtime events that you cannot otherwise trap. You can use MDAs to isolate hard-to-find application bugs that occur when transitioning between managed and unmanaged code. You can enable or disable all MDAs by adding a key to the Windows registry or by setting an environment variable. You can enable specific MDAs by using application configuration settings. You can set additional configuration settings for some individual MDAs in the application's configuration file. Because these configuration files are parsed when the runtime is loaded, you must enable the MDA before the managed application starts. You cannot enable it for applications that have already started.

Note

When an MDA is enabled, it is active even when your code is not executing under a debugger. 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. To avoid the dialog box, remove the MDA-enabling settings when your code is not executing in a debugging environment.

Note

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. To do that, on the Debug menu, click Exceptions. (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. For example, to avoid the exception dialog box for a contextSwitchDeadlock MDA clear the Thrown check box next to its name in the Managed Debugging Assistants list. You can also use this dialog box to enable MDAs.

The following table lists the MDAs that ship with the .NET Framework.

asynchronousThreadAbort MDA	bindingFailure MDA
callbackOnCollectedDelegate MDA	contextSwitchDeadlock MDA
dangerousThreadingAPI MDA	dateTimeInvalidLocalFormat MDA
dirtyCastAndCallOnInterface MDA	disconnectedContext MDA
dllMainReturnsFalse MDA	exceptionSwallowedOnCallFromCom MDA
failedQI MDA	fatalExecutionEngineError MDA
gcManagedToUnmanaged MDA	gcUnmanagedToManaged MDA
illegalPrepareConstrainedRegion MDA	invalidApartmentStateChange MDA
invalidCERCall MDA	invalidFunctionPointerInDelegate MDA
invalidGCHandleCookie MDA	invalidIUnknown MDA
invalidMemberDeclaration MDA	invalidOverlappedToPinvoke MDA
invalidVariant MDA	jitCompilationStart MDA
loaderLock MDA	loadFromContext MDA
marshalCleanupError MDA	marshaling MDA
memberInfoCacheCreation MDA	moduloObjectHashcode MDA
nonComVisibleBaseClass MDA	notMarshalable MDA
openGenericCERCall MDA	overlappedFreeError MDA
pInvokeLog MDA	pInvokeStackImbalance MDA
raceOnRCWCleanup MDA	reentrancy MDA
releaseHandleFailed MDA	reportAvOnComRelease MDA
streamWriterBufferedDataLost MDA	virtualCERCall MDA

By default, the .NET Framework activates a subset of MDAs for all managed debuggers. You can view the default set in Visual Studio by clicking Exceptions on the Debug menu and expanding the Managed Debugging Assistants list.

Enabling and Disabling MDAs

You can enable and disable MDAs by using a registry key, an environment variable, and application configuration settings. You must enable either the registry key or the environment variable to use the application configuration settings.

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. The hosting process is enabled by default, so it must be explicitly disabled.

To disable the hosting process in Visual Studio, do the following:

1. In Solution Explorer, select a project.

2. On the Project menu, click Properties.

   The Project Designer window appears.

3. Click the Debug tab.

4. In the Enable Debuggers section, clear the Enable the Visual Studio hosting process check box.

However, disabling the hosting process can affect performance. You can avoid the need to disable MDAs by preventing Visual Studio from displaying the MDA dialog box whenever an MDA notification is received. 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.

Enabling and Disabling MDAs by Using a Registry Key

You can enable MDAs by adding the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\MDA subkey (type REG_SZ, value 1) in the Windows registry. Copy the following example into a text file named MDAEnable.reg and double-click the file name in Windows Explorer to enable MDAs on that computer.

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework]
"MDA"="1"

To disable MDAs, set the MDA subkey to 0 (zero) using the Windows Registry Editor. Alternatively, you can copy the following example into a text file named MDADisable.reg and double-click the file name in Windows Explorer.

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework]
"MDA"="0"

By default, some MDAs are enabled when you run an application that is attached to a debugger, even without adding the registry key. Examples of such assistants are pInvokeStackImbalance MDA and invalidApartmentStateChange MDA. You can disable these assistants by running the MDADisable.reg file as described earlier in this section.

Enabling and Disabling MDAs by Using an Environment Variable

MDA activation can also controlled by the environment variable COMPLUS_MDA, which overrides the registry key. The COMPLUS_MDA string is a case-insensitive, semicolon-delimited list of MDA names or other special control strings. Starting under a managed or unmanaged debugger enables a set of MDAs by default. 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. The special control strings are the following:

• 0 - Deactivates all MDAs.

• 1 - Reads MDA settings from ApplicationName.mda.config.

• managedDebugger - Explicitly activates all MDAs that are implicitly activated when a managed executable is started under a debugger.

• unmanagedDebugger - Explicitly activates all MDAs that are implicitly activated when an unmanaged executable is started under a debugger.

If there are conflicting settings, the most recent settings override previous settings:

• COMPLUS_MDA=0 disables all MDAs, including those implicitly enabled under a debugger.

• COMPLUS_MDA=gcUnmanagedToManaged enables gcUnmanagedToManaged in addition to any MDAs that are implicitly enabled under a debugger.

• COMPLUS_MDA=0;gcUnmanagedToManaged enables gcUnmanagedToManaged but disables MDAs that would otherwise be implicitly enabled under a debugger.

Enabling and Disabling MDAs by Using Application-Specific Configuration Settings

You can enable, disable, and configure some assistants individually in the MDA configuration file for the application. 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. The application configuration file is typically located in the same directory as the application's executable (.exe) file. 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. The following example shows how to enable and configure the marshaling MDA.

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

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. The Marshaling MDA can also filter the names of the method and structure fields supplied in the <methodFilter> and <fieldFilter> child elements, respectively.

The following example shows how to enable multiple MDAs by using their default settings.

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

Important
When you specify more than one assistant in a configuration file, you must list them in alphabetical order. For example, if you want to enable both the virtualCERCall and the invalidCERCall MDAs, you must add the <invalidCERCall /> entry before the <virtualCERCall /> entry. If the entries are not in alphabetical order, an unhandled invalid configuration file exception message is displayed.

MDA Output

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.

See Also

Other Resources

Debugging, Tracing, and Profiling