Buat proyek WinUI 3 (SDK Aplikasi Windows) pertama Anda

Artikel
01/25/2024

Dalam topik ini kita akan melihat cara menggunakan Visual Studio untuk membuat proyek SDK Aplikasi Windows baru untuk aplikasi C# .NET atau C++ yang memiliki antarmuka pengguna (UI) WinUI 3. Kita juga akan melihat beberapa kode dalam proyek yang dihasilkan, apa fungsinya, dan cara kerjanya.

Tautan ke detail penginstalan lengkap ada dalam langkah-langkah di bawah ini. Kami menyarankan agar Anda menginstal dan menargetkan rilis stabil terbaru dari SDK Aplikasi Windows (lihat Catatan rilis saluran stabil).

Tip

Apa pun versi SDK Aplikasi Windows yang Anda pilih untuk diinstal dan ditargetkan (atau versi Visual Studio apa yang Anda gunakan), penting untuk memeriksa batasan dan masalah yang diketahui dalam catatan rilis untuk versi tersebut (lihat SDK Aplikasi Windows saluran rilis). Dengan mengetahui tentang batasan dan masalah yang diketahui untuk versi SDK Aplikasi Windows Anda, Anda akan dapat mengatasinya jika Anda mengalami salah satu dari mereka saat mengikuti langkah-langkah dalam topik ini.

Jika Anda mengalami masalah lain, maka Anda kemungkinan akan menemukan info tentang masalah tersebut di masalah GitHub, atau pada tab Diskusi, dari repositori GitHub WindowsAppSDK ; atau melalui pencarian online.

Penting

Jika Anda sedang mengerjakan aplikasi UWP, lihat Migrasi dari UWP ke SDK Aplikasi Windows.

Dikemas, tidak dikemas, dan dikemas dengan lokasi eksternal

Pengemasan adalah pertimbangan penting dari proyek SDK Aplikasi Windows apa pun. Untuk informasi selengkapnya tentang opsi pengemasan Anda, lihat Keuntungan dan kekurangan kemasan aplikasi Anda.

Dipaketkan: Buat proyek baru untuk aplikasi desktop C# atau C++ WinUI 3 yang dipaketkan

Untuk menyiapkan komputer pengembangan Anda, lihat Menginstal alat untuk SDK Aplikasi Windows.
Di Visual Studio, pilih File>Baru>Proyek.
Di filter drop-down dialog Proyek Baru, pilih C#/C++, Windows, dan winui.
Pilih templat proyek Aplikasi Kosong, Dipaketkan (WinUI 3 di Desktop), dan klik Berikutnya. Templat tersebut membuat aplikasi desktop dengan antarmuka pengguna berbasis WinUI 3. Proyek yang dihasilkan dikonfigurasi dengan manifes paket dan dukungan lain yang diperlukan untuk membangun aplikasi ke dalam paket MSIX (lihat Apa itu MSIX?). Untuk informasi selengkapnya tentang templat proyek ini, lihat Mengemas aplikasi Anda menggunakan MSIX proyek tunggal.
Masukkan nama proyek, pilih opsi lain seperti yang diinginkan, dan klik Buat.
Proyek yang dihasilkan Visual Studio berisi kode aplikasi Anda. File App.xaml dan file code-behind menentukan kelas turunan Aplikasi yang mewakili aplikasi anda yang sedang berjalan. File MainWindow.xaml dan file code-behind menentukan kelas MainWindow yang mewakili jendela utama yang ditampilkan oleh aplikasi Anda. Kelas-kelas tersebut berasal dari jenis di namespace Microsoft.UI.Xaml yang disediakan oleh WinUI 3.

