데스크톱 앱에서 WinRT XAML 컨트롤 호스팅(XAML Islands)

  • 아티클

중요

이 항목에서는 CommunityToolkit/Microsoft.Toolkit.Win32 GitHub 리포지토리의 형식을 사용하거나 다룹니다. XAML Islands 지원에 대한 중요한 정보는 해당 리포지토리의 XAML Islands 알림을 참조하세요.

Windows 10 버전 1903부터 XAML Islands라는 기능을 사용하여 UWP 이외의 데스크톱 애플리케이션에서 WinRT XAML 컨트롤을 호스팅할 수 있습니다. 이 기능을 사용하면 WinRT XAML 컨트롤을 통해서만 사용할 수 있는 최신 Windows UI 기능을 사용하여 기존 WPF, Windows Forms 및 C++ 데스크톱(Win32) 애플리케이션의 모양, 느낌 및 기능을 향상시킬 수 있습니다. 즉, Windows Ink와 같은 UWP 기능과 Fluent Design 시스템을 지원하는 컨트롤을 기존 WPF, Windows Forms 및 C++ 데스크톱 애플리케이션에서 사용할 수 있습니다.

다음을 포함하여 Windows.UI.Xaml.UIElement에서 파생되는 모든 WinRT XAML 컨트롤을 호스팅할 수 있습니다.

  • Windows SDK 또는 WinUI 2 라이브러리에서 제공하는 대부분의 자사 WinRT XAML 컨트롤(예외 참조).
  • 사용자 지정 WinRT XAML 컨트롤(예: 함께 작동하는 여러 WinRT XAML 컨트롤로 구성된 사용자 컨트롤). 애플리케이션을 사용하여 컴파일할 수 있도록 사용자 지정 컨트롤에 대한 소스 코드가 있어야 합니다.

기본적으로 XAML Island는 WinRT XAML 호스팅 API로 생성됩니다. 이 API는 Windows 10, 버전 1903 SDK에 도입된 몇 가지 Windows 런타임 클래스 및 COM 인터페이스로 구성됩니다. 또한 내부적으로 WinRT XAML 호스팅 API를 사용하고 WPF 및 Windows Forms 앱을 보다 편리하게 개발할 수 있는 환경을 제공하는 Windows 커뮤니티 도구 키트에 XAML Island .NET 컨트롤 세트가 제공됩니다.

XAML Island를 사용하는 방법은 애플리케이션 유형 및 호스팅하려는 WinRT XAML 컨트롤 형식에 따라 달라집니다.

참고

XAML Island에 대한 피드백이 있는 경우 Microsoft.Toolkit.Win32 리포지토리에서 새 이슈를 만들고 의견을 남겨 주세요.

요구 사항

XAML Islands의 런타임 요구 사항은 다음과 같습니다.

  • Windows 10 버전 1903 이상 릴리스.
  • 애플리케이션이 배포용 MSIX 패키지에 패키징되지 않은 경우, 컴퓨터에 Visual C++ Runtime이 설치되어 있어야 합니다.

WPF 및 Windows Forms 애플리케이션

참고

XAML Islands를 사용하여 WinRT XAML 컨트롤을 호스팅하는 것은 현재 .NET Core 3.x를 대상으로 하는 WPF 및 Windows Forms 앱에서만 지원됩니다. .NET을 대상으로 하는 앱 또는 .NET Framework 버전을 대상으로 하는 앱에서는 아직 XAML Islands가 지원되지 않습니다.

WPF 및 Windows Forms 애플리케이션은 Windows 커뮤니티 도구 키트에 제공되는 XAML Island .NET 컨트롤을 사용하는 것이 좋습니다. 이러한 컨트롤은 해당 WinRT XAML 컨트롤의 속성, 메서드 및 이벤트를 모방하거나 이에 대한 액세스를 제공하는 개체 모델을 제공합니다. 또한 키보드 탐색 및 레이아웃 변경과 같은 동작을 처리합니다.

WPF 및 Windows Forms 애플리케이션용 XAML Island 컨트롤 세트는 두 가지가 있으며, 래핑된 컨트롤과 호스트 컨트롤입니다.

래핑된 컨트롤

WPF 및 Windows Forms 애플리케이션은 특정 WinRT XAML 컨트롤의 인터페이스와 기능을 래핑하는 XAML Island 컨트롤을 선택하여 사용할 수 있습니다. WPF 또는 Windows Forms 프로젝트의 디자인 화면에 이러한 컨트롤을 바로 추가하고 디자이너에서 다른 WPF 또는 Windows Forms 컨트롤처럼 사용할 수 있습니다.

현재 Windows 커뮤니티 도구 키트에서 사용할 수 있는 래핑된 WinRT XAML 컨트롤은 다음과 같습니다.

