Pengenalan Program WinUI C++ Pertama

Posted on 2026年7月3日 by

Pada pelajaran sebelumnya, kita sudah menyelesaikan pemasangan WinUI C++ dan membuat program pertama yang bisa berjalan normal. Pada pelajaran kali ini, kita akan menganalisis struktur program WinUI C++ pertama yang sudah dibuat.

Direktori solusi proyek

Berikut penjelasan fungsi setiap file dan folder.

Analisis Direktori Proyek

Nama Solusi

Di bagian paling atas tertulis “Solution ‘App3’”, ini adalah nama solusi, dalam kasus ini bernama App3. Saat membuat proyek, kamu bisa menentukan nama solusi sendiri, secara default namanya sama dengan nama proyek.

Layar pembuatan proyek

Pada tangkapan layar di atas, kolom input pertama adalah nama proyek, kolom terakhir adalah nama solusi. Secara default keduanya sama, tapi kamu bisa memberikan nama yang berbeda.

Satu solusi bisa menampung banyak proyek, di sini hanya ada satu proyek paket desktop yaitu App3 (Desktop).

1. References (Referensi)

Folder ini menyimpan referensi SDK yang dibutuhkan proyek, Windows App SDK, runtime WinRT, serta komponen yang dipasang melalui NuGet:

  • Semua dependensi dikelola di sini: Windows SDK, pustaka kontrol WinUI 3, file header C++/WinRT, Microsoft.UI.Xaml dan lainnya;
  • Tidak perlu diedit secara manual, Visual Studio akan memperbarui secara otomatis saat mengelola paket NuGet.
Daftar referensi (potongan tangkapan layar)

2. External Dependencies (Dependensi Luar)

Folder ini akan memindai secara otomatis file header sistem, header SDK, dan header pustaka pihak ketiga:

  • Windows.h, kelompok header winrt/, header dasar Microsoft.UI.Xaml;
  • Hanya bisa dibaca, berfungsi untuk melihat kode luar yang dimasukkan, tidak bisa diedit manual. Biasanya berisi pustaka yang terpasang bersama Visual Studio.
File dependensi luar (potongan)

Klik dua kali sembarang file untuk membukanya, kamu akan melihat lokasinya ada di direktori instalasi Visual Studio. Arahkan kursor ke nama file di bagian atas untuk menampilkan path lengkap file tersebut.

3. Folder Assets Sumber Daya (Ikon Aplikasi / Layar Splash)

Semua gambar di sini digunakan untuk Microsoft Store, jendela sistem, layar splash saat buka aplikasi, layar kunci layar, diperlukan untuk pengemasan dan rilis ke Microsoft Store:

Mengapa file ini ada? Karena saat buat proyek kita memilih template paket. Pengemasan artinya nanti program akan dikompilasi menjadi file MSIX untuk dipasarkan di Microsoft Store. Apa beda proyek paket dan non-paket? Proyek non-paket menghasilkan file exe tunggal yang bisa langsung dijalankan dengan klik dua kali, seperti banyak proyek lama. Sedangkan proyek paket menggabungkan semua exe, dll dan sumber daya ke dalam satu file instalasi, pengguna cukup klik dua kali file tersebut untuk memasang aplikasi. Kita pilih template ini karena aplikasi nanti akan dirilis ke Microsoft Store.

Gambar di atas adalah template yang kita pilih saat buat proyek. Dari deskripsinya terlihat template ini menghasilkan file MSIX untuk rilis Microsoft Store. Toko memerlukan banyak ikon dan gambar, sehingga semua sumber daya ini sudah ada di proyek. Kita juga bisa membuat proyek non-paket yang hanya menghasilkan exe langsung, akan dibahas pada pelajaran berikutnya.

Fungsi Setiap Gambar
Nama FileFungsi
LockScreenLogo.scale-200.pngIkon aplikasi di layar kunci layar (skala DPI tinggi 200%)
SplashScreen.scale-200.pngLayar splash saat program dibuka
Square44x44Logo… banyak gambarIkon kecil menu Mulai, ikon taskbar, thumbnail jendela Alt+Tab
Square150x150Logo.scale-200.pngIkon ubin menengah menu Mulai
StoreLogo.pngIkon besar aplikasi yang ditampilkan di Microsoft Store
Wide310x150Logo.scale-200.pngUbin lebar menu Mulai

app.manifest

Manifest aplikasi Windows tradisional (kompatibel Win32):

  • Mengatur izin aplikasi, versi Windows yang kompatibel, deteksi DPI, izin administrator, perilaku skala jendela;
  • Berbeda dengan Package.appxmanifest milik UWP, proyek paket desktop memiliki dua manifest sekaligus.

4. App.xaml / App.xaml.h / App.xaml.cpp

Kelas akar global titik masuk aplikasi (sesuai winrt::App3::App)

  1. App.xaml: Kamus sumber daya XAML global. Gaya global, template kontrol, warna, font, sumber daya tema yang dipakai semua halaman proyek.
  2. App.xaml.h: File header otomatis buatan C++/WinRT, mendeklarasikan kelas App beserta fungsi siklus hidup seperti OnLaunched, OnActivated.
  3. App.xaml.cpp: Implementasi logika siklus hidup aplikasi
    • OnLaunched: Dijalankan saat aplikasi dibuka, membuat dan menampilkan jendela MainWindow;
    • Mengelola aktivasi jendela, penangguhan, pergantian tema, penangkapan kesalahan;
    • Semua logika inisialisasi global (font, database, layanan singleton) ditulis di sini.

