Функция CorBindToRuntimeExCorBindToRuntimeEx Function

Позволяет неуправляемым основным приложениям загружать в процесс общеязыковой среды выполнения (CLR).Enables unmanaged hosts to load the common language runtime (CLR) into a process. CorBindToRuntime и CorBindToRuntimeEx функции выполняют та же операция, но CorBindToRuntimeEx функция позволяет задавать флаги для определения поведения этой СРЕДЫ.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
[in] Строка, описывающая версию среды CLR, вы хотите загрузить.[in] A string describing the version of the CLR you want to load.

Номер версии в .NET Framework состоит из четырех частей, разделенных точками: major.minor.build.revision.A version number in the .NET Framework consists of four parts separated by periods: major.minor.build.revision. Строка, передаваемая как pwszVersion должно начинаться с символа «v», следуют первые три части номера версии (например, «v1.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
[in] Строковое значение, указывающее, следует ли загружать на сервере или рабочей станции сборки среды 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
[in] Сочетание значений 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
[in] 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
[in] IID Запрошенного интерфейса из rclsid.[in] The IID of the requested interface from rclsid. Поддерживаемые значения: IID_ICorRuntimeHost и IID_ICLRRuntimeHost.Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

ppv
[out] Указатель на возвращенный интерфейс 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 атрибут <legacyImpersonationPolicy > элемент 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