Mengemas program CLI yang dapat dieksekusi sebagai MSIX

Panduan ini memandu Anda mengemas executable baris perintah yang ada sebagai paket MSIX untuk distribusi melalui Windows Package Manager (winget), Microsoft Store, atau distribusi langsung.

Prasyarat

  • Anda ingin mengemas executable CLI yang sudah ada (.exe)
  • Windows 10 versi 1809 atau yang lebih baru

Steps

1. Atur Aplikasi CLI Anda

Tempatkan di folder khusus file eksekusi CLI dan segala dependensinya. Folder ini akan berisi semua file yang harus disertakan dalam paket MSIX Anda.

mkdir MyCliPackage
cd MyCliPackage
# Copy your CLI executable and dependencies here

2. Instal winapp CLI

Instal CLI winapp melalui Windows Package Manager, atau perbarui ke versi terbaru jika Anda sudah memilikinya:

# Install (or update if already installed)
winget install microsoft.winappcli --source winget

3. Hasilkan Package.appxmanifest

Hasilkan Package.appxmanifest dasar dan aset yang diperlukan untuk CLI Anda yang dapat dieksekusi:

winapp manifest generate --executable .\yourcli.exe

Perintah ini membuat Package.appxmanifest file di direktori saat ini dengan nilai default yang diisi dari executable Anda.

4. Konfigurasi Manifes

Sunting hasil Package.appxmanifest untuk menyesuaikan paket Anda. Setiap sub-langkah di bawah ini menjelaskan apa yang harus diubah dan mengapa.

4.1 Tambahkan Namespace yang Diperlukan

uap5 Tambahkan namespace ke Package elemen jika belum ada. Ini diperlukan untuk alias eksekusi di langkah 4.3:

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  ...
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap uap5 rescap">

4.2 Mengonfigurasi Elemen Aplikasi

<uap:VisualElements> Di elemen , tambahkan AppListEntry="none" untuk menyembunyikan aplikasi dari menu Mulai. Alat CLI dipanggil dari terminal, sehingga tidak memerlukan entri menu Mulai:

<uap:VisualElements
    DisplayName="YourApp"
    Description="My Application"
    BackgroundColor="transparent"
    Square150x150Logo="Assets\Square150x150Logo.png"
    Square44x44Logo="Assets\Square44x44Logo.png"
    AppListEntry="none">
</uap:VisualElements>

4.3 Menambahkan Alias Eksekusi Ekstensi

Tambahkan alias eksekusi sehingga pengguna dapat menjalankan CLI Anda berdasarkan nama dari jendela terminal apa pun. Tambahkan ini dalam <Application> elemen (setelah <uap:VisualElements>):

<Extensions>
  <uap5:Extension Category="windows.appExecutionAlias">
    <uap5:AppExecutionAlias>
      <uap5:ExecutionAlias Alias="yourcli.exe" />
    </uap5:AppExecutionAlias>
  </uap5:Extension>
</Extensions>

Ganti yourcli.exe dengan nama perintah yang diinginkan untuk CLI Anda. Setelah pengguna menginstal MSIX, mereka akan dapat memanggil CLI Anda dengan perintah ini.

4.4 Memperbarui Metadata Aplikasi

Perbarui bidang berikut agar sesuai dengan aplikasi CLI Anda.

Penting

Nilai Publisher dalam manifes Anda harus cocok dengan penerbit di sertifikat penandatangan Anda. Jika Anda membuat sertifikat nanti (langkah 5), sertifikat akan menggunakan penerbit dari manifes Anda. Jika Anda mengubah penerbit setelah membuat sertifikat, Anda harus meregenerasi sertifikat agar sesuai.

  • Identity: Memperbarui Name, Publisher, dan Version

    <Identity
  Name="YourCompany.YourCLI"
  Publisher="CN=Your Company"
  Version="1.0.0.0" />

  • Properti: Memperbarui nama tampilan, nama tampilan penerbit, dan deskripsi

    <Properties>
  <DisplayName>Your CLI Tool</DisplayName>
  <PublisherDisplayName>Your Company</PublisherDisplayName>
  <Description>Description of your CLI tool</Description>
  <Logo>Assets\StoreLogo.png</Logo>
</Properties>

  • VisualElements: Memperbarui nama tampilan dan referensi aset

    <uap:VisualElements
  DisplayName="Your CLI Tool"
  Description="Description of your CLI tool"
  BackgroundColor="transparent"
  Square150x150Logo="Assets\Square150x150Logo.png"
  Square44x44Logo="Assets\Square44x44Logo.png">
  <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" />
  <uap:SplashScreen Image="Assets\SplashScreen.png" />
</uap:VisualElements>

Catatan: Anda juga harus menambahkan aset ikon yang sesuai ke dalam folder di direktori paket Anda. Meskipun aplikasi tidak akan muncul di Menu Start, ikon masih diperlukan untuk pengiriman ke Toko dan mungkin muncul dalam konteks lain.

5. (Opsional) Menghasilkan Sertifikat Pengembangan

Untuk pengujian dan distribusi lokal di luar Microsoft Store, Anda harus menandatangani paket MSIX Anda dengan sertifikat.

Buat sertifikat pengembangan. Simpan di luar folder CLI Anda untuk menghindari secara tidak sengaja menyertakannya dalam paket:

# Navigate to a location outside your CLI folder (e.g., your home directory)
cd ~
winapp cert generate

Ini membuat devcert.pfx file di direktori beranda Anda (misalnya, C:\Users\yourname\devcert.pfx).

Untuk mempercayai sertifikat ini pada komputer pengembangan Anda, instal (memerlukan hak istimewa administrator):

# Run PowerShell as Administrator
winapp cert install ~\devcert.pfx

6. Paketkan CLI Anda

Sekarang Anda siap untuk membuat paket MSIX:

# Navigate back outside of your project folder
# Package with dev certificate (for local testing/distribution)
winapp pack .\path\to\MyCliPackage --cert .\path\to\devcert.pfx

Ini membuat .msix file di direktori saat ini.

7. Instal dan Verifikasi

Instal paket MSIX untuk memverifikasi semuanya berfungsi:

Add-AppxPackage .\MyCliPackage.msix

Jika Anda menambahkan alias eksekusi di langkah 4.3, Anda sekarang dapat menjalankan CLI dari terminal apa pun:

yourcli --help

Untuk menghapus instalasi di kemudian hari:

Get-AppxPackage *YourCLI* | Remove-AppxPackage

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

  • Distribute melalui winget: Kirimkan MSIX Anda ke Repositori Komunitas Windows Package Manager
  • Publish ke Microsoft Store: Gunakan winapp store untuk mengirimkan paket Anda
  • Siapkan CI/CD: Gunakan Tindakan setup-WinAppCli GitHub untuk mengotomatiskan kemasan di alur Anda
  • Last updated on