Mengemas aplikasi Anda menggunakan MSIX proyek tunggal

  • Artikel

MSIX proyek tunggal adalah fitur yang memungkinkan Anda membuat aplikasi desktop WinUI 3 paket tanpa perlu proyek pengemasan terpisah. Aplikasi WinUI 3 adalah aplikasi yang menggunakan kerangka kerja Windows UI Library (WinUI) 3 untuk antarmuka pengguna (UI); dan menggunakan SDK Aplikasi Windows. Untuk mengemas aplikasi desktop yang bukan aplikasi WinUI 3, lihat Menyiapkan aplikasi desktop Anda untuk kemasan MSIX di Visual Studio.

Fitur MSIX proyek tunggal tersedia sebagai ekstensi Visual Studio yang dapat Anda gunakan untuk skenario ini:

  • Buat aplikasi desktop WinUI 3 baru menggunakan templat proyek Visual Studio Aplikasi Kosong, Dipaketkan (WinUI 3 di Desktop) yang dilengkapi dengan SDK Aplikasi Windows. Proyek tersebut dikonfigurasi untuk membangun aplikasi Anda ke dalam paket MSIX tanpa memerlukan proyek pengemasan terpisah.
  • Ubah aplikasi desktop WinUI 3 yang sudah ada yang menggunakan proyek pengemasan terpisah. Modifikasi melibatkan penghapusan proyek pengemasan terpisah, seperti yang ditunjukkan pada ilustrasi di bawah ini.

Comparing packaging project to single project

Gambaran Umum

Bagian ini memperkenalkan beberapa detail penting tentang fitur MSIX proyek tunggal.

Keuntungan

Sebelum pengenalan fitur MSIX proyek tunggal, jika Anda ingin membuat aplikasi desktop WinUI 3 yang dikemas, maka Anda memerlukan dua proyek dalam solusi Anda—proyek aplikasi Anda, ditambah Proyek Kemasan Aplikasi Windows tambahan (lihat Menyiapkan aplikasi desktop Anda untuk kemasan MSIX di Visual Studio). Fitur MSIX proyek tunggal memungkinkan Anda mengembangkan dan membangun aplikasi hanya menggunakan proyek untuk aplikasi Anda. Itu memberikan struktur proyek yang lebih bersih dan pengalaman pengembangan yang lebih mudah. Misalnya, Anda tidak perlu lagi memilih proyek pengemasan terpisah sebagai proyek startup Anda.

Jenis proyek yang didukung

