Функция CorBindToRuntimeExCorBindToRuntimeEx Function

Позволяет неуправляемым узлам загружать среду CLR в процесс.Enables unmanaged hosts to load the common language runtime (CLR) into a process. Функции CorBindToRuntime и CorBindToRuntimeEx выполняют одну и ту же операцию, но функция CorBindToRuntimeEx позволяет устанавливать флаги для указания поведения среды CLR.The CorBindToRuntime and CorBindToRuntimeEx functions perform the same operation, but the CorBindToRuntimeEx function allows you to set flags to specify the behavior of the CLR.

Эта функция является устаревшей в .NET Framework 4.This function has been deprecated in the .NET Framework 4.

Эта функция принимает набор параметров, позволяющих узлу выполнять следующие действия:This function takes a set of parameters that allow a host to do the following:

  • Укажите версию среды выполнения, которая будет загружена.Specify the version of the runtime that will be loaded.

  • Укажите, следует ли загружать сборку сервера или рабочей станции.Indicate whether the server or workstation build should be loaded.

  • Управление тем, выполняется ли параллельная сборка мусора или не параллельная сборка мусора.Control whether concurrent garbage collection or non-concurrent garbage collection is done.

Примечание

Параллельная сборка мусора не поддерживается в приложениях, использующих Эмулятор WOW64 x86 в 64-разрядных системах, которые реализуют архитектуру Intel Itanium (прежнее название — IA-64).Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). Дополнительные сведения об использовании WOW64 в 64-разрядных системах Windows см. в разделе выполнение 32-разрядных приложений.For more information about using WOW64 on 64-bit Windows systems, see Running 32-bit Applications.

  • Определяет, загружаются ли сборки как нейтральные к домену.Control whether assemblies are loaded as domain-neutral.

  • Получите указатель интерфейса на ICorRuntimeHost , который можно использовать для установки дополнительных параметров для настройки экземпляра среды CLR перед его запуском.Obtain an interface pointer to an ICorRuntimeHost that can be used to set additional options for configuring an instance of the CLR before it is started.

СинтаксисSyntax

HRESULT CorBindToRuntimeEx (  
    [in]  LPCWSTR      pwszVersion,   
    [in]  LPCWSTR      pwszBuildFlavor,   
    [in]  DWORD        startupFlags,   
    [in]  REFCLSID     rclsid,   
    [in]  REFIID       riid,   
    [out] LPVOID FAR  *ppv  
);  

ПараметрыParameters

pwszVersion
окне Строка, описывающая версию среды CLR, которую требуется загрузить.[in] A string describing the version of the CLR you want to load.

Номер версии в .NET Framework состоит из четырех частей, разделенных точками: основной. дополнительный. сборка. Редакция.A version number in the .NET Framework consists of four parts separated by periods: major.minor.build.revision. Строка, передаваемая как pwszVersion, должна начинаться с символа "v", за которым следуют первые три части номера версии (например, "v 1.0.1529").The string passed as pwszVersion must start with the character "v" followed by the first three parts of the version number (for example, "v1.0.1529").

Некоторые версии среды CLR устанавливаются с инструкцией политики, которая определяет совместимость с предыдущими версиями среды CLR.Some versions of the CLR are installed with a policy statement that specifies compatibility with previous versions of the CLR. По умолчанию оболочка запуска проверяет pwszVersion в соответствии с инструкциями политики и загружает последнюю версию среды выполнения, совместимую с запрашиваемой версией.By default, the startup shim evaluates pwszVersion against policy statements and loads the latest version of the runtime that is compatible with the version being requested. Узел может заставить оболочку пропускать вычисление политики и загружать точную версию, указанную в pwszVersion, передав значение STARTUP_LOADER_SAFEMODE для параметра startupFlags, как описано ниже.A host can force the shim to skip policy evaluation and load the exact version specified in pwszVersion by passing a value of STARTUP_LOADER_SAFEMODE for the startupFlags parameter, as described below.