Buka file cpp, kamu akan melihat kode berikut:

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make<MainWindow>();
        window.Activate();
    }Code language: C++ (cpp)
Dari bagian ini program berpindah ke MainWindow. App hanya titik masuk dan tidak membuat jendela, MainWindow adalah tempat sebenarnya membuat jendela, kontrol dan dialog yang kita lihat.

5. Kumpulan MainWindow.xaml (Jendela Utama)

Jendela utama bawaan program, jendela akar tampilan teratas aplikasi desktop.

  1. MainWindow.xaml: Tata letak jendela. Tombol, kotak teks, kontrol navigasi, Frame penampung halaman semuanya ditulis di sini;
  2. MainWindow.idl: File definisi antarmuka IDL (inti C++/WinRT). Mendeklarasikan properti, metode, event yang dibuka jendela untuk binding XAML, panggilan antar komponen, pembuatan metadata tipe. Setelah diedit akan otomatis menghasilkan file penghubung .h/.cpp.
  3. MainWindow.xaml.h: File header kelas otomatis dari IDL + XAML, berisi deklarasi anggota kontrol, konstruktor, handler event.
  4. MainWindow.xaml.cpp: Logika bisnis jendela: kode klik tombol, binding data, perpindahan halaman, interaksi kontrol.

Berikut isi MainWindow.xaml tempat menampilkan kontrol dan tata letak:

<?xml version="1.0" encoding="utf-8"?>
<Window
    x:Class="App3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:App3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Title="App3">

    <Grid>

    </Grid>
</Window>
Code language: HTML, XML (xml)

6. module.g.cpp

File modul global C++/WinRT buatan otomatis (dilarang edit manual)

  • Membuat kode pendaftaran tipe WinRT berdasarkan semua file .idl;
  • Menyediakan titik masuk namespace winrt::App3::implementation agar sistem mengenali kontrol XAML dan kelas jendela buatan sendiri;
  • Jika menambah/hapus file IDL, Visual Studio akan menghasilkan ulang file ini secara otomatis.

7. Package.appxmanifest (Manifest Paket MSIX, File Paling Penting)

File konfigurasi untuk mengemas aplikasi desktop menjadi paket instalasi MSIX. Klik dua kali untuk buka editor visual:

  • Nama aplikasi, versi, penerbit, ikon, titik jalankan;
  • Deklarasi izin sistem (akses file, kamera, jaringan, tugas latar belakang);
  • Hubungan protokol buka file, protokol URL, ekstensi tambahan;
  • Pengaturan informasi rilis toko, shortcut desktop, hubungan file. Perbedaan dengan app.manifest: file ini adalah manifest khusus Microsoft Store / paket MSIX, hanya untuk UWP dan aplikasi desktop paket.

Di sini kita atur hal terkait Microsoft Store seperti versi, nama paket, penerbit dan lain-lain. Data ini harus diambil dari portal pengembang Microsoft Store.

8. packages.config

File konfigurasi paket NuGet: mencatat versi semua paket NuGet yang terpasang di proyek, contohnya:

  • Pustaka Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3;
  • Saat kerja tim atau ganti komputer, Visual Studio pakai file ini untuk memulihkan semua paket dependensi otomatis.

9. pch.h/pch.cpp (Header Terkompilasi Awal, Percepat Kompilasi C++)

pch = Precompiled Header (Header terkompilasi awal)

  1. pch.h: Tempatkan semua header umum global (winrt/Windows.*, Microsoft.UI.Xaml.*, pustaka standar). Semua file cpp diawali baris #include "pch.h";
  2. pch.cpp: File sumber untuk kompilasi header awal. Fungsi: sangat mengurangi waktu kompilasi karena tidak perlu muat ratusan header sistem tiap file satu per satu.

Semua perintah include yang sering dipakai dikumpulkan di file ini, file sumber lain cukup include file ini saja, mengurangi jumlah kode dan mempercepat proses kompilasi.

10. readme.txt

Dokumen penjelasan bawaan template Visual Studio, berisi petunjuk dasar kompilasi, pengemasan dan debug proyek WinUI 3 C++.

Dua File Manifest yang Sering Salah Paham

  1. app.manifest → Manifest proses Win32 tradisional (pengaturan jendela, kompatibilitas sistem, izin)
  2. Package.appxmanifest → Manifest paket aplikasi MSIX (rilis toko, instalasi, deklarasi fitur sistem)

Alur Eksekusi Keseluruhan Program

  1. Program mulai → Masuk ke App::OnLaunched(App.xaml.cpp)
  2. Buat instance MainWindow dan aktifkan untuk tampil window = make(); window.Activate();
  3. MainWindow.xaml merender tampilan, file cpp proses semua interaksi pengguna
  4. Saat buat paket instalasi, baca Package.appxmanifest untuk generate installer, semua ikon di folder Assets disematkan ke dalam paket

Sekian penjelasan lengkap struktur folder dan alur jalannya proyek kosong paling sederhana. Pelajaran selanjutnya kita akan tambahkan tombol di jendela yang angka bertambah tiap kali diklik, supaya paham cara kerja framework WinUI C++.

POSTED IN Belum diklasifikasikan

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *