Loading the Runtime into a Process

Before any managed code can be executed, the host must load and initialize the common language runtime. All hosts start with an unmanaged stub because the runtime is not yet running in the process. The .NET Framework provides a set of unmanaged APIs called the Hosting APIs that the host can use to start the runtime. For more information, see the Common Language Runtime Hosting Interfaces specification in the Tool Developers Guide of the .NET Framework SDK.

To load the runtime into a process, a host calls CorBindToRuntimeEx, found in the Common Language Runtime Hosting Interfaces specification in the .NET Framework SDK. The prototype for CorBindToRuntimeEx is located in Mscoree.h in the Include directory of the .NET Framework SDK. When calling CorBindToRuntimeEx, a host can set values that control which version of the runtime to load and the behavior of basic functions such as garbage collection and assembly loading. A host can set the values listed in the following table.

Value	Description
Concurrent garbage collection	Specifies whether garbage collection is done on background threads or on the threads that run user code. For more information, see the Common Language Runtime Hosting Interfaces specification in the Tool Developers Guide of the .NET Framework SDK.
Loader optimization	Controls whether assemblies are loaded in a domain-neutral manner. Loading assemblies in a domain-neutral manner enables the assembly code and the read-only runtime data structures to be shared among all application domains within a process. For more information, see Application Domains and Assemblies.
Server vs. workstation	Specifies whether to load the workstation build or the server build. For more information, see the Common Language Runtime Hosting Interfaces specification in the Tool Developers Guide of the .NET Framework SDK.
Version	Specifies which version of the runtime to load into the process. For more information, see Side-by-side Execution

In addition to setting the values described in the table when calling CorBindToRuntimeEx, a host can request an interface pointer to ICorRuntimeHost, which enables the host to accomplish tasks such as setting configuration options and transitioning to managed hosting code to create application domains and execute user code.

A host can use ICorRuntimeHost to configure various aspects of the runtime, such as garbage collection, to load into the process or register for additional events. For example, a host can use GetConfiguration to register a callback function that receives notification when a particular thread is about to be stopped in the debugger, or to specify the size of the garbage collection heap.

ICorRuntimeHost also provides Start and Stop methods to enable the host to explicitly control the lifetime of the runtime within the process. Start is implicitly called when the first managed code is run in the process and Stop is implicitly called when the process shuts down. Although the host is not required to call these methods explicitly and usually does not, it might be useful to do so in some scenarios. For example, the host might call these methods explicitly when it has finished running managed code and wants to unload the runtime from the process to save memory and other resources. For more information about calling Stop, see Unloading Domains and Shutting Down a Process.

See Also

Hosting the Common Language Runtime | AppDomainSetup Class | Transitioning to Managed Hosting Code