Starting the CLR

At first glance, pBeginHostSetup and pEndHostSetup might seem unnecessary. After all, the shim can tell when the CLR has been initialized after the call to hostCallBack returns. The reason these additional parameters are needed is to notify the shim about which thread the initialization is happening on. The shim needs this information mostly for internal implementation reasons relating to the fact that only one thread in the process is allowed to initialize the CLR. The shim also uses the information to block other threads that might enter the process and wish to run managed code from proceeding until the initialization is done.

Listing 3-1 from the sample DeferredStartup.exe shows how to use LockClrVersion to delay the loading of the CLR. In this example, I force the CLR into the process by activating a managed type through the COM Interoperability layer as in the scenario described earlier. When the managed type is activated, the host-supplied function is called to initialize the CLR.

Listing 3-1. Using LockClrVersion to Load the CLR

#include "stdafx.h"
#include <mscoree.h>

// Declare globals to hold function pointers to call to notify the shim when the
// initialization of the CLR is beginning and ending.
FLockClrVersionCallback g_beginInit;
FLockClrVersionCallback g_endInit;

// This function is registered as the host callback provided to the CLR by LockClrVersion.
//
 The shim will call this function the first time it receives a request to run managed code.
STDAPI InitializeCLR()
{
   // Notify the CLR that initialization is beginning
   g_beginInit();

   // Initialize the CLR.
   ICLRRuntimeHost *pCLR = NULL;
    HRESULT hr = CorBindToRuntimeEx(
      L"v2.0.41013",
      NULL,
      NULL,
      CLSID_CLRRuntimeHost,
      IID_ICLRRuntimeHost,
      (PVOID*) &pCLR);

   assert(SUCCEEDED(hr));

   // Start the CLR.
   pCLR->Start(NULL, NULL);

   // Notify the CLR that initialization has completed.
   g_endInit();

   return S_OK;

}

int main(int argc, char* argv[])
{
   HRESULT hr = S_OK;

   // Call LockClrVersion so the InitializeCLR always get called to set up the runtime.
   LockClrVersion(InitializeCLR, &g_beginInit, &g_endInit);

   // Initialize COM and create an instance of a managed type through COM Interop. This
   // will require the CLR to be loadedInitializeCLR will be called.
   CoInitialize(NULL);

   CLSID clsid;
   hr = CLSIDFromProgID(L"System.Collections.SortedList", &clsid);
   assert(SUCCEEDED(hr));

   IUnknown *pUnk = NULL;
   hr = CoCreateInstance(clsid, NULL, CLSCTX_INPROC_SERVER, IID_IUnknown, (LPVOID *) &pUnk);
   assert(SUCCEEDED(hr));

   pUnk->Release();

   CoUninitialize();

   return 0;

}

LockClrVersion can be used for another, less obvious purposeto prevent the CLR from ever being loaded in a process. The scenarios in which you'd want to do this are clearly limited, but if you had a requirement to prevent managed code from running in your process completely, LockClrVersion is the way to do it. As you've seen, LockClrVersion takes a callback function that gets invoked when the CLR needs to be initialized. If you return a failure HRESULT from this callback, the CLR would not be loaded. In this way, you can prevent the CLR from ever entering your process.

Note

There's another technique you can use to accomplish a subset of what LockClrVersion provides. Recall that CorBindToRuntimeEx has a startupFlags parameter. One of the flags you can pass is called STARTUP_LOADER_SETPREFERENCE . When you pass this flag to CorBindToRuntimeEx , the startup shim does not initialize the CLR, but rather just remembers the version number you've passed through the pwszVersion parameter. Later, when the CLR needs to be initializedeither implicitly (as happens when a managed type is created from COM) or explicitly by another call to CorBindToRuntimeEx that does not set STARTUP_LOADER_SETPREFERENCE the shim loads the version of the CLR that it remembered earlier. In this way, you can use CorBindToRuntimeEx to indicate which version of the CLR to load in a delayed fashion. Using STARTUP_LOADER_SETPREFERENCE with CorBindToRuntimeEx is more limited than LockClrVersion in three key ways: You can specify only a version number STARTUP_LOADER_SETPREFERENCE remembers only the version number you passed to CorBindToRuntimeEx . It does not remember your preference for build type, your garbage collection settings, or your domain-neutral code settings. When the CLR is started later, defaults are used for these other settings. You cannot provide a callback to do extra processing As you've seen, LockClrVersion takes a callback that is invoked when the CLR needs to be initialized. In addition to calling CorBindToRuntimeEx , hosts often use this callback to create their host control object and report it to the CLR so the appropriate hosting managers are set up properly. If you don't use LockClrVersion , there's no way to accomplish this, or other related startup tasks , in a delayed fashion. You cannot prevent the CLR from entering the process You can use LockClrVersion to prevent the CLR from ever entering a process by returning a failure HRESULT from your callback. You can't do this using STARTUP_LOADER_SETPREFERENCE and CorBindToRuntimeEx . Even with these limitations, passing STARTUP_LOADER_SETPREFERENCE to CorBindToRuntimeEx can still be useful. If all you need to do is ensure a specific version of the CLR is loaded in a lazy fashion, you can do this with much less code than it takes to use LockClrVersion properly.