Menggunakan winapp CLI dengan Rust

Panduan ini menunjukkan cara menggunakan winapp CLI dengan aplikasi Rust untuk men-debug dengan identitas paket dan mengemas aplikasi Anda sebagai MSIX.

Untuk contoh kerja lengkap, lihat sampel Rust di repositori ini.

Identitas paket adalah konsep inti dalam model Windows app. Ini memungkinkan aplikasi Anda untuk mengakses API Windows tertentu (seperti Notifikasi, Keamanan, API AI, dll), memiliki pengalaman penginstalan/penghapusan instalasi yang bersih, dan banyak lagi.

Executable standar (seperti yang dibuat dengan cargo build) tidak memiliki identitas paket. Panduan ini menunjukkan cara menambahkannya untuk penelusuran kesalahan lalu mengemasnya untuk didistribusikan.

Prasyarat

  1. Rust Toolchain: Instal Rust menggunakan rustup atau winget (atau perbarui jika sudah diinstal):

    winget install Rustlang.Rustup --source winget

  2. winapp CLI: Instal winapp alat melalui winget (atau perbarui jika sudah diinstal):

    winget install microsoft.winappcli --source winget

1. Buat Aplikasi Rust Baru

Mulailah dengan membuat aplikasi Rust sederhana:

cargo new rust-app
cd rust-app

Jalankan untuk memastikan semuanya berfungsi:

cargo run

Seharusnya output adalah "Halo, dunia!"

2. Perbarui Kode untuk Memeriksa Identitas

Kami akan memperbarui aplikasi untuk memeriksa apakah aplikasi berjalan dengan identitas paket. Ini akan membantu kami memverifikasi bahwa identitas berfungsi dengan benar di langkah-langkah selanjutnya. Kita akan menggunakan peti windows untuk mengakses API Windows.

Pertama, tambahkan windows dependensi ke Cargo.toml Anda dengan menjalankan:

cargo add windows --features ApplicationModel

Ini menambahkan pengikatan API Windows dengan fitur ApplicationModel, yang memberi kami akses ke API Package untuk memeriksa identitas.

Selanjutnya, ganti seluruh konten src/main.rs dengan kode berikut. Kode ini mencoba mengakses identitas paket saat ini. Jika berhasil, nama keluarga paket akan dicetak; jika tidak, ia mencetak "Tidak dibungkus".

Note

Sampel lengkap juga menyertakan kode untuk menampilkan Pemberitahuan Windows jika identitas ada, tetapi dalam panduan ini, kami akan fokus pada pemeriksaan identitas.

use windows::ApplicationModel::Package;

fn main() {
    match Package::Current() {
        Ok(package) => {
            match package.Id() {
                Ok(id) => match id.FamilyName() {
                    Ok(name) => println!("Package Family Name: {}", name),
                    Err(e) => println!("Error getting family name: {}", e),
                },
                Err(e) => println!("Error getting package ID: {}", e),
            }
        }
        Err(_) => println!("Not packaged"),
    }
}

3. Jalankan Tanpa Identitas

Sekarang, bangun dan jalankan aplikasi seperti biasa:

cargo run

Anda akan melihat output "Tidak dibungkus". Ini mengonfirmasi bahwa executable standar berjalan tanpa identitas paket apa pun.

4. Inisialisasi Project dengan winapp CLI

Perintah winapp init menyiapkan semua yang Anda butuhkan dalam sekali jalan: manifes dan aset aplikasi. Manifes menentukan identitas aplikasi Anda (nama, penerbit, versi) yang Windows gunakan untuk memberikan akses API.

Jalankan perintah berikut dan ikuti perintah:

winapp init

Ketika diminta:

  • Nama paket: Tekan Enter untuk menerima default (rust-app)
  • Nama penerbit: Tekan Enter untuk menerima pengaturan standar atau masukkan nama Anda
  • Versi: Tekan Enter untuk menerima 1.0.0.0
  • Deskripsi: Tekan Enter untuk menerima default atau memasukkan deskripsi
  • Penyiapan SDK: Pilih "Jangan siapkan SDK" (Rust menggunakan peti sendiri windows, bukan header SDK C++).

Perintah ini akan:

  • Buat Package.appxmanifest — manifes yang menentukan identitas aplikasi Anda
  • Buat Assets folder — ikon yang diperlukan untuk pengemasan MSIX dan pengiriman Store

Note

Karena tidak ada paket SDK yang dikelola, tidak ada winapp.yaml yang dibuat — Rust menggunakan crate melalui Cargo, jadi tidak ada yang bisa dilacak winapp restore/update.

Anda dapat membuka Package.appxmanifest untuk menyesuaikan properti lebih lanjut seperti nama tampilan, penerbit, dan kemampuan.

Menambahkan Alias Eksekusi (untuk aplikasi konsol)

Karena cargo new membuat aplikasi konsol, kita perlu menambahkan alias eksekusi ke manifes. Tanpa itu, winapp run akan meluncurkan aplikasi melalui aktivasi AUMID, yang membuka jendela baru—dan jendela itu akan segera ditutup ketika aplikasi konsol selesai, menghilangkan output apa pun.

Alias juga memungkinkan pengguna menjalankan aplikasi Anda berdasarkan nama dari terminal apa pun setelah mereka menginstal MSIX. Manifes mendaftarkan alias seperti rust-app.exe (default ke nama exe proyek Anda), yang dapat dipanggil pengguna sebagai rust-app atau rust-app.exe.