컨트롤 지원되는 최소 OS 설명
InkCanvas
InkToolbar		 Windows 10, 버전 1903 Windows Forms 또는 WPF 데스크톱 애플리케이션에서 Windows Ink 기반 사용자 조작을 위한 화면 및 관련 도구 모음을 제공합니다.
MediaPlayerElement Windows 10, 버전 1903 Windows Forms 또는 WPF 데스크톱 애플리케이션에서 비디오와 같은 미디어 콘텐츠를 스트리밍하고 렌더링하는 것을 포함합니다.
MapControl Windows 10, 버전 1903 Windows Forms 또는 WPF 데스크톱 애플리케이션에서 기호화된 지도 또는 실사 지도를 표시할 수 있습니다.

래핑된 WinRT XAML 컨트롤을 사용하는 방법을 보여 주는 연습은 XAML Islands를 사용하여 C# WPF 앱에서 UWP XAML 컨트롤 호스트를 참조하세요.

호스트 컨트롤

사용 가능한 래핑된 컨트롤에서 다루지 않는 사용자 지정 컨트롤 및 기타 시나리오의 경우 WPF 및 Windows Forms 애플리케이션은 Windows 커뮤니티 도구 키트에서 제공되는 WindowsXamlHost 컨트롤을 사용할 수도 있습니다.

컨트롤 지원되는 최소 OS 설명
WindowsXamlHost Windows 10, 버전 1903 Windows SDK에서 제공하는 자사 WinRT XAML 컨트롤과 사용자 지정 컨트롤을 포함하여 Windows.UI.Xaml.UIElement에서 파생되는 모든 WinRT XAML 컨트롤을 호스팅할 수 있습니다.

WindowsXamlHost 컨트롤을 사용하는 방법을 보여 주는 연습은 XAML Islands를 사용하여 C# WPF 앱에서 UWP XAML 컨트롤 호스트 및 XAML Islands를 사용하여 WPF 앱에서 사용자 지정 WinRT XAML 컨트롤 호스트를 참조하세요.

XAML Island .NET 컨트롤을 사용하도록 프로젝트 구성

XAML Island .NET 컨트롤을 사용하려면 Windows 10, 버전 1903 이상 버전이 필요합니다. 이러한 컨트롤을 사용하려면 아래에 나열된 NuGet 패키지 중 하나를 설치하세요. 이러한 패키지는 XAML Island의 래핑된 컨트롤과 호스트 컨트롤을 사용하는 데 필요한 모든 것을 제공하며, 필요한 다른 관련 NuGet 패키지도 포함하고 있습니다.

컨트롤 유형 NuGet 패키지 관련 문서
래핑된 컨트롤 다음 패키지의 버전 6.0.0 이상: XAML Islands를 사용하여 C# WPF 앱에서 UWP XAML 컨트롤 호스트
호스트 컨트롤 다음 패키지의 버전 6.0.0 이상: XAML Islands를 사용하여 C# WPF 앱에서 UWP XAML 컨트롤 호스트
WPF 앱에서 사용자 지정 WinRT XAML 컨트롤 호스팅

다음 사항에 유의하세요.

  • 호스트 컨트롤 패키지는 래핑된 컨트롤 패키지에도 포함됩니다. 두 컨트롤 세트를 모두 사용하려면 래핑된 컨트롤 패키지를 설치하시길 바랍니다.

  • 사용자 지정 WinRT XAML 컨트롤을 호스팅하는 경우 사용자 지정 컨트롤을 참조하기 위한 몇 가지 추가 단계도 수행해야 합니다. 자세한 내용은 XAML Islands를 사용하여 WPF 앱에서 사용자 지정 WinRT XAML 컨트롤 호스트을 참조하세요.

웹 보기 컨트롤

Windows 커뮤니티 도구 키트는 WPF 및 Windows Forms 애플리케이션에서 웹 콘텐츠를 호스트하는 데 필요한 다음과 같은 .NET 컨트롤도 제공합니다. 이러한 컨트롤은 XAML Island 컨트롤과 유사한 데스크톱 앱 현대화 시나리오에서 종종 사용되며, XAML Island 컨트롤과 동일한 Microsoft.Toolkit.Win32 리포지토리에서 유지 관리할 수 있습니다.

제어 지원되는 최소 OS 설명
WebView Windows 10, 버전 1803 Microsoft Edge 렌더링 엔진을 사용하여 웹 콘텐츠를 표시합니다.
WebViewCompatible Windows 7 더 많은 OS 버전과 호환되는 WebView 버전을 제공합니다. 이 컨트롤은 Microsoft Edge 렌더링 엔진을 사용하여 Windows 10 버전 1803 이상에 웹 콘텐츠를 표시하고 Internet Explorer 렌더링 엔진을 사용하여 이전 버전의 Windows 10, Windows 8.x 및 Windows 7에 웹 콘텐츠를 표시합니다.

