UWP용 WinUI 2 시작

2025-05-05

WinUI 2.8은 프로덕션 UWP 애플리케이션(및 XAML Islands를 사용하는 데스크톱 애플리케이션)을 빌드하는 데 사용할 수 있는 안정적인 최신 버전의 WinUI입니다.

라이브러리는 신규 또는 기존 Visual Studio 프로젝트에 추가할 수 있는 NuGet 패키지로 제공됩니다.

비고

최신 버전의 WinUI 3을 사용하여 Windows 데스크톱 앱을 빌드하는 방법에 대한 자세한 내용은 WinUI 3을 참조하세요.

UWP 개발을 위한 Visual Studio 설정

Visual Studio 2022를 다운로드하고 UWP 개발을 위한 도구를 설치합니다. 자세한 지침은 Visual Studio 문서에서 UWP 앱 만들기 를 참조하세요.

Visual Studio 설치 관리자 앱의 워크로드 탭에서 다음 워크로드 및 구성 요소를 선택합니다.

Visual Studio 2022 버전 17.10 이상
이전 버전의 Visual Studio

WinUI 애플리케이션 개발 워크로드를 선택합니다. 그런 다음 설치 세부 정보 창의 WinUI 애플리케이션 개발 노드에서 필요한 UWP 옵션을 선택합니다(필요한 추가 구성 요소도 선택).
- C#의 경우 유니버설 Windows 플랫폼 도구를 선택합니다.
- C++의 경우 C++(v14x) 유니버설 Windows 플랫폼 도구를 선택합니다(이전 버전을 사용할 특정 이유가 없는 경우 최신 버전 선택).

비고

Visual Studio 17.10 - 17.12에서 이 워크로드는 Windows 애플리케이션 개발이라고 합니다.

WinUI 다운로드 및 설치

기존 프로젝트를 열거나 Visual C# > Windows > 유니버설 아래의 빈 앱 템플릿 또는 언어 프로젝션에 적합한 템플릿을 사용하여 새 프로젝트를 만듭니다.

중요합니다

WinUI 2.7을 사용하려면 프로젝트 속성에서 TargetPlatformVersion >= 10.0.18362.0 및 TargetPlatformMinVersion >= 10.0.15063.0으로 설정해야 합니다.
솔루션 탐색기 창에서 마우스 오른쪽 단추로 프로젝트 이름을 클릭하고, NuGet 패키지 관리를 선택합니다.

프로젝트를 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리 옵션이 강조 표시된 솔루션 탐색기 패널
NuGet 패키지 관리자에서 찾아보기 탭을 선택하고 Microsoft.UI.Xaml 또는 WinUI를 검색합니다. 사용할 WinUI NuGet 패키지를 선택합니다(Microsoft.UI.Xaml 패키지에는 모든 앱에 적합한 Fluent 컨트롤 및 기능이 포함되어 있음). Install을 클릭합니다.

"시험판 포함" 확인란을 선택하면 새로운 실험적 기능이 포함된 최신 시험판 버전을 볼 수 있습니다.

NuGet 패키지 관리자 대화 상자는 검색 필드에 winui가 입력되어 있고 [시험판 포함] 확인란이 선택된 [찾아보기] 탭을 보여줍니다.

WinUI 테마 리소스를 App.xaml 파일에 추가합니다.

추가 애플리케이션 리소스가 있는지 여부에 따라 이를 수행하는 두 가지 방법이 있습니다.

a. 다른 애플리케이션 리소스가 필요 없는 경우 다음 예제와 같이 WinUI 리소스 요소 XamlControlsResources를 추가합니다.

<Application
    x:Class="ExampleApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    RequestedTheme="Light">

    <Application.Resources>
        <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
    </Application.Resources>

</Application>

b. 다른 리소스를 보유하고 있다면, 그 리소스를 XamlControlsResources.MergedDictionaries에 추가할 것을 추천합니다. 이 작업은 플랫폼의 리소스 시스템에서 작동하여 XamlControlsResources 리소스 재정의를 허용합니다.

<Application
    x:Class="ExampleApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    RequestedTheme="Light">

    <Application.Resources>
        <controls:XamlControlsResources>
            <controls:XamlControlsResources.MergedDictionaries>
                <ResourceDictionary Source="/Styles/Styles.xaml"/>
                <!-- Other app resources here -->
            </controls:XamlControlsResources.MergedDictionaries>
        </controls:XamlControlsResources>
    </Application.Resources>

</Application>

XAML 페이지 및/또는 코드-비하인드 페이지에 WinUI 패키지에 대한 참조를 추가합니다.
- XAML 페이지에서 참조를 페이지 위쪽에 추가합니다.
```
xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
```
- 코드에서(형식 이름을 한정하지 않고 사용하려는 경우) using 지시문을 추가할 수 있습니다.
```
using MUXC = Microsoft.UI.Xaml.Controls;
```

C++/WinRT 프로젝트에 대한 추가 단계

NuGet 패키지를 C++/WinRT 프로젝트에 추가하면 도구에서 일단의 프로젝션 헤더를 프로젝트의 \Generated Files\winrt 폴더에 생성합니다. 이러한 헤더 파일을 프로젝트로 가져와서 새 형식에 대한 참조가 확인되도록 하려면 미리 컴파일된 헤더 파일(일반적으로 pch.h)로 이동하여 포함시킬 수 있습니다. 다음은 Microsoft.UI.Xaml 패키지에 대해 생성된 헤더 파일이 포함된 예제입니다.

// pch.h
...
#include <winrt/Microsoft.UI.Xaml.Automation.Peers.h>
#include <winrt/Microsoft.UI.Xaml.Controls.Primitives.h>
#include <winrt/Microsoft.UI.Xaml.Media.h>
#include <winrt/Microsoft.UI.Xaml.XamlTypeInfo.h>
...

WinUI에 대한 간단한 지원을 C++/WinRT 프로젝트에 추가하는 방법에 대한 전체 단계별 연습은 간단한 C++/WinRT WinUI 예제를 참조하세요.

GitHub의 WinUI

GitHub의 microsoft-ui-xaml 리포지토리에서 버그 보고서를 환영합니다.