Menggunakan winapp CLI dengan .NET

Panduan ini harus berfungsi untuk sebagian besar jenis proyek .NET. Langkah-langkah telah diuji dengan proyek berbasis konsol dan UI seperti WPF. Untuk contoh kerja, lihat sampel dotnet-app (konsol) dan wpf-app (WPF) di folder sampel.

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

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 dotnet build) tidak memiliki identitas paket. Panduan ini menunjukkan cara menambahkannya untuk penelusuran kesalahan lalu mengemasnya untuk didistribusikan.

Prasyarat

.NET SDK: Menginstal SDK .NET (memerlukan mulai ulang setelah penginstalan):
```
winget install Microsoft.DotNet.SDK.10 --source winget
```
winapp CLI: Instal winapp alat melalui winget (atau perbarui jika sudah diinstal):
```
winget install Microsoft.winappcli --source winget
```

1. Buat Aplikasi .NET Baru

Mulailah dengan membuat aplikasi konsol .NET sederhana:

dotnet new console -n dotnet-app
cd dotnet-app

Jalankan untuk memastikan semuanya berfungsi:

dotnet run

Output harus "Hello, World!"

2. Perbarui Kode untuk Memeriksa Identitas

Kami akan memperbarui aplikasi untuk memeriksa apakah aplikasi berjalan dengan identitas paket. Kami akan menggunakan API Windows Runtime untuk mengakses API Paket.

Pertama, perbarui file project Anda untuk menargetkan versi Windows SDK tertentu. Buka dotnet-app.csproj dan ubah TargetFramework untuk menyertakan versi SDK Windows:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Ini memberi Anda akses ke API Windows Runtime tanpa memerlukan paket tambahan.

Sekarang ganti konten Program.cs dengan kode berikut. Kode ini mencoba mengambil identitas paket saat ini menggunakan API Windows Runtime. Jika berhasil, nama keluarga paket akan dicetak; jika tidak, ia mencetak "Tidak dibungkus".

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Jalankan Tanpa Identitas

Sekarang, jalankan aplikasi seperti biasa:

dotnet 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 secara otomatis mendeteksi file .csproj dan menjalankan penyiapan yang spesifik untuk .NET. Ini mengatur semua yang Anda butuhkan dalam sekali klik: memvalidasiTargetFramework, menambahkan paket NuGet yang diperlukan, menghasilkan manifes aplikasi, dan aset-aset.

Jalankan perintah berikut dan ikuti perintah:

winapp init

Ketika diminta:

Nama paket: Tekan Enter untuk menerima default (dotnet-app)
Nama penerbit: Tekan Enter untuk menerima pengaturan standar atau masukkan nama Anda
Versi: Tekan Enter untuk menerima 1.0.0.0
Description: Tekan Enter untuk menerima default (aplikasi Windows) atau masukkan deskripsi
SDK Aplikasi Windows penyiapan: Pilih Stabil, Pratinjau, atau Eksperimental (menentukan versi SDK Aplikasi Windows mana yang ditambahkan)
TargetFramework update: Jika TargetFramework Anda tidak menyertakan versi SDK Windows yang didukung, Anda akan diminta untuk memperbaruinya (misalnya, ke net10.0-windows10.0.26100.0)
Mode Pengembang: Jika Anda diminta tentang "Mode Pengembang", Anda dapat mengaktifkannya jika Anda mau, tetapi ketahuilah bahwa ia memerlukan hak istimewa administratif

Perintah ini akan:

Perbarui TargetFramework di .csproj Anda ke format TFM Windows yang didukung (jika diperlukan)
Tambahkan Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools, dan referensi paket NuGet Microsoft.Windows.SDK.BuildTools.WinApp ke .csproj
Membuat Package.appxmanifest dan Assets folder untuk identitas aplikasi Anda

Nota

Tidak seperti proyek native/C++, aliran .NET tidak membuat winapp.yaml file. Paket NuGet dikelola langsung lewat .csproj Anda. Gunakan dotnet restore untuk memulihkan paket setelah kloning.

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

Untuk memverifikasi bahwa paket ditambahkan ke proyek Anda:

dotnet list package

Anda akan melihat Microsoft.WindowsAppSDK dan Microsoft.Windows.SDK.BuildTools dalam output.

Menambahkan Alias Eksekusi (untuk aplikasi konsol)

Karena kita sedang membangun aplikasi konsol, kita perlu memastikan dotnet run menjaga output konsol di terminal saat ini. Secara bawaan, dotnet run meluncurkan aplikasi yang dikemas melalui aktivasi AUMID, yang membuka jendela baru — dan jendela segera ditutup ketika aplikasi konsol selesai, mengabaikan semua keluaran.