이러한 컨트롤을 사용하려면 다음과 같은 NuGet 패키지 중 하나를 설치하세요.

C++ 데스크톱(Win32) 애플리케이션

XAML Island .NET 컨트롤은 C++ 데스크톱 애플리케이션에서 지원되지 않습니다. 이러한 애플리케이션은 Windows 10 SDK(버전 1903 이상)에서 제공하는 WinRT XAML 호스팅 API를 대신 사용해야 합니다.

WinRT XAML 호스팅 API는 C++ 데스크톱 애플리케이션을 통해 Windows.UI.Xaml.UIElement에서 파생되는 모든 WinRT XAML 컨트롤을 호스팅하는 데 사용할 수 있는 몇 가지 Windows 런타임 클래스 및 COM 인터페이스로 구성됩니다. 연결된 창 핸들(HWND)이 있는 애플리케이션의 모든 UI 요소에서 WinRT XAML 컨트롤을 호스팅할 수 있습니다. 이 API에 대한 자세한 내용은 다음 문서를 참조하세요.

참고

Windows 커뮤니티 도구 키트의 래핑된 컨트롤 및 호스트 컨트롤은 내부적으로 WinRT XAML 호스팅 API를 사용하고, 사용자가 WinRT XAML 호스팅 API를 직접 사용한 경우 키보드 탐색 및 레이아웃 변경을 포함하여 직접 처리해야 하는 모든 동작을 구현합니다. WPF 및 Windows Forms 애플리케이션의 경우 API 사용에 대한 많은 구현 세부 정보를 추상화하므로 WinRT XAML 호스팅 API를 직접 사용하는 대신 이러한 컨트롤을 사용하는 것이 좋습니다.

XAML 아일랜드의 아키텍처

WinRT XAML 호스팅 API를 기반으로 다양한 유형의 XAML Island 컨트롤의 아키텍처를 구성하는 방법을 간략히 살펴보겠습니다.

Host control Architecture

이 다이어그램 맨 아래에 표시되는 API는 Windows SDK와 함께 제공됩니다. 래핑된 컨트롤과 호스트 컨트롤은 Windows 커뮤니티 도구 키트의 NuGet 패키지를 통해 사용할 수 있습니다.

제한 사항 및 해결 방법

다음 섹션에서는 XAML Islands를 사용하는 데스크톱 앱의 특정 UWP 개발 시나리오에 대한 제한 사항 및 해결 방법을 설명합니다.

임시 방편으로만 지원

✔️ XAML Island의 WinUI 2 라이브러리의 컨트롤을 호스팅하는 것은 현재 XAML Islands 릴리스에서 조건부로 지원됩니다. 데스크톱 앱이 MSIX 패키지를 배포에 사용하는 경우 Microsoft.UI.Xaml NuGet 패키지의 시험판 또는 릴리스 버전에서 WinUI 컨트롤을 호스팅할 수 있습니다. 데스크톱 앱이 MSIX를 사용하여 패키징되지 않은 경우 Microsoft.UI.Xaml NuGet 패키지의 시험판 버전을 설치한 경우 또는 Dynamic Dependencies API를 사용하는 경우에만 WinUI 컨트롤을 호스트할 수 있습니다. WinUI 3.0 라이브러리의 컨트롤을 호스팅하는 기능은 이후 릴리스에서 지원할 예정입니다.

✔️ XAML Island에서 XAML 콘텐츠 트리의 루트 요소에 액세스하여 루트 요소가 호스팅되는 컨텍스트에 대한 관련 정보를 얻으려면 CoreWindow, ApplicationView 및 Window 클래스를 사용하지 마세요. 그 대신 XamlRoot 클래스를 사용하세요. 자세한 내용은 이 섹션을 참조하세요.

✔️ WPF, Windows Forms 또는 C++ 데스크톱(Win32) 앱에서 공유 계약을 지원하려면 앱에서 IDataTransferManagerInterop 인터페이스를 사용하여 특정 창의 공유 작업을 시작하는 DataTransferManager 개체를 가져와야 합니다. WPF 앱에서 이 인터페이스를 사용하는 방법을 보여주는 샘플은 ShareSource 샘플을 참조하세요.

✔️ XAML Islands에 호스팅된 컨트롤에는 x:Bind을(를) 사용할 수 없습니다. .NET Standard 라이브러리에서 데이터 모델을 선언해야 합니다.

지원되지 않음

 .NET Framework를 대상으로 하는 WPF 및 Windows Forms 앱에서 XAML Islands를 사용합니다. XAML Islands는 .NET Core 3.x를 대상으로 하는 앱에서만 지원됩니다.

 XAML Islands의 UWP XAML 콘텐츠는 런타임에 Windows 테마가 어두운 색에서 밝은 색으로 또는 그 반대로 변경되어도 응답하지 않습니다. 콘텐츠는 런타임에 고대비 변경에 응답합니다.

