Managed Debugging Assistant Configuration Files

MDAs (Managed Debugging Assistants) are a feature of the CLR that help track down difficult-to-diagnose bugs in complex areas such as interop and threading. Basic information about MDAs can be found in the MSDN Library topic, Stephen Toub’s MSDN magazine article, and Mike Stall’s blog post. For fine-grained control over the MDAs that are enabled for an application (or to use MDAs without running the application under the Visual Studio debugger), you need to use an application-specific configuration file (as well as setting the MDA registry key or COMPLUS_MDA environment variable, as detailed in those articles). Unfortunately, advanced MDA usage (with an application-specific config file) can itself be a complex and difficult-to-diagnose process.

For starters, the config file must be named properly. Like a regular application config file, the name of this file needs to include the full name of the program (including the “.exe” suffix), followed by “.mda.config”, e.g., MdaTest.exe.mda.config.

I don’t know of any way to check that the MDA configuration is being read, apart from deliberately introducing an error (see below) and seeing if the runtime raises the “InvalidConfigFile” MDA when the application is run.

If there is an error in the MDA config file, the following message will be displayed when the application is run:

If you’re running the application under WinDbg, you’ll see the following message instead:

<mda:msg xmlns:mda="http://schemas.microsoft.com/CLR/2004/10/mda"> 
  <!-- 
       The 'mdaConfig' configuration file is invalid. 
   --> 
  <mda:invalidConfigFileMsg break="true" configFile="mdaConfig"/> 
</mda:msg>

There are two main causes I’ve found for this error.

1. Incorrect XML element names. Double-check every XML element and attribute name to ensure it’s spelt correctly. The basic structure of the config file is:

<mdaConfig>
    <assistants>
        <!-- MDA elements go here -->
    </assistants>
</mdaConfig>

If any of the element names are not recognised, the InvalidConfigFile error will occur. Note that the online MSDN documentation for .NET 2.0 and .NET 3.0 has incorrect examples; be sure you’re using the .NET 3.5 version of the documentation. (For example, this 2.0 page says to use <fatalExecutionError />, but the equivalent 3.5 page correctly gives <fatalExecutionEngineError /> as the configuration element name.)

The MDA parser doesn’t seem to log any information about why the config file is invalid; to determine the element causing the problem, remove all the elements from the config file and add them back in one-by-one (running the application after each addition) until you find the one that causes the problem.

1. Incorrectly ordered XML elements. The MDA configuration elements must be in alphabetical order, or the file will not load properly. So, this will not work:

<assistants>
    <bindingFailure/>
    <asynchronousThreadAbort/>
</assistants>

but this will:

<assistants>
    <asynchronousThreadAbort/>
    <bindingFailure/>
</assistants>

One final thing to note is that Visual Studio uses the settings in the Debug > Exceptions dialog and ignores the MDA config file when the application is started under the VS debugger. To debug with the MDA config file settings, use WinDbg or attach the Visual Studio debugger to the process after it has started.

Posted by Bradley Grainger on April 03, 2008