첫 WinUI C++ 프로그램 소개 - WinUI C++ 튜토리얼

지난 수업에서는 WinUI C++ 설치와 첫 프로젝트 생성을 마치고 프로그램이 정상 실행되는 것을 확인했습니다. 이번 시간에는 방금 만든 첫 WinUI C++ 프로그램의 내부 구조를 분석해 보겠습니다.

아래에서 각 파일과 폴더의 역할을 분석하겠습니다.

프로젝트 디렉터리 분석

솔루션 이름

최상단에 보이는 Solution ‘App3’가 솔루션 이름으로, 여기서는 App3입니다. 프로젝트 생성 시 원하는 솔루션명을 지정할 수 있으며 기본값은 프로젝트 이름과 동일합니다.

위 이미지의 첫 입력창은 프로젝트 이름, 마지막 입력창은 솔루션 이름입니다. 기본적으로 동일한 이름이 입력되지만 별도로 다르게 설정할 수 있습니다.

하나의 솔루션에는 여러 프로젝트를 담을 수 있으며, 여기에는 데스크톱 패키지 프로젝트인 App3 (Desktop) 단 하나만 포함되어 있습니다.

1. References (참조)

프로젝트 의존성 SDK, Windows App SDK, WinRT 런타임, NuGet으로 설치한 컴포넌트 참조를 저장하는 폴더입니다.

Windows SDK, WinUI 3 컨트롤 라이브러리, C++/WinRT 헤더 라이브러리, Microsoft.UI.Xaml 등 의존 라이브러리를 모두 관리합니다.
수동 수정할 필요 없으며, Visual Studio에서 NuGet 패키지를 관리할 때 자동으로 업데이트됩니다.

2. External Dependencies (외부 의존성)

시스템 헤더 파일, SDK 헤더, 서드파티 라이브러리 헤더 파일을 자동 스캔하여 보여주는 폴더입니다.

Windows.h, winrt/ 계열 헤더, Microsoft.UI.Xaml 하위 헤더 등이 포함됩니다.
읽기 전용으로 외부에서 불러온 코드를 확인하는 용도일 뿐 수동 편집은 불가능하며, 주로 Visual Studio 설치 시 함께 제공되는 라이브러리입니다.

아무 파일이나 더블클릭하여 열면 파일 경로가 Visual Studio 설치 디렉터리임을 확인할 수 있습니다. 상단 파일명에 마우스를 올리면 전체 경로가 표시됩니다.

3. Assets 리소스 폴더 (앱 아이콘 / 시작 화면)

마이크로소프트 스토어, 시스템 팝업, 앱 시작 스플래시 화면, 잠금 화면에서 사용하는 이미지 리소스가 저장되며 MSIX 패키지 제작 및 스토어 등록에 활용합니다.

이런 이미지 파일들이 존재하는 이유는 프로젝트 생성 시 패키지형 템플릿을 선택했기 때문입니다. 패키지란 최종적으로 MSIX 또는 마이크로소프트 스토어 배포용 파일로 컴파일하는 형식을 의미합니다. 패키지형과 비패키지형의 차이는 다음과 같습니다. 비패키지형은 단독 exe 파일로 실행 가능하며 예전에 개발한 대부분 프로젝트가 해당합니다. 컴파일 후 exe를 더블클릭하면 바로 실행됩니다. 반면 패키지형은 exe, dll, 모든 리소스 파일을 하나의 패키지로 묶어 사용자가 패키지 파일만 실행하면 자동으로 설치되는 구조입니다. 본 프로젝트는 마이크로소프트 스토어에 출시할 목적으로 packaged 템플릿을 선택했습니다.

위 이미지는 프로젝트 생성 시 선택한 템플릿이며 설명에서 마이크로소프트 스토어 배포용 MSIX 파일을 출력하는 프로젝트임을 알 수 있습니다. 스토어 등록에는 다양한 아이콘과 이미지가 필수이므로 프로젝트에 기본 리소스가 포함된 것입니다. 패키지를 사용하지 않고 단독 exe로 컴파일해 직접 실행하는 방식도 가능하며 자세한 내용은 이후 수업에서 다루겠습니다.