Untuk memperbaikinya, Anda akan menambahkan alias eksekusi ke manifes dan memberi tahu integrasi eksekusi untuk diluncurkan melalui alias tersebut sebagai gantinya.

P langkah ini jika Anda membangun aplikasi UI (WPF, WinForms, WinUI). Aplikasi tersebut merender jendelanya sendiri, sehingga peluncuran AUMID default adalah yang Anda inginkan.

Tambahkan alias eksekusi ke manifes Anda:
```
winapp manifest add-alias
```
Ini menambahkan uap5:ExecutionAlias ke Package.appxmanifest (secara default menggunakan nama exe proyek Anda) sehingga aplikasi dapat diluncurkan dengan nama dari terminal.
Instruksikan dotnet run integrasi untuk menggunakan alias. Buka dotnet-app.csproj dan tambahkan yang berikut ini di dalam apa pun <PropertyGroup> (atau buat baru <PropertyGroup> jika diperlukan):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
Dengan properti ini diatur, dotnet run meluncurkan aplikasi melalui nama alias eksekusinya dan mewarisi stdin/stdout/stderr dari terminal saat ini sehingga Anda melihat output konsol secara sebaris.

5. Debugging dengan Identifikasi

Karena winapp init menambahkan paket NuGet Microsoft.Windows.SDK.BuildTools.WinApp ke proyek Anda, Anda cukup menjalankan:

dotnet run

Ini secara otomatis memanggil winapp run di balik layar - membuat paket tata letak fleksibel, mendaftarkannya ke Windows, dan meluncurkan aplikasi Anda dengan identitas paket lengkap.

Nota

Anda mungkin melihat peringatan kerentanan NuGet (NU1900) tentang sumber paket. Ini dapat diabaikan dengan aman — tidak memengaruhi build Anda.

Anda akan melihat output yang mirip dengan:

Package Family Name: dotnet-app_12345abcde

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

Alternatif: Manual `winapp run`

Jika Anda tidak menggunakan winapp init (atau menghapus paket NuGet), Anda dapat membuat dan menjalankan secara manual:

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Untuk menambahkan kembali paket NuGet: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Tip

Untuk menonaktifkan integrasi otomatisdotnet run, tambahkan <EnableWinAppRunSupport>false</EnableWinAppRunSupport> ke ..csproj Lihat dokumentasi dukungan dotnet run untuk opsi kustomisasi.

Alternatif: Identitas paket jarang

Jika Anda memerlukan perilaku paket sparse secara khusus (identitas tanpa menyalin file), Anda dapat menggunakan create-debug-identity untuk tujuan tersebut. Ini mendaftarkan sebuah paket "sparse" yang menunjuk ke exe Anda, alih-alih membuat struktur file yang lebih fleksibel.

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Kemudian jalankan executable secara langsung (jangan gunakan dotnet run karena mungkin membangun kembali/menimpa file):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternatif: Tujuan MSBuild Manual

Jika Anda lebih suka tidak menggunakan paket NuGet, Anda dapat menambahkan target MSBuild kustom yang berjalan create-debug-identity setelah build Debug. Tambahkan ini ke file .csproj Anda di akhir, tepat sebelum tag penutup </Project>.

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Dengan konfigurasi ini, dotnet build menerapkan identitas debug dan Anda dapat menjalankan executable secara langsung. Perhatikan bahwa dotnet run dapat membangun kembali dan menimpa identitas, jadi jalankan file .exe secara manual setelah proses build selesai.

Tip

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

Kapan harus melewati ini: Jika Anda lebih suka kontrol eksplisit ketika identitas diterapkan, atau jika Anda mengerjakan kode yang tidak memerlukan identitas untuk sebagian besar siklus pengembangan Anda, pendekatan manual di atas mungkin lebih sederhana.

6. Menggunakan SDK Aplikasi Windows (Opsional)

SDK Aplikasi Windows memberi Anda akses ke API Windows modern di luar apa yang disediakan Windows SDK dasar — hal-hal seperti sistem pemberitahuan, API windowing, manajemen siklus hidup aplikasi, dan AI di perangkat. Jika aplikasi Anda memerlukan salah satu kemampuan ini, langkah ini untuk Anda. Jika Anda hanya memerlukan identitas paket untuk distribusi, Anda dapat melompat ke langkah 7.

Jika Anda menjalankan winapp init (Langkah 4), Microsoft.WindowsAppSDK sudah ditambahkan sebagai referensi paket NuGet ke .csproj Anda. Anda dapat memverifikasi dengan dotnet list package. Jika Anda melewati penyiapan SDK selama init, atau perlu menambahkannya secara manual, jalankan:

dotnet add package Microsoft.WindowsAppSDK

Perbarui Program.cs