Если вызывающий объект указывает значение NULL для pwszVersion, CorBindToRuntimeEx определяет набор установленных сред выполнения, Номера версий которых ниже среды выполнения .NET Framework 4, и загружают последнюю версию среды выполнения из этого набора.If the caller specifies null for pwszVersion, CorBindToRuntimeEx identifies the set of installed runtimes whose version numbers are lower than the .NET Framework 4 runtime, and loads the latest version of the runtime from that set. Он не загружает .NET Framework 4 или более поздней версии и завершается ошибкой, если предыдущая версия не установлена.It won't load the .NET Framework 4 or later, and fails if no earlier version is installed. Обратите внимание, что передача значения NULL позволяет узлу не контролировать, какая версия среды выполнения загружена.Note that passing null gives the host no control over which version of the runtime is loaded. Хотя такой подход может быть приемлемым в некоторых сценариях, настоятельно рекомендуется, чтобы узел предоставил определенную версию для загрузки.Although this approach may be appropriate in some scenarios, it is strongly recommended that the host supply a specific version to load.

pwszBuildFlavor
окне Строка, указывающая, загружать ли сервер или рабочую станцию сборку среды CLR.[in] A string that specifies whether to load the server or the workstation build of the CLR. Допустимые значения: svr и wks.Valid values are svr and wks. Сборка сервера оптимизирована для использования нескольких процессоров для сборок мусора, а сборка рабочей станции оптимизирована для клиентских приложений, работающих на однопроцессорном компьютере.The server build is optimized to take advantage of multiple processors for garbage collections, and the workstation build is optimized for client applications running on a single-processor machine.

Если pwszBuildFlavor имеет значение null, загружается сборка рабочей станции.If pwszBuildFlavor is set to null, the workstation build is loaded. При запуске на однопроцессорном компьютере сборка рабочей станции всегда загружается, даже если pwszBuildFlavor имеет значение svr.When running on a single-processor machine, the workstation build is always loaded, even if pwszBuildFlavor is set to svr. Однако если pwszBuildFlavor имеет значение svr и задана параллельная сборка мусора (см. Описание параметра startupFlags), то загружается серверная сборка.However, if pwszBuildFlavor is set to svr and concurrent garbage collection is specified (see the description of the startupFlags parameter), the server build is loaded.

startupFlags
окне Сочетание значений перечисления STARTUP_FLAGS .[in] A combination of values of the STARTUP_FLAGS enumeration. Эти флаги контролируют параллельную сборку мусора, код, нейтральный к домену, и поведение параметра pwszVersion.These flags control concurrent garbage collection, domain-neutral code, and the behavior of the pwszVersion parameter. Значение по умолчанию — один домен, если флаг не установлен.The default is single domain if no flag is set. Допустимы следующие значения.The following values are valid:

  • STARTUP_CONCURRENT_GC

  • STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN

  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN

  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST

  • STARTUP_LOADER_SAFEMODE

  • STARTUP_LEGACY_IMPERSONATION

  • STARTUP_LOADER_SETPREFERENCE

  • STARTUP_SERVER_GC

  • STARTUP_HOARD_GC_VM

  • STARTUP_SINGLE_VERSION_HOSTING_INTERFACE

  • STARTUP_LEGACY_IMPERSONATION

  • STARTUP_DISABLE_COMMITTHREADSTACK

  • STARTUP_ALWAYSFLOW_IMPERSONATION

Описание этих флагов см. в описании перечисления STARTUP_FLAGS .For descriptions of these flags, see the STARTUP_FLAGS enumeration.

rclsid
окне CLSID компонентного класса, реализующего интерфейс ICorRuntimeHost или ICLRRuntimeHost .[in] The CLSID of the coclass that implements either the ICorRuntimeHost or the ICLRRuntimeHost interface. Поддерживаемые значения: CLSID_CorRuntimeHost или CLSID_CLRRuntimeHost.Supported values are CLSID_CorRuntimeHost or CLSID_CLRRuntimeHost.

