Bagikan melalui

Fungsi CorBindToRuntimeEx

  • Artikel

Memungkinkan host yang tidak terkelola untuk memuat runtime bahasa umum (CLR) ke dalam suatu proses. Fungsi CorBindToRuntime dan CorBindToRuntimeEx melakukan operasi yang sama, tetapi fungsi CorBindToRuntimeEx memungkinkan Anda mengatur bendera untuk menetapkan perilaku CLR.

Fungsi ini sudah tidak digunakan lagi di .NET Framework 4.

Fungsi ini membutuhkan satu set parameter yang memungkinkan host untuk melakukan hal berikut:

  • Menentukan versi runtime yang akan dimuat.

  • Menunjukkan apakah build server atau stasiun kerja harus dimuat.

  • Kontrol apakah pengumpulan sampah serentak atau pengumpulan sampah yang tidak serentak dilakukan.

Catatan

Pengumpulan sampah serentak tidak didukung dalam aplikasi yang menjalankan emulator WOW64 x86 pada sistem 64-bit yang menerapkan arsitektur Intel Itanium (sebelumnya disebut IA-64). Untuk informasi selengkapnya tentang menggunakan WOW64 pada sistem Windows 64-bit, lihat Menjalankan Aplikasi 32-bit.

  • Kontrol apakah rakitan dimuat sebagai netral domain.

  • Dapatkan penunjuk antarmuka ke ICorRuntimeHost yang dapat digunakan untuk mengatur opsi tambahan untuk mengonfigurasi instans CLR sebelum dimulai.

Sintaks

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

Parameter

pwszVersion
[in] String yang menjelaskan versi CLR yang ingin Anda muat.

Nomor versi dalam .NET Framework terdiri dari empat bagian yang dipisahkan oleh titik: major.minor.build.revision. String yang diteruskan sebagai pwszVersion harus diawali dengan karakter "v" diikuti oleh tiga bagian pertama dari nomor versi (misalnya, "v1.0.1529").

Beberapa versi CLR diinstal dengan pernyataan kebijakan yang menentukan kompatibilitas dengan versi CLR sebelumnya. Secara default, shim startup mengevaluasi pwszVersion terhadap pernyataan kebijakan dan memuat versi terbaru runtime yang kompatibel dengan versi yang diminta. Host dapat memaksa shim untuk melewati evaluasi kebijakan dan memuat versi yang tepat yang ditentukan dalam pwszVersion dengan meneruskan nilai STARTUP_LOADER_SAFEMODE untuk parameter startupFlags, seperti yang dijelaskan di bawah ini.

Jika pemanggil menentukan null untuk pwszVersion, CorBindToRuntimeEx mengidentifikasi kumpulan runtime yang diinstal yang nomor versinya lebih rendah dari runtime .NET Framework 4, dan memuat versi terbaru runtime dari kumpulan tersebut. Ini tidak akan memuat .NET Framework 4 atau yang lebih baru, dan gagal jika tidak ada versi sebelumnya yang diinstal. Harap diingat bahwa melewati null tidak memberi host kontrol atas versi runtime mana yang dimuat. Meskipun pendekatan ini mungkin sesuai dalam beberapa skenario, sangat disarankan agar host menyediakan versi tertentu yang akan dimuat.

pwszBuildFlavor
[in] String yang menentukan apakah akan memuat build server atau stasiun kerja CLR. Nilai yang berlaku adalah svr atau wks. Build server dioptimalkan untuk memanfaatkan beberapa prosesor untuk pengumpulan sampah, dan build stasiun kerja dioptimalkan untuk aplikasi klien yang berjalan di komputer prosesor tunggal.

Jika pwszBuildFlavor diatur ke null, build stasiun kerja dimuat. Saat berjalan di komputer prosesor tunggal, build stasiun kerja selalu dimuat, meskipun pwszBuildFlavor diatur ke svr. Namun, jika pwszBuildFlavor diatur ke svr dan pengumpulan sampah serentak ditentukan (lihat deskripsi parameter startupFlags), build server dimuat.

startupFlags
[in] Kombinasi nilai enumerasi STARTUP_FLAGS. Bendera ini mengontrol pengumpulan sampah serentak, kode netral domain, dan perilaku parameter pwszVersion. Defaultnya adalah domain tunggal jika tidak ada bendera yang diatur. Nilai berikut valid:

  • STARTUP_CONCURRENT_GC

  • STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN

  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN

  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST

  • STARTUP_LOADER_SAFEMODE

  • STARTUP_LOADER_SETPREFERENCE

  • STARTUP_SERVER_GC

  • STARTUP_HOARD_GC_VM

  • STARTUP_SINGLE_VERSION_HOSTING_INTERFACE

  • STARTUP_LEGACY_IMPERSONATION

  • STARTUP_DISABLE_COMMITTHREADSTACK

  • STARTUP_ALWAYSFLOW_IMPERSONATION

Untuk deskripsi bendera ini, lihat enumerasi STARTUP_FLAGS.

rclsid
[in] CLSID dari coclass yang menerapkan antarmuka ICorRuntimeHost atau ICLRRuntimeHost. Nilai yang didukung adalah CLSID_CorRuntimeHost atau CLSID_CLRRuntimeHost.

riid
[in] IID antarmuka yang diminta dari rclsid. Nilai yang didukung adalah IID_ICorRuntimeHost atau IID_ICLRRuntimeHost.

ppv
[out] Penunjuk antarmuka yang ditampilkan ke riid.

Keterangan

Jika pwszVersion menentukan versi runtime yang tidak ada, CorBindToRuntimeEx menampilkan nilai HRESULT CLR_E_SHIM_RUNTIMELOAD.

Konteks Eksekusi dan Alur Identitas Windows

Di versi 1 CLR, objek WindowsIdentity tidak mengalir di seluruh titik asinkron seperti rangkaian baru, kumpulan rangkaian, atau panggilan balik timer. Dalam CLR versi 2.0, objek ExecutionContext membungkus beberapa informasi tentang rangkaian yang saat ini dijalankan dan mengalirkannya di seluruh titik asinkron, tetapi tidak di seluruh batas domain aplikasi. Demikian pula, objek WindowsIdentity juga mengalir di setiap titik asinkron. Oleh karena itu, peniruan saat ini pada rangkaian, jika ada, mengalir juga.

Anda dapat mengubah aliran dengan dua cara:

  1. Dengan mengubah pengaturan ExecutionContext untuk menyembunyikan alur berdasarkan per rangkaian (lihat metode SuppressFlow, SuppressFlow, dan SuppressFlowWindowsIdentity).

  2. Dengan mengubah mode default proses ke mode kompatibilitas versi 1, di mana objek WindowsIdentity tidak mengalir di titik asinkron apa pun, terlepas dari pengaturan ExecutionContext pada rangkaian saat ini. Bagaimana Anda mengubah mode default tergantung pada apakah Anda menggunakan antarmuka hosting yang dapat dieksekusi atau tidak terkelola untuk memuat CLR:

    1. Untuk executable terkelola, Anda harus mengatur atribut enabled elemen <legacyImpersonationPolicy> ke true.

    2. Untuk antarmuka hosting tidak terkelola, atur bendera STARTUP_LEGACY_IMPERSONATION dalam parameter startupFlags saat memanggil fungsi CorBindToRuntimeEx.

    Mode kompatibilitas versi 1 berlaku untuk seluruh proses dan semua domain aplikasi dalam prosesnya.

Persyaratan

Platform: Lihat Persyaratan Sistem.

Header: MSCorEE.h

Pustaka: MSCorEE.dll

Versi .NET Framework: Tersedia mulai dari 1.0

Lihat juga