Properti-properti proyek dan penginisialisasi otomatis

Topik ini menjelaskan properti project yang dapat Anda atur dalam file Visual Studio project Anda (seperti .csproj atau .vcxproj) untuk menyesuaikan cara aplikasi Anda disebarkan, termasuk mengonfigurasi penginisialisasi otomatis.

Penginisialisasi otomatis di SDK Aplikasi Windows

Dalam SDK Aplikasi Windows, ada beberapa rutinitas yang tugasnya adalah memastikan bahwa runtime Windows App diinisialisasi dengan benar. Rutinitas ini dikenal sebagai penginisialisasi otomatis, karena berjalan secara otomatis sebelum titik masuk aplikasi Anda, dan melakukan pekerjaan inisialisasi untuk Anda.

Tip

Jika Anda ingin tahu tentang detail teknis. Di C++, penginisialisasi otomatis diimplementasikan dengan konstruktor kelas statis. Di C#, penginisialisasi otomatis diimplementasikan dengan penginisialisasi modul .NET. Jadi Anda mungkin terkadang mendengar penginisialisasi modul yang digunakan saat istilah yang tepat adalah penginisialisasi otomatis.

Semua penginisialisasi otomatis diaktifkan secara kondisional secara default, berdasarkan konfigurasi pengemasan dan penyebaran aplikasi Anda. Berikut adalah detailnya:

  • Bootstrapper adalah penginisialisasi otomatis (juga dikenal sebagai dependensi dinamis). Penginisialisasi otomatis ini memanggil API bootstrapper secara otomatis saat memulai aplikasi. Ini diperlukan untuk aplikasi yang bergantung pada kerangka kerja dan tidak dikemas, untuk memastikan bahwa Windows App Runtime ditambahkan ke graf paket aplikasi. Untuk informasi tentang aplikasi yang bergantung pada kerangka kerja (dan mandiri), lihat gambaran umum penyebaran SDK Aplikasi Windows. Untuk informasi tentang aplikasi yang tidak dikemas (dan dikemas), lihat Aplikasi Windows: pengemasan, penyebaran, dan proses.
    • Untuk aplikasi yang dikemas, Anda tidak memerlukan penginisialisasi otomatis dependensi bootstrapper/dinamis karena berkas appxmanifest.xml tersebut menyatakan dependensi kerangka kerja. Dan untuk aplikasi mandiri, Anda tidak memerlukan penginisialisasi otomatis bootstrapper/dependensi dinamis karena aplikasi tersebut tidak menggunakan kerangka kerja.
    • Anda dapat memilih keluar dari penginisialisasi otomatis dependensi bootstrapper/dinamis di .csproj atau .vcxproj file menggunakan <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>.
  • Penginisialisasi otomatis untuk Deployment Manager. Ini diperlukan untuk aplikasi paket yang bergantung pada kerangka kerja yang menggunakan fungsionalitas utama atau singleton (misalnya, pemberitahuan push), karena appxmanifest.xml berkas tidak dapat mengekspresikan dependensi tersebut.
    • Untuk aplikasi mandiri, Anda tidak memerlukan penginisialisasi otomatis Deployment Manager karena aplikasi tersebut tidak mendukung fungsionalitas utama/singleton.
    • Untuk informasi yang lebih penting, lihat bagian Penginisialisasi otomatis Deployment Manager nanti dalam topik ini.
  • Penginisialisasi otomatis aktivasi bebas pendaftaran. Ini diperlukan agar aplikasi mandiri dapat menggunakan aktivasi Windows Runtime (WinRT) tanpa pendaftaran berbasis manifes (UndockedRegFreeWinRT), jika aplikasi berjalan pada versi sistem operasi yang lebih lama dari Windows 10 Pembaruan Mei 2019 (versi 1903; dengan kode nama "19H1").
    • Untuk aplikasi yang bergantung pada kerangka kerja, dan untuk aplikasi mandiri yang menargetkan Windows 10, versi 1903, atau yang lebih baru, Anda tidak memerlukan inisialisasi otomatis aktivasi bebas pendaftaran. Aplikasi tersebut dapat memilih keluar melalui <WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize>.
  • Penginisialisasi otomatis kompatibilitas. Ini diperlukan agar aplikasi menggunakan fasilitas penahanan A/B untuk mengontrol perilaku rilis layanan. Untuk informasi selengkapnya, lihat RuntimeCompatibilityOptions.
    • Untuk aplikasi yang tidak menggunakan penahanan A/B (yang merupakan default), Anda tidak memerlukan penginisialisasi otomatis kompatibilitas.

