Export (0) Print
Expand All

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.

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.

ICLRMetaHost::EnumerateLoadedRuntimes method

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.

ICLRRuntimeInfo::GetVersionString method

GetRequestedRuntimeInfo function

GetRequestedRuntimeVersion function

The function and method return the same value.

ICLRRuntimeInfo::GetRuntimeDirectory method

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.

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

CallFunctionShim

No

No

ClrCreateManagedInstance

No

No

CorBindToCurrentRuntime

Yes

ICLRRuntimeInfo::GetInterface

CorBindToRuntime

Yes

ICLRRuntimeInfo::GetInterface

CorBindToRuntimeByCfg

Yes

ICLRRuntimeInfo::GetInterface

ICLRMetaHostPolicy::GetRequestedRuntime

CorBindToRuntimeEx

Yes

ICLRRuntimeInfo::GetInterface, also

ICLRMetaHost::GetRuntime with STARTUP_LOADER_SAFEMODE

CorBindToRuntimeHost

Yes

ICLRRuntimeInfo::GetInterface

ICLRMetaHostPolicy::GetRequestedRuntime

CorExitProcess

No

No

CorLaunchApplication

No

No

CorMarkThreadInThreadPool

No

No

CreateDebuggingInterfaceFromVersion

Obsolete

ICLRRuntimeInfo::GetInterface

CreateICeeFileGen

No

No

DestroyICeeFileGen

No

No

FExecuteInAppDomainCallback

No

No

FLockClrVersionCallback

No

No

GetCLRIdentityManager

No

No

GetCORRequiredVersion

No

ICLRMetaHostPolicy::GetRequestedRuntime

GetCORSystemDirectory

Yes

ICLRRuntimeInfo::GetRuntimeDirectory

GetCORVersion

No

No

GetFileVersion

No

ICLRMetaHost::GetVersionFromFile

GetRealProcAddress

No

No

GetRequestedRuntimeInfo

Yes

ICLRRuntimeInfo::GetVersionString

ICLRMetaHostPolicy::GetRequestedRuntime

GetRequestedRuntimeVersion

No

ICLRRuntimeInfo::GetVersionString

ICLRMetaHostPolicy::GetRequestedRuntime

GetRequestedRuntimeVersionForCLSID

No

No

GetVersionFromProcess

No

No

LoadLibraryShim

Yes

ICLRRuntimeInfo::LoadLibrary

LoadStringRC

No

No

LoadStringRCEx

No

No

LockClrVersion

No

No

LPOVERLAPPED_COMPLETION_ROUTINE

No

No

LPTHREAD_START_ROUTINE

No

No

RunDll32ShimW

No

No

WAITORTIMERCALLBACK

No

No

ShutdownCOMInterop replaces COEEShutDownCOM function.

Show:
© 2015 Microsoft