Fitur MSIX proyek tunggal mendukung templat WinUI 3 di Visual Studio (C# dan C++) untuk SDK Aplikasi Windows.

Pembatasan

MSIX proyek tunggal hanya mendukung satu executable dalam paket MSIX yang dihasilkan. Jika Anda perlu menggabungkan beberapa executable ke dalam satu paket MSIX, maka Anda harus terus menggunakan Proyek Pengemasan Aplikasi Windows dalam solusi Anda.

Menginstal alat pengemasan MSIX proyek tunggal

Alat pengemasan MSIX proyek tunggal mencakup templat proyek Visual Studio yang dapat Anda gunakan untuk membuat aplikasi desktop WinUI 3 paket baru. Alat-alat tersebut disertakan dengan ekstensi SDK Aplikasi Windows untuk Visual Studio. Untuk petunjuk penginstalan SDK Aplikasi Windows, lihat Menginstal alat untuk SDK Aplikasi Windows.

SDK Aplikasi Windows versi 0.8 dan C# dari 1.0 Pratinjau 3: Alat pengemasan MSIX proyek tunggal tidak disertakan dengan ekstensi SDK Aplikasi Windows untuk Visual Studio untuk SDK Aplikasi Windows versi 0.8, atau untuk proyek C# hingga dan termasuk Pratinjau 3 dari SDK Aplikasi Windows 1.0. Jadi, jika Anda menggunakan versi tersebut, maka Anda mungkin perlu menginstal alat pengemasan MSIX proyek tunggal secara eksplisit. Lihat info di bawah ini:

  • Visual Studio 2022 versi 17.1 dan yang lebih baru: Ekstensi MSIX Packaging Tools proyek tunggal untuk Visual Studio 2022 VSIX dibangun ke dalam Visual Studio 2022 versi 17.1 dan yang lebih baru.

  • Visual Studio 2022 sebelum versi 17.1: Instal ekstensi MSIX Packaging Tools proyek tunggal untuk Visual Studio 2022 VSIX.

  • Visual Studio 2019: Instal Alat Pengemasan MSIX proyek tunggal untuk ekstensi VSIX Visual Studio 2019. Ekstensi ini memerlukan Visual Studio 2019 versi 16.10.x atau yang lebih baru.

Anda kemudian dapat, di Visual Studio, mengonfirmasi bahwa Anda telah menginstal ekstensi. Klik Ekstensi>Kelola Ekstensi Terinstal>>Semua, dan konfirmasikan bahwa Alat Kemasan MSIX proyek tunggal tercantum.

Membuat proyek baru

Jika Anda menggunakan SDK Aplikasi Windows 1.0 Pratinjau 2 atau yang lebih baru, maka Anda dapat membuat aplikasi berbasis WinUI 3 baru yang menyertakan dukungan MSIX proyek tunggal hanya dengan menggunakan templat Aplikasi Kosong, Dikemas (WinUI 3 di Desktop). Untuk informasi selengkapnya, lihat Membuat proyek WinUI 3 pertama Anda.

Mengubah proyek yang sudah ada

Ikuti langkah-langkah di bagian ini untuk memodifikasi aplikasi berbasis WinUI 3 yang sudah ada yang menggunakan proyek pengemasan terpisah. Langkah-langkahnya termasuk memindahkan manifes paket (dan dukungan lain yang diperlukan untuk membangun paket MSIX) ke dalam proyek aplikasi, lalu menghapus proyek pengemasan terpisah.

Langkah 1: Membuat atau membuka proyek pengemasan yang ada

Jika Anda sudah memiliki solusi untuk aplikasi desktop WinUI 3 (lihat templat WinUI 3 di Visual Studio) yang menyertakan Proyek Pengemasan Aplikasi Windows (lihat Menyiapkan aplikasi desktop Anda untuk kemasan MSIX di Visual Studio), lalu buka solusi tersebut di Visual Studio sekarang.

Jika tidak, buat aplikasi desktop WinUI 3 baru di Visual Studio dengan menggunakan templat Aplikasi Kosong, Dikemas dengan Windows Application Packaging Project (WinUI 3 di Desktop). Solusi Anda akan terlihat mirip dengan cuplikan layar di bawah ini.

A solution using the packaging project

Langkah 2: Mengedit pengaturan proyek aplikasi

Selanjutnya, edit beberapa pengaturan konfigurasi untuk menggunakan fitur MSIX proyek tunggal. Ada petunjuk yang berbeda tergantung pada jenis proyek dan versi Visual Studio Anda.

  1. Di Penjelajah Solusi, klik dua kali simpul proyek untuk aplikasi Anda untuk membuka file .csproj di editor XML. Tambahkan XML berikut ke elemen PropertyGroup> utama<.

    <EnableMsixTooling>true</EnableMsixTooling>
<PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>

    Setelah selesai, <elemen PropertyGroup> akan terlihat mirip dengan ini.

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>

  2. Simpan perubahan Anda, dan tutup file .csproj .

  3. Lakukan salah satu prosedur berikut, tergantung pada versi Visual Studio Anda.

    Untuk Visual Studio 2022 atau yang lebih baru:

    1. Di Penjelajah Solusi, klik kanan folder Properti di bawah simpul proyek untuk aplikasi Anda, dan pilih Tambahkan>Item Baru....

    2. Pilih File Teks, beri nama peluncuran file baru Pengaturan.json, dan klik Tambahkan. Pastikan file baru berada di folder Properti proyek aplikasi Anda.

    3. Salin pengaturan berikut ke dalam file baru. Anda bebas mengubah nilai sesuai kebutuhan untuk skenario Anda. Nilai MyApp dapat berupa string apa pun; tidak perlu mencocokkan nama aplikasi Anda.

      {
    "profiles": {
        "MyApp": {
            "commandName": "MsixPackage",
            "commandLineArgs": "", /* Command line arguments to pass to the app. */
            "alwaysReinstallApp": false, /* Uninstall and then reinstall the app. All information about the app state is deleted. */
            "remoteDebugEnabled": false, /* Indicates that the debugger should attach to a process on a remote machine. */
            "allowLocalNetworkLoopbackProperty": true, /* Allow the app to make network calls to the device it is installed on. */
            "authenticationMode": "Windows", /* The authentication scheme to use when connecting to the remote machine. */
            "doNotLaunchApp": false, /* Do not launch the app, but debug my code when it starts. */
            "remoteDebugMachine": "", /* The name of the remote machine. */
            "nativeDebugging": false /* Enable debugging for managed and native code together, also known as mixed-mode debugging. */
        }
    }
}

    4. Simpan dan tutup file launch Pengaturan.json.

    Untuk Visual Studio 2019:

    1. Di Penjelajah Solusi, klik kanan simpul proyek untuk aplikasi Anda, dan pilih Properti.

    2. Pilih tab Debug dan atur properti Luncurkan ke MsixPackage. Anda mungkin harus memilih ini dua kali jika kembali pada upaya pertama.

      Enabling MsixProject option

    3. Simpan perubahan.

Langkah 3: Memindahkan file ke proyek aplikasi

Selanjutnya, pindahkan beberapa file penting ke proyek aplikasi. Ada instruksi yang berbeda tergantung pada jenis proyek Anda.

  1. Di File Explorer, pindahkan file Package.appxmanifest dan folder Gambar dari proyek kemasan Anda ke proyek aplikasi Anda. Tempatkan file dan folder ini di tingkat atas hierarki folder proyek aplikasi.
  2. Di Visual Studio, di Penjelajah Solusi, pilih beberapa gambar di dalam folder Gambar. Di jendela Properti , atur Tindakan Build ke Konten.
  3. Hapus proyek pengemasan dari solusi Anda.

Illustration of moving files to main app

Langkah 4: Mengaktifkan penyebaran di Configuration Manager

  1. Pilih Build>Configuration Manager.
  2. Di Configuration Manager, klik kotak centang Sebarkan untuk setiap kombinasi konfigurasi dan platform (misalnya, Debug dan x86, Debug dan arm64, Rilis dan x64, dan banyak lagi).

    Catatan

    Pastikan untuk menggunakan konfigurasi solusi Aktif dan drop-down platform solusi Aktif di bagian atas alih-alih menu drop-down Konfigurasi dan Platform di baris yang sama dengan kotak centang Sebarkan.

Enabling Deploy in Configuration Manager

Langkah 5: Sebarkan aplikasi Anda

Bangun dan sebarkan proyek aplikasi Anda. Visual Studio akan membangun aplikasi Anda ke dalam paket MSIX, menginstal paket, lalu menjalankan aplikasi Anda.

Langkah 6: Mengemas aplikasi Anda untuk penerbitan

Gunakan perintah Paket & Terbitkan di Visual Studio untuk mengemas aplikasi Anda untuk menerbitkannya ke Microsoft Store.

Mengotomatiskan pembuatan dan pengemasan aplikasi MSIX proyek tunggal Anda

Anda dapat menggunakan msbuild untuk membangun dan mengemas aplikasi MSIX proyek tunggal Anda, sehingga memungkinkan Anda mengotomatiskan alur kerja. Teknik untuk solusi proyek tunggal, dan baris perintah, hanya sedikit berbeda dari apa yang mungkin sudah Anda lakukan jika Anda memiliki solusi dua proyek—yang memiliki Proyek Pengemasan Aplikasi Windows (lihat Menyiapkan aplikasi desktop Anda untuk kemasan MSIX di Visual Studio).

Opsi perintah build penting untuk solusi proyek tunggal adalah /p:GenerateAppxPackageOnBuild=true. Tanpa opsi itu, proyek akan dibangun, tetapi Anda tidak akan mendapatkan paket MSIX. Sertakan opsi tersebut, dan itu akan menyebabkan paket MSIX dihasilkan.

Ada contoh lengkap dalam bentuk GitHub Action yang membangun solusi proyek tunggal WinUI 3.

Catatan

MSIX proyek tunggal saat ini tidak mendukung produksi bundel MSIX (lihat Paket MSIX bundling). Ini hanya menghasilkan satu MSIX. Tetapi Anda dapat memaketkan .msix file ke dalam bundel MSIX dengan menggunakan MSIX Bundler GitHub Action.

Cara aplikasi desktop kemasan berjalan di Windows

Untuk penyelaman yang lebih mendalam tentang apa yang terjadi pada file dan entri registri saat Anda membuat paket aplikasi Windows untuk aplikasi desktop Anda, lihat Memahami bagaimana aplikasi desktop kemasan berjalan di Windows.

Memberikan tanggapan

Untuk mengirimi kami umpan balik Anda, melaporkan masalah, atau mengajukan pertanyaan tentang fitur MSIX proyek tunggal, posting diskusi atau masalah di repositori GitHub SDK Aplikasi Windows.