Windows.UI.Xaml.WebView 컨트롤을 추가합니다. WPF 및 WinForms 앱의 경우 이 대안을 참조하세요.

MediaPlayer 컨트롤 및 MediaPlayerElement 호스트 컨트롤은 전체 화면 모드를 지원하지 않습니다.

 필기 보기를 사용한 텍스트 입력. 이 기능에 대한 자세한 내용은 이 문서를 참조하세요.

@Places 및 @People 콘텐츠 링크를 사용하는 텍스트 컨트롤. 이 기능에 대한 자세한 내용은 이 문서를 참조하세요.

 XAML 아일랜드는 TextBox, RichEditBox 또는 AutoSuggestBox 같은 텍스트 입력을 받는 컨트롤이 포함된 ContentDialog 호스팅을 지원하지 않습니다. 이렇게 하면 입력 컨트롤이 키 누름에 제대로 응답하지 않습니다. XAML 아일랜드를 사용하여 비슷한 기능을 구현하려면 입력 컨트롤이 포함된 Popup을 호스트하는 것이 좋습니다.

 XAML Islands는 현재 호스팅된 Windows.UI.Xaml.Controls.Image 컨트롤 또는 Windows.UI.Xaml.Media.Imaging.SvgImageSource 개체를 사용하여 SVG 파일을 표시하는 것을 지원하지 않습니다. 이 문제를 해결하려면 표시할 이미지 파일을 JPG 또는 PNG와 같은 래스터 기반 형식으로 변환합니다.

XAML 아일랜드에 대한 창 호스트 컨텍스트

데스크톱 앱에서 XAML 아일랜드를 호스팅하는 경우 동일한 스레드에서 여러 개의 XAML 콘텐츠 트리를 동시에 실행할 수 있습니다. XAML 아일랜드에서 XAML 콘텐츠 트리의 루트 요소에 액세스하고 해당 요소가 호스팅되는 컨텍스트에 대한 관련 정보를 가져오려면 XamlRoot 클래스를 사용합니다. CoreWindow, ApplicationView 및 Window 클래스는 XAML 아일랜드에 대한 올바른 정보를 제공하지 않습니다. CoreWindow 및 Window 개체는 스레드에 있으며 앱에서 액세스할 수 있지만, 의미 있는 범위 또는 표시 유형을 반환하지 않습니다(항상 표시되지 않으며, 1x1 크기임). 자세한 내용은 창 작업 호스트를 참조하세요.

예를 들어 XAML Island에서 호스팅되는 WinRT XAML 컨트롤이 포함된 창의 경계 사각형을 가져오려면 컨트롤의 XamlRoot.Size 속성을 사용합니다. XAML Island에서 호스팅할 수 있는 모든 WinRT XAML 컨트롤은 Windows.UI.Xaml.UIElement에서 파생되므로 컨트롤의 XamlRoot 속성을 사용하여 XamlRoot 개체에 액세스할 수 있습니다.

Size windowSize = myUWPControl.XamlRoot.Size;

CoreWindows.Bounds 속성을 사용하여 경계 사각형을 가져오지 않습니다.

// This will return incorrect information for a WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

XAML Islands의 컨텍스트에서 사용하지 않아야 하는 일반적인 창 작업 관련 API 및 추천되는 XamlRoot 대체 항목에 대한 테이블은 이 섹션의 테이블을 참조하세요.

WPF 앱에서 이 인터페이스를 사용하는 방법을 보여주는 샘플은 ShareSource 샘플을 참조하세요.

추가 리소스

XAML Island 사용에 대한 자세한 배경 정보 및 튜토리얼은 다음 문서 및 리소스를 참조하세요.

  • WPF 앱 튜토리얼 현대화: 이 튜토리얼에서는 Windows 커뮤니티 도구 키트의 래핑된 컨트롤과 호스트 컨트롤을 사용하여 기존 WPF LOB(기간 업무) 애플리케이션에 WinRT XAML 컨트롤을 추가하는 방법에 대한 단계별 지침을 제공합니다. 이 튜토리얼에는 WPF 애플리케이션의 전체 코드 및 프로세스의 각 단계에 대한 자세한 지침이 포함되어 있습니다.
  • XAML Islands 코드 샘플: 이 리포지토리에는 XAML Islands 사용 방법을 보여주는 Windows Forms, WPF 및 C++ 데스크톱(Win32) 샘플이 포함되어 있습니다.
  • XAML Islands v1 - 업데이트 및 로드맵: 이 블로그 게시물에서는 XAML Island에 대한 많은 일반적인 질문을 토론하고 자세한 개발 로드맵을 제공합니다.