각 이미지 파일의 역할

파일명	역할
LockScreenLogo.scale-200.png	잠금 화면 앱 아이콘 (200% 고해상도 DPI 스케일링 지원)
SplashScreen.scale-200.png	앱 시작 시 보여지는 스플래시 화면
Square44x44Logo… 여러 이미지	시작 메뉴 소형 아이콘, 작업 표시줄 아이콘, Alt+Tab 창 미리보기 이미지
Square150x150Logo.scale-200.png	시작 메뉴 중형 타일 아이콘
StoreLogo.png	마이크로소프트 스토어에 표시되는 앱 대형 아이콘
Wide310x150Logo.scale-200.png	시작 메뉴 가로형 타일 아이콘

app.manifest

기존 윈도우 애플리케이션 매니페스트 (Win32 호환용)

앱 권한, 호환 윈도우 버전, DPI 인식 설정, 관리자 권한, 창 스케일링 동작을 설정합니다.
UWP의 Package.appxmanifest와 별개 파일로, 데스크톱 패키지 프로젝트는 두 가지 매니페스트가 공존합니다.

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

애플리케이션 전역 진입점 루트 클래스 (winrt::App3::App에 해당)

App.xaml：XAML 전역 리소스 사전. 전역 스타일, 컨트롤 템플릿, 색상, 폰트, 테마 리소스를 정의하며 프로젝트 모든 페이지에서 공유합니다.
App.xaml.h：C++/WinRT가 자동 생성한 헤더 파일로 App 클래스를 선언하며 OnLaunched, OnActivated 등 생명주기 함수를 포함합니다.
App.xaml.cpp：앱 생명주기 로직 구현
- OnLaunched：앱 실행 시 호출되며 MainWindow를 생성하고 표시합니다.
- 창 활성화, 일시 중지, 테마 전환, 예외 처리 로직을 작성합니다.
- 전역 초기화 로직 (폰트, 데이터베이스, 싱글톤 서비스)을 여기에 작성합니다.

cpp 파일을 열면 아래 코드를 확인할 수 있습니다.

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make<MainWindow>();
        window.Activate();
    }Code language: C++ (cpp)

이 부분부터 프로그램 제어가 MainWindow로 넘어갑니다. App은 단순 진입점일 뿐 창을 생성하지 않으며, 실제 사용자가 보이는 창, 컨트롤, 다이얼로그를 만드는 곳은 MainWindow입니다.

5. MainWindow.xaml 세트 (메인 창)

프로그램 기본 메인 창으로 데스크톱 앱의 최상위 시각적 루트 창입니다.

MainWindow.xaml：창 화면 레이아웃. 버튼, 텍스트박스, 네비게이션 컨트롤, 페이지를 담는 Frame을 작성합니다.
MainWindow.idl：IDL 인터페이스 정의 파일 (C++/WinRT 핵심). 창이 외부에 노출하는 속성, 메서드, 이벤트를 정의하며 XAML 바인딩, 컴포넌트 간 호출, 타입 메타데이터 생성에 사용합니다. 수정하면 자동으로 .h/.cpp 연결 코드가 생성됩니다.
MainWindow.xaml.h：IDL + XAML에서 자동 생성된 클래스 헤더로 컨트롤 멤버, 생성자, 이벤트 핸들러 선언을 담습니다.
MainWindow.xaml.cpp：창 비즈니스 로직. 버튼 클릭 이벤트, 데이터 바인딩, 페이지 전환, 컨트롤 상호작용 코드를 작성합니다.

아래 MainWindow.xaml은 컨트롤과 레이아웃을 정의하는 파일입니다.

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

C++/WinRT 전역 모듈 자동 생성 파일 (수동 수정 금지)