Penginisialisasi otomatis Deployment Manager

Saat aplikasi yang menggunakan SDK Aplikasi Windows 1.8 atau yang lebih baru dimulai, penginisialisasi otomatis Deployment Manager akan berjalan secara default. Tetapi Anda dapat memilih keluar dari yang terjadi. Bagian ini menjelaskan manfaat dan peringatan yang memungkinkan penginisialisasi otomatis Deployment Manager berjalan, dan membantu Anda memutuskan apakah akan memilih keluar atau tidak.

Agar aplikasi Anda menggunakan fungsionalitas dalam paket Main/Singleton (misalnya, pemberitahuan push): 1. Anda harus menggunakan API Penyebaran untuk memastikan bahwa paket tersebut disebarkan (karena paket Main/Singleton bukan kerangka kerja, tetapi paket "utama", seperti aplikasi; sehingga paket tersebut tidak dapat didaftarkan sebagai dependensi dalam manifes appx aplikasi Anda. Sebagai gantinya, API Penyebaran menyediakan fungsionalitas untuk menyebarkan paket tersebut). 2. Karena 1), aplikasi Anda perlu menginisialisasi Deployment Manager dengan menyebabkan DeploymentManager.Initialize dipanggil. Aplikasi Anda dapat melakukannya secara otomatis, atau eksplisit, seperti yang akan kita lihat. 3. Aplikasi Anda harus menjadi aplikasi paket yang bergantung pada kerangka kerja sehingga membutuhkan dependensi pada paket Main/Singleton.

Salah satu cara menginisialisasi Manajer Penyebaran adalah dengan memungkinkan penginisialisasi otomatis Deployment Manager berjalan (lihat bagian Auto-initializer di SDK Aplikasi Windows sebelumnya dalam topik ini). Penginisialisasi otomatis dari Deployment Manager secara otomatis memanggil DeploymentManager.Initialize untuk Anda. Cara lain menginisialisasi Deployment Manager adalah dengan secara eksplisit memanggil DeploymentManager.Initialize sendiri.

Jika aplikasi Anda (menggunakan SDK Aplikasi Windows 1.8 atau yang lebih baru) tidak memerlukan paket Main/Singleton, maka Anda harus menolak penginisialisasi otomatis Deployment Manager dengan mengatur properti WindowsAppSdkDeploymentManagerInitialize ke false dalam file project aplikasi Anda.

Jika aplikasi Anda (menggunakan SDK Aplikasi Windows 1.8 atau yang lebih baru) does memerlukan paket Main/Singleton, maka Anda dapat:

  • Izinkan penginisialisasi otomatis Deployment Manager berjalan (yang dilakukannya secara default),
  • atau keluar dari penginisialisasi otomatis Deployment Manager dengan mengatur properti WindowsAppSdkDeploymentManagerInitialize ke false di file project aplikasi Anda. Anda kemudian harus secara eksplisit memanggil DeploymentManager.Initialize sendiri.

Penting

Untuk proses apa pun yang berjalan di AppContainer, jika Anda menyebabkan DeploymentManager.Initialize dipanggil, aplikasi Anda perlu mendeklarasikan packageManagementkemampuan terbatas dalam manifes paket Anda.

Properti Proyek

Dalam tabel di bawah ini adalah properti yang dapat Anda atur dalam file project aplikasi Anda. Lihat bagian sebelumnya (di atas) untuk detail tentang penginisialisasi otomatis di SDK Aplikasi Windows.