Proyek ini juga menyertakan manifes paket untuk membangun aplikasi ke dalam paket MSIX.
Untuk menambahkan item baru ke aplikasi Anda, klik kanan simpul proyek di Penjelajah Solusi, dan pilih Tambahkan>Item Baru. Dalam kotak dialog Tambahkan Item Baru, pilih tab WinUI , pilih item yang ingin Anda tambahkan, lalu klik Tambahkan. Untuk detail selengkapnya tentang item yang tersedia, lihat Templat WinUI 3 di Visual Studio.
Buat dan jalankan solusi Anda di komputer pengembangan Anda untuk mengonfirmasi bahwa aplikasi berjalan tanpa kesalahan.

Unpackaged: Membuat proyek baru untuk aplikasi desktop C# atau C++ WinUI 3 yang tidak dikemas

Penting

Mulai dari SDK Aplikasi Windows 1.0, pendekatan default untuk memuat SDK Aplikasi Windows dari yang dikemas dengan lokasi eksternal atau aplikasi yang tidak dikemas adalah menggunakan inisialisasi otomatis melalui <WindowsPackageType> properti proyek (serta membuat perubahan konfigurasi tambahan). Untuk langkah-langkah yang terlibat dalam inisialisasi otomatis dalam konteks proyek WinUI 3, lanjutkan membaca bagian ini. Atau, jika Anda memiliki proyek yang sudah ada yang bukan WinUI 3, lihat Menggunakan SDK Aplikasi Windows dalam proyek yang ada.

Untuk menyiapkan komputer pengembangan Anda, lihat Menginstal alat untuk SDK Aplikasi Windows.
Unduh dan jalankan penginstal terbaru untuk SDK Aplikasi Windows dari Unduhan untuk SDK Aplikasi Windows. Itu akan menginstal dependensi paket runtime yang diperlukan untuk menjalankan dan menyebarkan yang dikemas dengan lokasi eksternal atau aplikasi yang tidak dikemas pada perangkat target (lihat panduan penyebaran SDK Aplikasi Windows untuk aplikasi yang bergantung pada kerangka kerja yang dikemas dengan lokasi eksternal atau tidak dikemas).
C++. Instal Microsoft Visual C++ Redistributable (VCRedist) yang sesuai untuk arsitektur perangkat target.
- Versi terbaru VCRedist kompatibel dengan rilis Visual Studio terbaru yang tersedia secara umum (GA) (yaitu, bukan pratinjau), serta semua versi Visual Studio yang dapat digunakan untuk membangun biner SDK Aplikasi Windows.
- Build Insider Visual Studio mungkin telah menginstal versi VCRedist yang lebih baru, dan menjalankan versi publik kemudian akan gagal dengan kesalahan ini (yang dapat Anda abaikan): Kesalahan 0x80070666: Tidak dapat menginstal produk saat versi yang lebih baru diinstal.
Catatan

Jika Anda tidak menginstal VCRedist pada perangkat target, tautan dinamis akan c:\windows\system32\vcruntime140.dll gagal. Kegagalan tersebut dapat bermanifestasi ke pengguna akhir dengan berbagai cara.
Di Visual Studio, pilih File>Baru>Proyek.
Di filter drop-down dialog Proyek Baru, pilih C#/C++, Windows, dan WinUI.
Anda perlu memulai dengan proyek yang dikemas untuk menggunakan diagnostik XAML. Jadi pilih templat proyek Aplikasi Kosong, Paket (WinUI 3 di Desktop), dan klik Berikutnya.

Penting