모든 .idl 파일을 기반으로 WinRT 타입 등록 코드를 생성합니다.
winrt::App3::implementation 네임스페이스 진입점을 제공해 시스템이 사용자 정의 XAML 컨트롤과 창 클래스를 인식하도록 합니다.
IDL 파일 추가/삭제 후 Visual Studio가 자동으로 재생성합니다.

7. Package.appxmanifest (MSIX 패키지 매니페스트, 가장 중요한 파일)

데스크톱 앱을 MSIX 설치 패키지로 빌드하기 위한 설정 파일로 더블클릭하면 시각적 편집기로 열립니다.

앱 이름, 버전, 게시자, 아이콘, 실행 진입점 설정.
시스템 권한 선언 (파일 접근, 카메라, 네트워크, 백그라운드 작업).
파일 열기 프로토콜, URL 프로토콜, 확장 기능 연결 설정.
스토어 등록 정보, 데스크톱 바로가기, 파일 연결 구성. app.manifest와 차이점: 이 파일은 마이크로소프트 스토어 / MSIX 패키지 전용 매니페스트로 UWP 및 패키지형 데스크톱 앱에서 사용합니다.

예를 들어 버전, 패키지명, 게시자 정보 등 마이크로소프트 스토어 관련 설정을 여기 작성하며 해당 정보는 마이크로소프트 스토어 개발자 페이지에서 발급받아야 합니다.

8. packages.config

NuGet 패키지 설정 파일로 프로젝트에 설치된 모든 NuGet 패키지 버전을 기록합니다.

Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3 라이브러리 등.
팀 협업이나 다른 PC로 작업 환경을 옮길 때 Visual Studio가 이 파일을 참고해 의존 패키지를 자동 복구합니다.

9. pch.h/pch.cpp (사전 컴파일 헤더, C++ 컴파일 속도 향상)

pch = Precompiled Header (사전 컴파일 헤더)

pch.h：전역 공통 헤더를 한 번에 포함 (winrt/Windows.*, Microsoft.UI.Xaml.*, 표준 라이브러리 등). 모든 cpp 파일 최상단에 #include "pch.h"를 작성합니다.
pch.cpp：사전 컴파일 헤더 전용 소스 파일. 역할: 모든 소스 파일에서 반복적으로 시스템 헤더를 불러오지 않아 컴파일 시간을 크게 단축합니다.

공통으로 사용하는 include 구문을 이 파일에 모아두고 다른 소스에서 이 파일만 불러오면 코드 양을 줄이고 컴파일 속도를 높일 수 있습니다.

10. readme.txt

Visual Studio 템플릿 기본 설명 문서로 WinUI 3 C++ 프로젝트 기본 빌드, 패키지 제작, 디버깅 방법이 기록되어 있습니다.

혼동하기 쉬운 두 가지 manifest 파일

app.manifest → 기존 Win32 프로세스 매니페스트 (창 설정, 시스템 호환성, 권한 관리)
Package.appxmanifest → MSIX 앱 패키지 매니페스트 (스토어 출시, 설치 설정, 시스템 기능 선언)

프로그램 전체 실행 흐름

앱 실행 → App::OnLaunched(App.xaml.cpp) 진입
MainWindow 인스턴스 생성 후 활성화 및 표시 window = make(); window.Activate();
MainWindow.xaml이 화면을 렌더링하고 cpp 파일이 사용자 상호작용을 처리
패키지 빌드 시 Package.appxmanifest 정보를 읽어 설치 파일을 생성하며 Assets 폴더의 아이콘 이미지가 패키지에 내장됨

이상으로 가장 간단한 빈 앱의 디렉터리 구조와 실행 순서에 대한 전체 설명입니다. 다음 수업에서는 창에 버튼을 추가하고 클릭할 때 숫자가 증가하는 기능을 구현해 WinUI C++ 프레임워크의 작동 원리를 이해하겠습니다.

Previous: WinUI C++ 설치 및 첫 프로젝트 생성