Ganti seluruh konten Program.cs dengan kode berikut, yang menambahkan pemeriksaan versi Windows App Runtime:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Kompilasi dan Jalankan

Bangun ulang dan jalankan aplikasi dengan SDK Aplikasi Windows. Karena kami telah menambahkan WinAppSDK, kita perlu mendaftar ulang dengan identitas sehingga winapp menambahkan dependensi runtime. Jika Anda menambahkan paket WinApp NuGet (disarankan), cukup jalankan dotnet run. Jika tidak (ganti dotnet-app dengan nama proyek Anda):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Anda sekarang akan melihat output seperti:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

Paket SDK Aplikasi Windows NuGet mencakup semua rakitan yang diperlukan untuk mengakses API Windows modern termasuk:

Pemberitahuan dan ubin aktif
Siklus hidup windowing dan aplikasi
Pemberitahuan push
Dan banyak lagi komponen SDK Aplikasi Windows

Untuk penggunaan SDK Aplikasi Windows yang lebih canggih, lihat dokumentasi SDK Aplikasi Windows.

7. Paket dengan MSIX

Setelah siap mendistribusikan aplikasi, Anda dapat mengemasnya sebagai MSIX menggunakan manifes yang sama.

Membuat untuk Rilis

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

dotnet build -c Release

Nota

Anda mungkin melihat peringatan kerentanan NuGet (NU1900). Ini aman untuk diabaikan dan tidak memengaruhi output build Anda.

Membuat Sertifikat Pengembangan

Sebelum pengemasan, Anda memerlukan sertifikat pengembangan untuk penandatanganan. Hasilkan satu jika Anda belum melakukannya.

winapp cert generate --if-exists skip

Tanda tangani dan Kemas

Sekarang Anda dapat mengemas dan menandatangani. Arahkan perintah paket ke folder output build Anda (ganti dotnet-app dan jalur TFM dengan nilai proyek Anda):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --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 dapat menginstal paket MSIX, Anda perlu menginstal sertifikat pengembangan. Jalankan perintah ini sebagai administrator:

winapp cert install .\devcert.pfx

Instal dan Jalankan

Instal paket dengan mengeklik dua kali file *.msix yang dihasilkan.

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

dotnet-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

Setelah siap untuk didistribusikan, Anda dapat menandatangani MSIX dengan sertifikat penandatanganan kode dari Otoritas Sertifikat sehingga pengguna Anda tidak perlu menginstal sertifikat yang ditandatangani sendiri.
Microsoft Store akan menandatangani MSIX untuk Anda, tidak perlu menandatangani sebelum pengiriman.
Anda mungkin perlu membuat beberapa paket MSIX, satu untuk setiap arsitektur yang Anda dukung (x64, Arm64). Gunakan -r parameter dengan dotnet build untuk menargetkan arsitektur tertentu: dotnet build -c Release -r win-x64 atau dotnet build -c Release -r win-arm64.

Mengotomatiskan Kemasan MSIX (Opsional)

Untuk mengotomatiskan kemasan MSIX sebagai bagian dari build Rilis Anda, tambahkan target ini ke file Anda .csproj (Anda dapat menambahkannya bersama target identitas debug):

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Dengan konfigurasi ini:

Membangun dalam mode Rilis (dotnet build -c Release) akan secara otomatis membuat paket MSIX
MSIX dikemas dan ditandatangani dengan sertifikat pengembangan milik Anda
File akhir .msix akan berada di akar proyek

Anda juga dapat membuat konfigurasi kustom (misalnya, PackagedRelease) dengan memodifikasi kondisi menjadi '$(Configuration)' == 'PackagedRelease'.

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
Explore Windows API: Dengan identitas paket, Anda sekarang dapat menggunakan Notifications, on-device AI, dan API identity-dependent lainnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-12

Menggunakan winapp CLI dengan .NET

Prasyarat

1. Buat Aplikasi .NET Baru

2. Perbarui Kode untuk Memeriksa Identitas

3. Jalankan Tanpa Identitas

4. Inisialisasi Project dengan winapp CLI

Menambahkan Alias Eksekusi (untuk aplikasi konsol)

5. Debugging dengan Identifikasi

Alternatif: Manual winapp run

Alternatif: Identitas paket jarang

Alternatif: Tujuan MSBuild Manual

6. Menggunakan SDK Aplikasi Windows (Opsional)

Perbarui Program.cs

Kompilasi dan Jalankan

7. Paket dengan MSIX

Membuat untuk Rilis

Membuat Sertifikat Pengembangan

Tanda tangani dan Kemas

Menginstal Sertifikat

Instal dan Jalankan

Tips

Mengotomatiskan Kemasan MSIX (Opsional)

Langkah Selanjutnya

Saran dan Komentar

Sumber Daya Tambahan:

Alternatif: Manual `winapp run`