Pastikan bahwa proyek yang baru saja Anda buat menargetkan versi SDK Aplikasi Windows yang Anda instal dengan alat penginstal di langkah 2. Untuk melakukannya, di Visual Studio, klik Alat>Pengelola>Paket NuGet Kelola Paket NuGet untuk Solusi...>Pembaruan. Dan jika perlu perbarui referensi ke paket NuGet Microsoft.WindowsAppSDK . Anda dapat melihat versi mana yang diinstal pada tab Terinstal .
Tambahkan properti berikut ke file proyek Anda—baik file (C#) atau .vcxproj (C++) Anda .csproj . Masukkan ke dalam elemen PropertyGroup yang sudah ada (untuk C++, elemen akan memiliki Label="Globals"):
```
<Project ...>
  ...
  <PropertyGroup>
    ...
    <WindowsPackageType>None</WindowsPackageType>
    ...
  </PropertyGroup> 
  ...
</Project>
```

C++. Dalam file proyek C++ Anda (.vcxproj), di dalam elemen PropertyGroup yang sudah ada, atur properti AppxPackage ke false:

<Project ...>
  ...
  <PropertyGroup Label="Globals">
    ...
    <AppxPackage>false</AppxPackage>
    ...
  </PropertyGroup> 
  ...
</Project>

C#. Untuk memulai aplikasi C# dari Visual Studio (baik Debugging atau Tanpa Debugging), pilih profil Peluncuran tidak dikemas dari menu drop-down Mulai. Jika profil Paket dipilih, maka Anda akan melihat kesalahan penyebaran di Visual Studio. Langkah ini tidak diperlukan jika Anda memulai aplikasi (.exe) dari baris perintah atau dari Windows File Explorer.
Bangun dan jalankan.

The bootstrapper API

<WindowsPackageType>None</WindowsPackageType> Mengatur properti proyek menyebabkan penginisialisasi otomatis menemukan dan memuat versi SDK Aplikasi Windows yang paling sesuai untuk aplikasi Anda.

Jika Anda memiliki kebutuhan lanjutan (seperti penanganan kesalahan kustom, atau untuk memuat versi SDK Aplikasi Windows tertentu), maka Anda dapat memanggil API bootstrapper secara eksplisit. Untuk informasi selengkapnya, lihat Menggunakan runtime SDK Aplikasi Windows untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas, dan Tutorial: Menggunakan API bootstrapper dalam aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas yang menggunakan SDK Aplikasi Windows.

Untuk informasi selengkapnya tentang bootstrapper, lihat Arsitektur penyebaran dan gambaran umum untuk aplikasi yang bergantung pada kerangka kerja.

Lihat kode dalam templat proyek

Dalam panduan ini, kami menggunakan templat proyek Blank App, Packaged (WinUI 3 in Desktop), yang membuat aplikasi desktop dengan antarmuka pengguna berbasis WinUI 3. Mari kita lihat beberapa kode yang disertakan dengan templat itu, dan apa fungsinya. Untuk informasi selengkapnya tentang templat proyek dan item WinUI 3 yang tersedia, lihat Templat WinUI 3 di Visual Studio.

Titik masuk aplikasi

Saat sistem operasi Windows (OS) menjalankan aplikasi, OS memulai eksekusi di titik masuk aplikasi. Titik masuk tersebut mengambil bentuk fungsi Main (atau wWinMain untuk C++/WinRT). Biasanya, proyek baru mengonfigurasi fungsi tersebut agar dibuat secara otomatis oleh proses build Visual Studio. Dan itu disembunyikan secara default, jadi Anda tidak perlu khawatir dengannya. Tetapi jika Anda ingin tahu info lebih lanjut, lihat Single-instancing di Main atau wWinMain.

Kelas Aplikasi

Aplikasi secara keseluruhan diwakili oleh kelas yang biasanya disebut hanya Aplikasi. Kelas tersebut didefinisikan dalam App.xaml dan dalam file code-behind -nya (App.xaml.cs, atau App.xaml.h dan .cpp). Aplikasi berasal dari kelas WinUI 3 Microsoft.UI.Xaml.Application .

Kode yang dihasilkan dalam titik masuk membuat instans Aplikasi, dan mengaturnya berjalan.

Di konstruktor Aplikasi, Anda akan melihat metode InitializeComponent yang dipanggil. Metode itu pada dasarnya mengurai konten App.xaml, yaitu markup XAML. Dan itu penting karena App.xaml berisi sumber daya gabungan yang perlu diselesaikan dan dimuat ke dalam kamus untuk digunakan aplikasi yang sedang berjalan.

Metode aplikasi lain yang menarik adalah OnLaunched. Di sana kita membuat dan mengaktifkan instans baru kelas MainWindow (yang akan kita lihat berikutnya).

Kelas MainWindow

Jendela utama yang ditampilkan oleh aplikasi tentu saja diwakili oleh kelas MainWindow . Kelas tersebut didefinisikan dalam MainWindow.xaml dan dalam file code-behind (MainWindow.xaml.cs, atau MainWindow.xaml.h dan .cpp). MainWindow berasal dari kelas WinUI 3 Microsoft.UI.Xaml.Window .

Konstruktor MainWindow memanggil metode InitializeComponent sendiri. Sekali lagi, tugasnya adalah mengubah markup XAML di dalam MainWindow.xaml menjadi grafik objek antarmuka pengguna (UI).

Di MainWindow.xaml Anda akan melihat tata letak dasar MainWindow. Di akar tata letak adalah panel dinamis yang disebut Microsoft.UI.Xaml.Controls.StackPanel. Untuk informasi selengkapnya tentang panel tata letak, lihat Panel tata letak.

Di dalam StackPanel itu ada Microsoft.UI.Xaml.Controls.Button. Dan Tombol tersebut menggunakan markup Click="myButton_Click" untuk secara deklaratif menghubungkan metode penanganan aktivitas untuk peristiwa Klik.

Metode tersebut diberi nama myButton_Click, dan Anda dapat menemukan implementasi metode tersebut di MainWindow.xaml.cs, atau di MainWindow.xaml.cpp. Di dalamnya, konten tombol diubah dari default "Klik Saya" menjadi "Diklik".

C++. Jika Anda membuat proyek C++, maka Anda juga akan melihat MainWindow.idl file. Untuk informasi selengkapnya, lihat dokumentasi C++/WinRT . Kontrol XAML; bind ke properti C++/WinRT adalah tempat yang baik untuk mulai belajar tentang tujuan dan penggunaan .idl file.

Langkah berikutnya

Topik ini menunjukkan cara membuat proyek Visual Studio untuk aplikasi yang dikemas atau tidak dikemas. Untuk contoh menambahkan fungsionalitas ke aplikasi seperti itu, lihat Tutorial: Membuat penampil foto sederhana dengan WinUI 3. Topik itu berjalan melalui proses membangun aplikasi sederhana untuk menampilkan foto.

Kemudian, untuk melanjutkan perjalanan pengembangan Anda dengan SDK Aplikasi Windows, lihat Mengembangkan aplikasi desktop Windows.

Bagikan melalui

Buat proyek WinUI 3 (SDK Aplikasi Windows) pertama Anda

Dikemas, tidak dikemas, dan dikemas dengan lokasi eksternal

Dipaketkan: Buat proyek baru untuk aplikasi desktop C# atau C++ WinUI 3 yang dipaketkan

Unpackaged: Membuat proyek baru untuk aplikasi desktop C# atau C++ WinUI 3 yang tidak dikemas

The bootstrapper API

Lihat kode dalam templat proyek

Titik masuk aplikasi

Kelas Aplikasi

Kelas MainWindow

Langkah berikutnya

Sumber Daya Tambahan:

Bagikan melalui

Buat proyek WinUI 3 (SDK Aplikasi Windows) pertama Anda

Dikemas, tidak dikemas, dan dikemas dengan lokasi eksternal

Dipaketkan: Buat proyek baru untuk aplikasi desktop C# atau C++ WinUI 3 yang dipaketkan

Unpackaged: Membuat proyek baru untuk aplikasi desktop C# atau C++ WinUI 3 yang tidak dikemas

The bootstrapper API

Lihat kode dalam templat proyek

Titik masuk aplikasi

Kelas Aplikasi

Kelas MainWindow

Langkah berikutnya

Topik terkait

Sumber Daya Tambahan: