Bagikan melalui

Gunakan runtime SDK Aplikasi Windows untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas

  • Artikel

Catatan

Jika aplikasi Anda diinstal dengan menggunakan teknologi MSIX, lihat panduan penyebaran SDK Aplikasi Windows untuk aplikasi paket yang bergantung pada kerangka kerja.

Jika aplikasi Anda tidak diinstal dengan menggunakan MSIX (artinya, aplikasi tersebut dikemas dengan lokasi eksternal atau tidak dikemas), maka Anda harus menginisialisasi SDK Aplikasi Windows untuk digunakan sebelum dapat memanggil fitur SDK Aplikasi Windows seperti WinUI 3, App Lifecycle, MRT Core, dan DWriteCore. Aplikasi Anda harus menginisialisasi runtime SDK Aplikasi Windows sebelum menggunakan fitur lain dari SDK Aplikasi Windows.

  • Dimulai pada SDK Aplikasi Windows 1.0, yang dapat dilakukan secara otomatis saat aplikasi Anda dimulai melalui inisialisasi otomatis (atur properti <WindowsPackageType>None</WindowsPackageType>proyek ). Untuk demonstrasi, lihat Membuat proyek WinUI 3 pertama Anda.
  • Tetapi jika Anda memiliki kebutuhan lanjutan (seperti menangani kesalahan dengan menampilkan UI atau pengelogan kustom Anda sendiri, atau jika Anda perlu memuat versi SDK Aplikasi Windows yang berbeda dari versi yang Anda buat), maka lanjutkan membaca topik ini. Dalam skenario tersebut, alih-alih inisialisasi otomatis, Anda dapat memanggil API bootstrapper secara eksplisit.

Salah satu dari dua teknik di atas memungkinkan aplikasi yang tidak menggunakan MSIX untuk mengambil dependensi dinamis pada SDK Aplikasi Windows pada waktu proses.

Untuk informasi latar belakang tentang dependensi dinamis, lihat paket kerangka kerja MSIX dan dependensi dinamis.

Di balik layar, dan memilih keluar dari inisialisasi modul otomatis

Kode yang dihasilkan oleh properti yang WindowsPackageType disebutkan di atas memanfaatkan inisialisasi modul untuk memanggil API bootstrapper. Bootstrapper melakukan pengangkatan berat untuk menemukan SDK Aplikasi Windows dan memungkinkan proses saat ini untuk menggunakannya. Kode yang dihasilkan menangani inisialisasi dan pematian. Anda dapat mengontrol perilaku inisialisasi dengan properti proyek berikut:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Gunakan opsi default.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • Gunakan tidak ada opsi.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Panggil DebugBreak() jika terjadi kesalahan hanya jika debugger dilampirkan ke proses.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Lakukan fail-fast jika terjadi kesalahan.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Minta pengguna untuk memperoleh runtime SDK Aplikasi Windows jika runtime yang cocok tidak dapat ditemukan.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Berhasil jika dipanggil dalam proses dengan identitas paket (jika tidak, kesalahan akan gagal dan kesalahan dikembalikan).

Jika Anda ingin aplikasi Anda memiliki kontrol eksplisit, maka Anda dapat langsung memanggil API boostrapper di awal startup aplikasi Anda. Dalam hal ini Anda tidak perlu WindowsPackageType dalam file proyek Anda.

Catatan

Selain inisialisasi otomatis dan API bootstrapper, SDK Aplikasi Windows juga menyediakan implementasi API dependensi dinamis. API ini memungkinkan aplikasi yang tidak dikemas untuk mengambil dependensi pada paket kerangka kerja apa pun (bukan hanya paket kerangka kerja SDK Aplikasi Windows), dan digunakan secara internal oleh API bootstrapper. Untuk informasi selengkapnya tentang API dependensi dinamis, lihat Menggunakan API dependensi dinamis untuk mereferensikan paket MSIX pada waktu proses.

Memilih keluar dari (atau ke) inisialisasi modul otomatis

Properti <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> proyek menonaktifkan inisialisasi modul otomatis yang dijelaskan di atas (API bootstrapper tidak dipanggil). Hal ini memungkinkan aplikasi Anda bertanggung jawab dan langsung memanggil API bootstrapper.

Pada versi 1.2 dari SDK Aplikasi Windows (dari saluran stabil), inisialisasi modul otomatis hanya berlaku untuk proyek yang menghasilkan yang dapat dieksekusi (yaitu, properti proyek OutputType diatur ke Exe atau WinExe). Ini untuk mencegah penambahan penginisialisasi otomatis ke DALAM DLL pustaka kelas dan non-executable lainnya secara default. Jika Anda memerlukan penginisialisasi otomatis dalam non-executable (misalnya, DLL pengujian yang dimuat oleh proses host yang dapat dieksekusi yang tidak menginisialisasi bootstrapper), maka Anda dapat secara eksplisit mengaktifkan penginisialisasi otomatis di proyek Anda dengan <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Menggunakan API bootstrapper

Penting

Fungsi MddBootstrapInitialize2 yang disebutkan di bawah ini tersedia mulai versi 1.1.

API bootstrapper terdiri dari tiga fungsi C/C++ yang dideklarasikan dalam file header mddbootstrap.h di SDK Aplikasi Windows: MddBootstrapInitialize, MddBootstrapInitialize2, dan MddBootstrapShutdown. Fungsi-fungsi tersebut disediakan oleh pustaka bootstrapper di SDK Aplikasi Windows. Pustaka tersebut adalah DLL kecil yang harus Anda distribusikan dengan aplikasi Anda; ini bukan bagian dari paket kerangka kerja itu sendiri.

MddBootstrapInitialize2

Fungsi ini menginisialisasi proses panggilan untuk menggunakan versi paket kerangka kerja SDK Aplikasi Windows yang paling sesuai dengan kriteria yang Anda berikan ke parameter fungsi. Biasanya, itu menghasilkan mereferensikan versi paket kerangka kerja yang cocok dengan paket nuGet SDK Aplikasi Windows yang diinstal. Jika beberapa paket memenuhi kriteria, maka kandidat terbaik dipilih. Fungsi ini harus menjadi salah satu panggilan pertama dalam startup aplikasi untuk memastikan komponen bootstrapper dapat menginisialisasi SDK Aplikasi Windows dengan benar dan menambahkan referensi run-time ke paket kerangka kerja.

API bootstrapper menggunakan DYNAMIC Dependencies API untuk menambahkan paket kerangka kerja runtime SDK Aplikasi Windows ke grafik paket proses saat ini dan mengaktifkan akses ke paket.

Fungsi ini juga menginisialisasi Dynamic Dependency Lifetime Manager (DDLM). Komponen tersebut menyediakan infrastruktur untuk mencegah OS melayani paket kerangka kerja SDK Aplikasi Windows saat digunakan oleh aplikasi yang tidak dipaketkan.

MddBootstrapShutdown

Fungsi ini menghapus perubahan pada proses saat ini yang dilakukan oleh panggilan ke MddBootstrapInitialize. Setelah fungsi ini dipanggil, aplikasi Anda tidak dapat lagi memanggil API SDK Aplikasi Windows, termasuk API dependensi dinamis.

Fungsi ini juga mematikan Dynamic Dependency Lifetime Manager (DDLM) sehingga Windows dapat melayani paket kerangka kerja seperlunya.

Pembungkus .NET untuk API bootstrapper

Meskipun Anda dapat memanggil API bootstrapper C/C++ langsung dari aplikasi .NET, yang mengharuskan penggunaan platform memanggil untuk memanggil fungsi. Dalam rilis SDK Aplikasi Windows 1.0 dan yang lebih baru, pembungkus .NET untuk API bootstrapper tersedia di perakitanMicrosoft.WindowsAppRuntime.Bootstrap.Net.dll. Rakitan itu menyediakan API yang lebih mudah dan lebih alami bagi pengembang .NET untuk mengakses fungsionalitas bootstrapper. Kelas Bootstrap menyediakan fungsi Inisialisasi, TryInitialize, dan Shutdown statis yang membungkus panggilan ke fungsi MddBootstrapInitialize dan MddBootstrapShutdown untuk skenario yang paling umum. Misalnya yang menunjukkan cara menggunakan pembungkus .NET untuk API bootstrapper, lihat instruksi C# di Tutorial: Menggunakan API bootstrapper dalam aplikasi yang dikemas dengan lokasi eksternal atau membongkar yang menggunakan SDK Aplikasi Windows.

Untuk informasi selengkapnya tentang pembungkus .NET untuk API bootstrapper, lihat sumber daya berikut:

Pembungkus C++ untuk API bootstrapper

Pembungkus C++ untuk API bootstrapper tersedia mulai dari SDK Aplikasi Windows 1.1.

Lihat API Bootstrapper C++.

Mendeklarasikan kompatibilitas OS dalam manifes aplikasi Anda

Untuk mendeklarasikan kompatibilitas sistem operasi (OS), dan untuk menghindari SDK Aplikasi Windows default ke perilaku Windows 8 (dan potensi crash), Anda dapat menyertakan manifes aplikasi berdampingan dengan paket Anda dengan lokasi eksternal atau aplikasi yang tidak dikemas. Lihat Manifes aplikasi (ini adalah file yang mendeklarasikan hal-hal seperti kesadaran DPI, dan disematkan ke dalam aplikasi .exe Anda selama build). Ini mungkin menjadi masalah jika Anda menambahkan dukungan SDK Aplikasi Windows ke aplikasi yang sudah ada, daripada membuat yang baru melalui templat proyek Visual Studio.

Jika Anda belum memiliki manifes aplikasi berdampingan dalam proyek Anda, tambahkan file XML baru ke proyek Anda, dan beri nama seperti yang direkomendasikan dalam Manifes aplikasi. Tambahkan ke file elemen kompatibilitas dan elemen turunan yang diperlihatkan dalam contoh berikut. Nilai-nilai ini mengontrol tingkat quirks untuk komponen yang berjalan dalam proses aplikasi Anda.

Ganti atribut Id dari elemen maxversiontested dengan nomor versi Windows yang Anda targetkan (harus 10.0.17763.0 atau rilis yang lebih baru). Perhatikan bahwa menetapkan nilai yang lebih tinggi berarti bahwa versi Windows yang lebih lama tidak akan menjalankan aplikasi Anda dengan benar karena setiap rilis Windows hanya tahu versi sebelum itu. Jadi, jika Anda ingin aplikasi Anda berjalan di Windows 10, versi 1809 (10.0; Build 17763), maka Anda harus membiarkan nilai 10.0.17763.0 apa adanya, atau menambahkan beberapa elemen maxversiontested untuk berbagai nilai yang didukung aplikasi Anda.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>

Lihat Juga