In-Process Side-by-Side Runtime Host Activation
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
In-process side-by-side runtime host activation describes the ability of an application to load and activate multiple versions of the common language runtime (CLR) in the same process. The application can be either native (unmanaged) or managed, and the activation can be done either through COM or by using unmanaged host interfaces. Each CLR instance can load and execute as many assemblies as needed.
This capability, which is introduced in the .NET Framework version 4 Beta 2, overcomes the following limitations of the .NET Framework version 2.0 hosting API:
When a newer version of the .NET Framework CLR loaded an assembly that was built against a previous version of the CLR, compatibility issues could occur, and the application could stop working. This could happen for any managed assembly, both in full applications and in plug-ins (where the managed assemblies run in the context of a host application). The only way to guarantee that a newer version of the .NET Framework did not affect existing applications was to have all existing managed applications run in their original target compiled .NET Framework version.
A host application could not run two instances of the CLR in the same process. This scenario limited backward compatibility for add-ins. For example, if a managed add-in that was compiled to run with CLR version 1.1 was deployed to a desktop that had both 1.1 and 2.0 versions of the .NET Framework installed, the most current runtime (version 2.0) would be loaded. However, that version of the runtime could be incompatible with the add-in.
The .NET Framework 4 Beta 2 hosting API provides the following advantages:
Clear separation between policy-free and policy-based functionalities.
Easy to extend with additional functionality by introducing new interfaces.
Functions perform clearly defined steps rather than poorly understood heavy-weight black boxes.
All .NET Framework 4 Beta 2 interfaces have these characteristics:
They use lifetime management (AddRef/Release), encapsulation (implicit context), and QueryInterface functionality from COM.
They do not use COM types (BSTR, SAFEARRAY, VARIANT), apartment models, aggregation, or registry activation (CoCreateInstance).
The .NET Framework 4 Beta 2 hosting API is defined in MetaHost.idl and is COM-like in its construction. It provides enumeration, information, and manipulation functionality through the ICLRMetaHost and ICLRRuntimeInfo interfaces.
Two other interfaces encapsulate strong name services and policy-based runtime binding exported through MSCorEE.dll: ICLRStrongName and ICLRMetaHostPolicy.
Appendix 1: Hosting API CompatibilityTable
The following table describes the interactions that may occur between the hosting interfaces in different versions of the .NET Framework. References to CorBindTo* functions include the following deprecated hosting global static functions:
NET Framework 4 hosting |
.NET Framework 2.0 hosting |
Interaction |
|---|---|---|
ICLRMetaHost::GetRuntime method |
|
ICLRMetaHost::GetRuntime supersedes the CorBindToRuntimeEx function used with STARTUP_LOADER_SAFEMODE. A host may call one of the CorBindTo* functions to instantiate a particular version of the common language runtime (CLR). If the host then calls ICLRMetaHost::GetRuntime, depending on the hosting policy in place, GetRuntime returns an ICLRRuntimeInfo pointer to either a new runtime instance, or to the runtime that is already loaded in memory. |
|
For compatibility with earlier versions of the hosting API, ICLRMetaHost::EnumerateLoadedRuntimes interacts with CorBindTo* functions and the two interfaces in the following way: Whenever a host application calls a hosting API from a previous version to load a runtime, ICLRMetaHost::EnumerateLoadedRuntimes is able to list that runtime. Also, GetVersionFromProcess Function lists all runtime versions loaded by ICLRMetaHost::GetRuntime, ICLRMetaHost::EnumerateInstalledRuntimes, ICLRMetaHost::EnumerateLoadedRuntimes, or ICLRRuntimeHost3::StartWithFlags Method. |
|
ICLRMetaHost::RequestRuntimeLoadedNotification Method Method |
LockClrVersion function |
The callback function that is set by ICLRMetaHost::SetRuntimeLoadedCallback is triggered by a call to any CorBindTo* function. LockClrVersion is triggered by calls to the .NET Framework 4 Beta 2 hosting API only when the runtime that is being loaded is also loadable by the earlier hosting API. |
GetRequestedRuntimeInfo function GetRequestedRuntimeVersion function |
The function and method return the same value. |
|
GetCORSystemDirectory function |
The function and method return the same value. |
|
ICLRRuntimeInfo::IsLoaded method |
|
ICLRRuntimeInfo::IsLoaded is consistent with the CorBindTo* functions, and the two interfaces. If a host calls the earlier hosting API to instantiate a runtime, a later call to ICLRRuntimeInfo::IsLoaded, relative to the instantiated runtime, returns true. Otherwise, it returns false. |
ICLRRuntimeInfo::LoadLibrary method |
LoadLibraryShim function |
The handles returned by LoadLibraryShim Function are fully compatible with the in-process side-by-side hosting interfaces. |
ICLRRuntimeHost3::IsStarted method |
ICorRuntimeHost::Start method ICorRuntimeHost::Stop method ICLRRuntimeHost::Start method ICLRRuntimeHost::Stop method |
ICLRRuntimeHost3::IsStarted returns valid status for runtime versions that are started and stopped by the earlier hosting API methods. |
Appendix 2: Deprecated Functions
All global static functions in the .NET Framework hosting API are deprecated. They are listed in the following table. References to these functions have been removed from MSCorEE.h, MSCorEE.lib, and MSCorEE.idl. Hosting application developers should use the new in-process side-by-side hosting API instead.
The behavior of some of the deprecated functions has changed slightly to minimize the impact of installing the common language runtime (CLR) version in the .NET Framework version 4 Beta 2 side by side with previous versions. In cases where the binding behavior has changed, refer to the default side-by-side hosting policy discussed in Hosting Policies.
.NET Framework 2.0 hosting global static function |
Behavior changes |
.NET Framework 4 replacement |
|---|---|---|
No |
No |
|
No |
No |
|
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
No |
No |
|
No |
No |
|
No |
No |
|
Obsolete |
||
No |
No |
|
No |
No |
|
No |
No |
|
No |
No |
|
No |
No |
|
No |
||
Yes |
||
No |
No |
|
No |
||
No |
No |
|
Yes |
||
No |
||
No |
No |
|
No |
No |
|
Yes |
||
No |
No |
|
No |
No |
|
No |
No |
|
No |
No |
|
No |
No |
|
No |
No |
|
No |
No |
ShutdownCOMInterop replaces COEEShutDownCOM function.