riid
окне IID запрашиваемого интерфейса из rclsid.[in] The IID of the requested interface from rclsid. Поддерживаемые значения: IID_ICorRuntimeHost или IID_ICLRRuntimeHost.Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

ppv
заполняет Возвращаемый указатель интерфейса на riid.[out] The returned interface pointer to riid.

ЗаметкиRemarks

Если pwszVersion указывает несуществующую версию среды выполнения, CorBindToRuntimeEx возвращает значение HRESULT CLR_E_SHIM_RUNTIMELOAD.If pwszVersion specifies a runtime version that does not exist, CorBindToRuntimeEx returns an HRESULT value of CLR_E_SHIM_RUNTIMELOAD.

Контекст выполнения и поток удостоверения WindowsExecution Context and Flow of Windows Identity

В версии 1 среды CLR объект WindowsIdentity не перетекает через асинхронные точки, такие как новые потоки, пулы потоков или обратные вызовы таймера.In version 1 of the CLR, the WindowsIdentity object does not flow across asynchronous points such as new threads, thread pools, or timer callbacks. В версии 2,0 среды CLR объект ExecutionContext заключает некоторые сведения о выполняемом в данный момент потоке и передает его через любую асинхронную точку, но не через границы домена приложения.In version 2.0 of the CLR, an ExecutionContext object wraps some information about the currently executing thread and flows it across any asynchronous point, but not across application domain boundaries. Аналогичным образом объект WindowsIdentity также проходит через любую асинхронную точку.Similarly, the WindowsIdentity object also flows across any asynchronous point. Таким образом, текущее олицетворение в потоке, если таковое имеется, также проходит.Therefore, the current impersonation on the thread, if any, flows too.

Изменить последовательность можно двумя способами:You can alter the flow in two ways:

  1. Изменяя параметры ExecutionContext для подавления потока на основе потока (см. методы SuppressFlow, SuppressFlowи SuppressFlowWindowsIdentity).By modifying the ExecutionContext settings to suppress the flow on a per-thread basis (see the SuppressFlow, SuppressFlow, and SuppressFlowWindowsIdentity methods).

  2. Изменив режим обработки по умолчанию на режим совместимости версии 1, где объект WindowsIdentity не пополняется по какой бы то ни было асинхронной точке, независимо от параметров ExecutionContext в текущем потоке.By changing the process default mode to the version 1 compatibility mode, where the WindowsIdentity object does not flow across any asynchronous point, regardless of the ExecutionContext settings on the current thread. Изменение режима по умолчанию зависит от того, используется ли управляемый исполняемый файл или неуправляемый интерфейс размещения для загрузки среды CLR:How you change the default mode depends on whether you use a managed executable or an unmanaged hosting interface to load the CLR:

    1. Для управляемых исполняемых файлов необходимо задать атрибут enabled элемента <легациимперсонатионполици > для true.For managed executables, you must set the enabled attribute of the <legacyImpersonationPolicy> element to true.

    2. Для неуправляемых интерфейсов размещения установите флаг STARTUP_LEGACY_IMPERSONATION в параметре startupFlags при вызове функции CorBindToRuntimeEx.For unmanaged hosting interfaces, set the STARTUP_LEGACY_IMPERSONATION flag in the startupFlags parameter when calling the CorBindToRuntimeEx function.

    Режим совместимости версии 1 применяется ко всему процессу и всем доменам приложения в процессе.The version 1 compatibility mode applies to the entire process and to all the application domains in the process.

ТребованияRequirements

Платформы: см. раздел Требования к системе.Platforms: See System Requirements.

Заголовок: MSCorEE. hHeader: MSCorEE.h

Библиотека: MSCorEE. dllLibrary: MSCorEE.dll

Версии платформы .NET Framework: Доступно с версии 1.0Available since 1.0.NET Framework Versions: Доступно с версии 1.0Available since 1.0

См. такжеSee also