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. Setelah mengkloning, jalankan winapp restore atau dotnet restore.

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.

Keluaran konsol (tidak ada yang perlu dilakukan)

Karena kami membangun aplikasi konsol, output konsol harus tetap berada di terminal saat ini. Aktivasi AUMID membuat aplikasi yang dipaketkan tidak memiliki konsol, sehingga aplikasi konsol akan berjalan dengan benar dan tidak mencetak apa pun.

winapp menanganinya untuk Anda: aplikasi dengan OutputType=Exe akan dijalankan melalui alias eksekusi, yang mewarisi stdin/stdout/stderr dari terminal Anda. Ini menambahkan uap5:ExecutionAlias yang diperlukan ke manifes yang disiapkannya, jadi tidak ada yang perlu dikonfigurasi.

aplikasi UI (WPF, WinForms, WinUI) merender jendelanya sendiri, sehingga tetap mempertahankan aktivasi AUMID.

Untuk memaksa AUMID untuk aplikasi konsol, tetapkan yang berikut ini di dalam dotnet-app.csproj mana pun di <PropertyGroup> — aplikasi kemudian berjalan tanpa konsol dan tidak menampilkan apa pun di terminal:

<WinAppRunUseExecutionAlias>false</WinAppRunUseExecutionAlias>

Jika Anda lebih suka memilih nama perintah sendiri, jalankan winapp manifest add-alias untuk mendeklarasikannya di Package.appxmanifest; alias yang Anda tulis digunakan as-is.

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.

Argumen yang Anda tulis setelah dotnet run masuk ke aplikasi Anda, persis seperti yang mereka lakukan jika proyek tidak mereferensikan paket ini:

dotnet run --devtools          # your app receives --devtools
dotnet run -- --devtools       # identical: the SDK consumes the -- before forwarding

Gunakan -- saat flag aplikasi Anda juga merupakan opsi dotnet run (--configuration, --project, --framework, -c, -f, -r, ...) — tanpanya, SDK akan mengambil token tersebut dan aplikasi Anda tidak akan pernah menerimanya:

dotnet run -- --configuration Release   # your app receives --configuration Release

Konfigurasikan peluncur WinApp itu sendiri dengan WinAppRun* properti MSBuild. MSBuild menggunakan ini, sehingga mereka tidak pernah mencapai aplikasi Anda:

dotnet run -p:WinAppRunDebugOutput=true --devtools

Di sini, properti digunakan untuk mengonfigurasi WinApp, sementara --devtools diteruskan ke aplikasi Anda. Lihat dotnet run dukungan untuk daftar properti lengkap, termasuk properti mana yang tidak dapat digabungkan.

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. winapp run dapat langsung menerima proyek (mode proyek) — winapp run membangun .csproj dan menjalankannya, sehingga Anda tidak perlu mengarahkan ke folder keluaran build atau melakukan build secara terpisah:

# Build and run the project in one step (project mode)
winapp run .

# ...or run a specific project / configuration / architecture
winapp run .\dotnet-app.csproj -c Debug --arch x64

Untuk menjalankan konfigurasi AOT Asli proyek, aktifkan AOT dalam proyek dan jalankan :

winapp run . --aot
winapp run . --aot -c Release

Gunakan x64 atau ARM64. Untuk penimpaan satu kali, tambahkan -p PublishAot=true.

Anda masih dapat mengarahkan winapp run ke folder output bawaan jika Anda mau (mode folder):

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

Mode Project mendukung aplikasi WinUI yang dikemas dan tidak dikemas — mode ini mendeteksi jenisnya dari WindowsPackageType proyek dan menginstal Windows App Runtime dengan arsitektur yang sesuai secara otomatis. Untuk memaksa menjalankan proyek yang dipaketkan tanpa pemaketan, tambahkan -p WindowsPackageType=None.

Aplikasi multiproyeksi (aplikasi yang mereferensikan pustaka kelas) dibuat dengan benar: winapp menyimpan AnyCPU/netstandard2.0 referensi pada platform yang kompatibel alih-alih memaksa arsitektur aplikasi di seluruh grafik. RID-only tetap menjadi default; ketika konfigurasi efektif memerlukan profil mandiri (misalnya, build Rilis yang dipangkas), winapp memilih profil yang cocok tanpa mengubah platform pustaka yang direferensikan.

Output dotnet build dialirkan secara langsung, dengan perintah yang tepat dicetak terlebih dahulu. Tambahkan --verbose untuk jejak keputusan build milik winapp. Memerlukan .NET SDK 8.0.100 atau yang lebih baru. Lihat winapp run di referensi penggunaan untuk daftar opsi lengkap.

Tidak ada Windows SDK yang terinstal? Proyek penulisan C#/WinRT biasanya memerlukan SDK Windows terdaftar untuk dibangun. Ketika mode proyek tidak mendeteksi apa pun (CI yang bersih, kontainer, mesin pengembangan tanpa SDK), cswinrt diarahkan ke winmds dari paket Microsoft.Windows.SDK.NET.Ref yang dipulihkan secara otomatis sehingga proses build tetap berhasil — tidak perlu tindakan apa pun. Ini tidak akan berpengaruh apa pun saat SDK terinstal atau saat Anda mengatur -p CsWinRTWindowsMetadata=… secara manual.

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.

Tip: Anda juga dapat melewati langkah menemukan folder output build dan langsung mengemas dari proyek — winapp package .\dotnet-app.csproj --cert .\devcert.pfx memublikasikan proyek dan mengemas outputnya dalam satu langkah (mode proyek secara default menggunakan konfigurasi Release). Mode proyek menerima opsi build -c, --arch, -f, --no-build, --no-restore, -p; tambahkan --no-build untuk mengemas build yang sudah ada tanpa membangun ulang.

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?

Terakhir diperbarui pada 2026-10-03

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

Keluaran konsol (tidak ada yang perlu dilakukan)

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`