Nama dan deskripsi properti Nilai Untuk informasi selengkapnya
AppxPackage. Menentukan apakah aplikasi WinUI dipaketkan atau tidak. false (untuk aplikasi yang tidak dikemas), atau tidak ada (untuk aplikasi yang dikemas) Membuka kemasan aplikasi WinUI
EnableMsixTooling. Mengaktifkan fitur MSIX proyek tunggal untuk sebuah proyek. true (untuk mengaktifkan), atau tidak ada (untuk menonaktifkan) Gunakan MSIX proyek tunggal untuk memaketkan aplikasi Anda
UseCrtSDKReferenceStaticWarning. Menonaktifkan peringatan build yang muncul saat aplikasi C++ yang dipaketkan menautkan CRT secara statis (yang diperlukan untuk penerapan mandiri menggunakan CRT hibrida). Atur ke false dalam proyek aplikasi paket yang memilih CRT hibrid. false (untuk menekan peringatan di aplikasi mandiri yang dikemas), atau tidak ada (default, peringatan diaktifkan) panduan penyebaran SDK Aplikasi Windows untuk aplikasi mandiri
GunakanWinUI. Menentukan apakah Anda menggunakan kerangka kerja antarmuka pengguna WinUI di aplikasi Anda. benar, atau tidak ada (untuk false) WinUI dalam SDK Aplikasi Windows (WinUI)
WindowsAppSDKSingleFileVerifyConfiguration. Mengontrol apakah SDK menjalankan target validasi saat build ketika PublishSingleFile diatur. Ketika diaktifkan (default), target memancarkan kesalahan jika properti yang diperlukan hilang (EnableMsixTooling, , WindowsPackageType=NoneIncludeAllContentForSelfExtract) dan peringatan jika pengaturan mandiri tidak ada (WindowsAppSDKSelfContained, SelfContained). Atur ke false hanya untuk menonaktifkan semua pemeriksaan — misalnya, dalam pipeline CI jika Anda telah memverifikasi kepatuhan secara manual. true (nilai default — validasi dijalankan), false (nonaktifkan semua pemeriksaan) Ditentukan dalam Microsoft.WindowsAppSDK.SingleFile.targets (disertakan secara otomatis oleh paket NuGet saat PublishSingleFile diatur)
WindowsAppSdkBootstrapInitialize. Menentukan apakah SDK Aplikasi Windows menggunakan penginisialisasi otomatis untuk bootstrapper/dependensi dinamis atau tidak. true (default untuk berkas yang dapat dieksekusi), false (default untuk berkas yang tidak dapat dieksekusi) Memilih untuk tidak menggunakan (atau menggunakan) penginisialisasi otomatis
WindowsAppSdkDeploymentManagerInitialize. Menentukan apakah SDK Aplikasi Windows memanfaatkan penginisialisasi otomatis Deployment Manager atau tidak. true (default), false
WindowsAppSDKRuntimePatchLevel1, WindowsAppSDKRuntimePatchLevel2, dan WindowsAppSDKDisabledChanges. Menentukan apakah SDK Aplikasi Windows memanfaatkan penginisialisasi otomatis kompatibilitas, dan mengonfigurasi opsi kompatibilitas yang diinginkan untuk mengatur perilaku perubahan Windows App Runtime yang ditambahkan dalam pembaruan layanan. Berbagai, atau tidak ada (untuk menonaktifkan penginisialisasi otomatis) RuntimeCompatibilityOptions
WindowsAppSDKSelfContained. Menentukan apakah aplikasi disebarkan mandiri atau tidak. benar, atau tidak ada (untuk false) panduan penyebaran SDK Aplikasi Windows untuk aplikasi mandiri
WindowsAppSdkUndockedRegFreeWinRTInitialize. Menentukan apakah SDK Aplikasi Windows memanfaatkan penginisialisasi otomatis aktivasi bebas pendaftaran atau tidak. true (default untuk berkas yang dapat dieksekusi), false (default untuk berkas yang tidak dapat dieksekusi) Memilih keluar dari (atau ke) dukungan UndockedRegFreeWinRT otomatis
WindowsPackageType. Pengaturan <WindowsPackageType>None</WindowsPackageType> untuk aplikasi yang tidak dikemas menyebabkan penginisialisasi otomatis dependensi bootstrapper/dinamis menemukan dan memuat versi SDK Aplikasi Windows yang paling sesuai untuk aplikasi Anda. Tidak ada, atau tidak ada (untuk menonaktifkan penginisialisasi otomatis) Membuka kemasan aplikasi WinUI

Di balik layar, dan menolak penginisialisasi otomatis

Example

Berikut adalah kutipan dari file .csproj khas untuk project C# WinUI 3, memperlihatkan beberapa properti project dari tabel di atas yang digunakan.

...
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>
...
  • Last updated on