How to get a V2.0 ICorDebug object

I think the biggest breaking change in the ICorDebug API is how we deal with versioning.

Managed debugging is done via the com-classic ICorDebug interface.

In v1.0/v1.1, you cocreate to get an ICorDebug implementation, like so:

        ICorDebug * cor;

        hr = CoCreateInstance(CLSID_CorDebug, NULL,

                              CLSCTX_INPROC_SERVER,

                              IID_ICorDebug,

                              (void **)&cor);

This has a few problems:

-         COM activation is evil because it means a more complex setup to update the registry. This allows bugs like “you need to reregister mscordbi.dll”. A quick google search shows that people hit this problem enough.

-         there are no version parameters in here

In v2.0, there is no longer a com coclass for ICorDebug. We still use the com-class ICorDebug interfaces, but we don’t use COM activation anymore. You now call a new API defined in mscoree.idl:

STDAPI CreateDebuggingInterfaceFromVersion(

int iDebuggerVersion,

LPCWSTR szDebuggeeVersion,

IUnknown ** ppCordb);

This takes version parameters. iDebuggerVersion is a constant from CorDebug.idl specifying the version of the API the client is built against.  szDebuggeeVersion is the version string of the debuggee. 

*ppCordb is an out parameter for the newly allocated com-object.

Here’s some sample code to use the new API:

    // Sample code to get an ICorDebug instance to debug v1.1.

    typedef HRESULT (STDAPICALLTYPE *FPCreateCordb)(int iDebuggerVersion, LPCWSTR szDebuggeeVersion, IUnknown ** ppCordb);

    // Must late bind to CreateDebuggingInterfaceFromVersion since it may not be installed.

    HMODULE hMscoree = LoadLibraryA("mscoree.dll");

    if (hMscoree == null) { /* Serious error, v2.0 runtime is not installed! */ }

    FPCreateCordb fpCreateCordb = (FPCreateCordb) GetProcAddress(m_hMscoree, "CreateDebuggingInterfaceFromVersion");

    if (fpCreateCordb == NULL) {  /* fail */ }

    const char * szDebuggeeVersion = “v1.1.4322”; // if we’re debugging a v1.1 debuggee

    const int iDebuggerVersion = CorDebugVersion_2_0; // if we’re a v2.0 debugger.

    hr = fpCreateCordb(CorDebugVersion_2_0, szEverettVersion, &pObject);

    if (FAILED(hr)) { /* fail */ }

    ICorDebug * cor;

    hr = pObject->QueryInterface(IID_ICorDebug, (void**) &cor);

    if (FAILED(hr)) { /* fail */ }

Note that MDbg in the beta 1 sample is still using the old API, but we’ve updated it in the beta2 release.

Why the change?

The debugging services in V1 didn’t have a good versioning plan. The original idea was that the debugger would just create a single instance of ICorDebug (via CoCreate) and that would emulate all other versions as needed.

This was a bad idea.

That means if you have an v1 debugger on a v1 debuggee, you’ll use the v1 implementation of ICorDebug. As soon as you install a v2 CLR, that scenario is automatically updated to use a V2 implementation of ICorDebug.

If that new implementation doesn’t perfectly emulate the old one, then the mere act of installing a new v2 runtime would have broken a pure v1 scenario.

The test matrix also explodes very quickly. We’d have to test every version against every previous version.

ICorDebug design flaws also prevent us from shimming implementations underneath the interface either. We don’t know the version of the debuggee until a CreateProcess callback is dispatched, but there’s still a lot of functionality before that callback (including interop-debugging support).

We concluded the only viable alternative was to keep 1 version of the ICorDebug implementation  per CLR. With the new APIs, installing a new CLR does not have any impact on the what happens to the debugging pipeline of existing apps. You’ll also notice now that the version of mscordbi.dll in the debugger will always strictly match the version of mscorwks.dll in the debuggee. So when a v2.0 debugger is debugging a v1.0 application, it loads the v1.0 mscordbi. (Unfortunately, this will be a problem for debuggers implemented in managed code. See here for details.).

This ugliness is an example of the consequence of not really thinking about versioning until v2.0.

Issues with the new design:

The biggest immediate problem with the new design is where do you get the debuggee’s version string from? The debugger needs to predict the debuggee’s version before it launches it. There are a few APIs in mscoree.idl to help with this:

1)      GetCORVersion   this will get the version string for the currently executing process. This works fine if the debugger + debuggee have the same version. (This is what beta 1 MDbg does.)

2)      GetRequestedRuntimeVersion   this predict the version string from an executable on disk based off policy settings, config files, etc. This will always be accurate for a pure-managed app like C#.

3)      GetVersionFromProcess   this will find the version string from a currently running process. This API was added in v2.0 to explicitly support this scenario.

There are of course cases where there’s no way to predict the version string. Consider a pure native app that pops up a dialog box asking the user which runtime to bind to and then calls CorBindToRuntimeEx on the fly.

All this said, we considered these limitations doable given the scenarios we wanted to support.