Lewati langkah ini jika Anda membuat aplikasi UI (aplikasi Rust yang merender jendelanya sendiri). Aplikasi tersebut berfungsi dengan baik dengan peluncuran AUMID default.

Tambahkan alias:

winapp manifest add-alias

Ini menambahkan uap5:ExecutionAlias entri ke Package.appxmanifest.

5. Debugging dengan Identifikasi

Untuk menguji fitur yang memerlukan identitas (seperti Pemberitahuan) tanpa sepenuhnya mengemas aplikasi, gunakan winapp run. Ini mendaftarkan seluruh folder output build sebagai paket tata letak longgar — persis seperti penginstalan MSIX yang sesungguhnya — dan meluncurkan aplikasi. Tidak diperlukan sertifikat atau penandatanganan untuk debug.

  1. Buat executable:

    cargo build

  2. Jalankan dengan identitas:

    winapp run .\target\debug --with-alias

Bendera --with-alias meluncurkan aplikasi melalui alias eksekusinya sehingga output konsol tetap berada di terminal saat ini. Ini memerlukan uap5:ExecutionAlias yang kami tambahkan di langkah 4.

Note

winapp run juga mendaftarkan paket pada sistem Anda. Inilah sebabnya mengapa MSIX mungkin muncul sebagai "sudah diinstal" ketika Anda mencoba menginstalnya nanti di langkah 6. Gunakan winapp unregister untuk membersihkan paket pengembangan setelah selesai.

Anda sekarang akan melihat output yang mirip dengan:

Package Family Name: rust-app_12345abcde

Ini mengonfirmasi bahwa aplikasi Anda berjalan dengan identitas paket yang valid!

Tip

Untuk alur kerja penelusuran kesalahan tingkat lanjut (melampirkan debugger, penyiapan IDE, penelusuran kesalahan startup), lihat Panduan Penelusuran Kesalahan.

6. Paket dengan MSIX

Setelah siap mendistribusikan aplikasi, Anda dapat mengemasnya sebagai MSIX menggunakan manifes yang sama. MSIX menyediakan penginstalan/penghapusan instalasi yang bersih, pembaruan otomatis, dan pengalaman penginstalan tepercaya.

Menyiapkan Direktori Paket

Pertama, bangun aplikasi Anda dalam mode rilis untuk performa optimal:

cargo build --release

Kemudian, buat direktori hanya dengan file yang diperlukan untuk distribusi. Folder target\release berisi artefak build yang bukan bagian dari aplikasi Anda — kami hanya memerlukan yang dapat dieksekusi:

mkdir dist
copy .\target\release\rust-app.exe .\dist\

Membuat Sertifikat Pengembangan

Paket MSIX harus ditandatangani. Untuk pengujian lokal, buat sertifikat pengembangan yang ditandatangani sendiri:

winapp cert generate --if-exists skip

Penting

Publisher sertifikat harus cocok dengan Publisher di Package.appxmanifest Anda. Perintah cert generate akan membaca ini secara otomatis dari manifes Anda.

Tanda tangani dan Kemas

Sekarang Anda dapat mengemas dan menandatangani dalam satu langkah.

winapp pack .\dist --cert .\devcert.pfx

Catatan: pack Perintah secara otomatis menggunakan Package.appxmanifest dari direktori Anda saat ini dan menyalinnya ke folder target sebelum pengemasan. File .msix yang dihasilkan akan berada di direktori saat ini.

Menginstal Sertifikat

Sebelum Anda dapat menginstal paket MSIX, Anda perlu mempercayai sertifikat pengembangan pada komputer Anda. Jalankan perintah ini sebagai administrator (Anda hanya perlu melakukan ini sekali per sertifikat):

winapp cert install .\devcert.pfx

Instal dan Jalankan

Note

Jika Anda menggunakan winapp run di langkah 5, paket mungkin sudah terdaftar di sistem Anda. Gunakan winapp unregister terlebih dahulu untuk menghapus pendaftaran pengembangan, lalu instal paket rilis.

Instal paket dengan mengeklik dua kali file yang dihasilkan .msix , atau melalui PowerShell:

Add-AppxPackage .\rust-app.msix

Sekarang Anda dapat menjalankan aplikasi dari mana saja di terminal dengan mengetik:

rust-app

Anda seharusnya melihat output "Nama Keluarga Paket" yang mengonfirmasi bahwa itu diinstal dan berjalan dengan menggunakan identitas.

Tip

Jika Anda perlu mengemas ulang aplikasi Anda (misalnya, setelah perubahan kode), tambahkan Version di aplikasi Anda Package.appxmanifest sebelum berjalan winapp pack lagi. Windows memerlukan nomor versi yang lebih tinggi untuk memperbarui paket yang diinstal.

Tips

  1. Setelah siap didistribusikan, Anda dapat menandatangani MSIX dengan sertifikat penandatanganan kode dari Otoritas Sertifikat sehingga pengguna Anda tidak perlu menginstal sertifikat yang ditandatangani sendiri
  2. Microsoft Store akan menandatangani MSIX untuk Anda, tidak perlu menandatangani sebelum pengiriman.
  3. Anda mungkin perlu membuat beberapa paket MSIX, satu untuk setiap arsitektur yang Anda dukung (x64, Arm64)

Langkah Selanjutnya

  • Last updated on