다음을 통해 공유

개요 및 릴리스 정보: WinUI 3 - 프로젝트 리유니언 0.8 미리 보기(2021년 5월)

  • 아티클

WinUI 3는 최신 Windows 앱 구축을 위한 기본 UX(사용자 환경) 프레임워크입니다. 이는 Windows 운영 체제와 별개로 프로젝트 리유니언(현재는 Windows 앱 SDK라고 함)의 일부로 제공됩니다. 0.8 미리 보기 릴리스는 WinUI 3 기반 사용자 인터페이스로 앱 빌드를 시작하는 데 도움이 되는 Visual Studio의 WinUI 3 템플릿을 제공합니다.

WinUI 3 - 프로젝트 리유니언 0.8 미리 보기는 버그 수정, 일반적인 개선 사항 및 실험적 기능을 포함하는 WinUI 3의 시험판 버전입니다. 일부는 2021년 6월에 Windows 앱 SDK 0.8 안정적인 릴리스에 대해 안정화될 예정입니다.

Important

이 미리 보기 릴리스는 개발자 커뮤니티에서 초기에 평가하고 피드백을 수집하기 위한 것입니다. 프로덕션 앱에는 사용하면 안 됩니다.

프로젝트 리유니언 및 WinUI 3을 사용하여 프로덕션 앱을 배송하려는 경우 개요 및 릴리스 정보: WinUI 3 - 프로젝트 리유니언 0.5를 참조하세요.

WinUI GitHub 리포지토리를 사용하여 피드백을 제공하고 제안 사항과 문제를 기록해 주세요.

참고 항목

프로젝트 리유니언은 Windows 앱 SDK의 이전 코드 이름입니다. 이 문서에서는 이 코드 이름을 사용한 이전 릴리스를 언급할 때 프로젝트 리유니언을 계속 사용합니다.

WinUI 3 - 프로젝트 리유니언 0.8 미리 보기 설치

이 버전의 WinUI 3은 프로젝트 리유니언 0.8 미리 보기의 일부로 제공됩니다. 설치하려면 다음을 참조하세요.

Windows 앱 SDK의 미리 보기 및 실험 채널용 도구 설치

이제 WinUI가 프로젝트 리유니언의 일부로 제공되므로, 개발자 도구 및 구성 요소 세트를 포함하는 프로젝트 리유니언 VSIX(Visual Studio Extension)를 다운로드하여 시작할 수 있습니다. Project Reunion 패키지에 대한 자세한 내용은 Windows 앱 SDK를 사용하는 앱 배포를 참조하세요. Windows 앱 SDK VSIX에는 WinUI 3 앱을 빌드하는 데 사용되는 Visual Studio의 WinUI 3 템플릿이 포함되어 있습니다.

참고 항목

WinUI 3 컨트롤 및 기능의 작동 모습을 확인하려면 GitHub에서 WinUI 3 Controls Gallery를 복제하고 빌드하거나 Microsoft Store에서 다운로드할 수 있습니다.

개발 환경을 설정한 후 Visual Studio의 WinUI 3 템플릿을 참조하여 사용 가능한 Visual Studio 프로젝트 및 항목 템플릿을 숙지합니다.

WinUI 3 앱의 빌드를 시작하는 방법에 대한 자세한 내용은 다음 문서를 참조하세요.

제한 사항 및 알려진 문제 외에도 WinUI 프로젝트를 사용하여 앱을 빌드하는 것은 XAML 및 WinUI 2를 사용하여 UWP 앱을 빌드하는 것과 비슷합니다. 따라서 UWP 앱 및 Windows SDK의 Windows.UI WinRT 네임스페이스에 대한 대부분의 지침 설명서를 적용할 수 있습니다.

WinUI 3 API 참조 설명서는 WinUI 3 API 참조에서 찾을 수 있습니다.

Webview2

이 WinUI 3 릴리스에서 WebView2를 사용하고 싶은데 WebView2 런타임이 아직 설치되지 않은 경우 이 페이지에서 제공하는 Evergreen Bootstrapper 또는 Evergreen Standalone Installer를 다운로드하세요.

Windows 커뮤니티 도구 키트

Windows 커뮤니티 도구 키트를 사용하는 경우 최신 버전을 다운로드합니다.

Visual Studio 지원

Hot Reload, Live Visual Tree 및 Live Property Explorer와 같은 WinUI 3에 추가된 최신 도구 기능을 활용하려면 Visual Studio 2019 16.10의 미리 보기 버전을 사용해야 합니다. Visual Studio 미리 보기 릴리스는 시험판 제품이므로 Visual Studio의 미리 보기 버전을 사용하여 WinUI 3 앱을 빌드할 때 버그 및 제한 사항이 발생할 수 있습니다.

아래 표에서는 WinUI 3 - 프로젝트 리유니언 0.5와 Visual Studio 2019 버전의 호환성을 보여줍니다.

VS 버전 WinUI 3 - 프로젝트 리유니언 0.5
16.8 없음
16.9 예(하지만 핫 다시 로드, 라이브 시각적 트리 또는 라이브 속성 탐색기와는 호환 안 됨)
16.10 Preview 네, WinUI 3 도구를 모두 사용합니다(미리 보기에서).

기존 WinUI 3 앱 업데이트

WinUI 3의 이전 미리 보기 또는 안정적인 버전을 사용하여 앱을 만든 경우 WinUI 3 - 프로젝트 리유니언 0.8 미리 보기를 사용하도록 프로젝트를 업데이트할 수 있습니다. 자세한 내용은 기존 프로젝트를 최신 프로젝트 리유니언 릴리스로 업데이트를 참조하세요.

이 릴리스의 주요 변경 내용

  • 이제 이 릴리스에서 피벗 컨트롤을 사용할 수 있습니다.
  • 프로젝트 리유니언 v0.5.5, v0.5.6 및 v0.5.7 서비스 릴리스의 중요한 버그 수정 사항은 대부분 이 릴리스에 포함되어 있습니다. 이 미리 보기에 포함되지 않은 서비스 수정 사항은 알려진 문제를 참조하세요.

WinUI 3 - 프로젝트 리유니언 0.8 미리 보기에서 수정된 버그 목록

  • x:Bind는 사용자 지정 MenuFlyoutItem에서 작동하지 않습니다. 즉, 부모 이름 범위가 x:Bind를 사용하는 경우에는 일반적으로 ControlTemplate의 x:Bind가 작동하지 않습니다.

  • 최상위 창(또는 아일랜드)이 이동하는 경우 창 팝업 숨기기

  • WinUI 3 Controls Gallery의 StandardUICommand 페이지에서 모든 항목을 표시하지 않음

  • TextBox에서 마우스 오른쪽 단추로 클릭하면 애플리케이션이 충돌함

  • 바로 가기 메뉴가 EditableComboBox에 대해 잘못된 위치에 표시됨

  • 터치 시 RichTextBlock 선택을 변경하면 선택 표시기가 사라짐

  • Microsoft C++ 예외: NavigationView를 사용하는 경우 메모리 위치 0x에 winrt::hresult_error 발생

  • 수정이 필요한 WinUI 3 오류 메시지: "'Windows.metadata'를 확인할 수 없습니다. Windows 소프트웨어 개발 키트를 설치하세요. Windows SDK는 Visual Studio와 함께 설치됩니다."

  • 예외 발생에 대한 VSM Setter 쿼크에 역방향 논리가 있음

    • GitHub에서 이 문제를 해결해 @HppZ 주셔서 감사합니다!

  • 브라우저 프로세스가 충돌하는 경우 WebView2(필요한 경우)에서 포커스가 이동함

  • ProgressBar가 일시 중지됨 옵션과 오류 옵션에서 차이가 없음

  • PointerReplay가 지속적으로 실행됨

  • NavigationView로 인해 UWP, 리유니언 0.5 미리 보기에서 충돌이 발생함

  • AutoSuggestBox, ComboBox 및 CommandBarFlyout이 해당 팝업에서 ShouldConstrainToRootBounds="false" 설정 안 됨

  • WinUI 3 - 프로젝트 리유니언 0.5로 인해 C# 관리형 앱에 대한 C++ 예외 생성

  • WebView2 초기 탭 포커스 손실

  • Close() 후 DPI가 변경될 때 WebView2가 충돌함

  • WinUI3의 CommandBar에서 플라이아웃을 사용하여 AppBarButton의 모양이 변경됨

이전의 WinUI 3 미리 보기에 도입된 새로운 특징 및 기능

다음 특징 및 기능은 과거 WinUI 3 미리 보기 릴리스에서 도입된 것들이며, WinUI 3 - 프로젝트 리유니언 0.8 미리 보기에서도 계속 지원됩니다.

참고 항목

다음 기능 중 일부는 계속해서 WinUI 3 미리 보기에 포함되어 제공되지만, 다음 지원 릴리스에 포함되지 않을 수도 있습니다. 이러한 기능은 실험적으로 표시되며 앱에서 사용될 때 경고를 throw합니다. 또한 WinUI 2.6 시험판에 포함된 API는 이 릴리스에서 실험적으로 표시되어 있습니다.

  • Win32 앱용 .NET을 포함하여 WinUI에서 데스크톱 앱을 만드는 기능
  • UWP 앱 빌드를 위한 미리 보기 수준 지원
  • RadialGradientBrush
  • TabView 업데이트
  • 어두운 테마 업데이트
  • WebView2의 향상된 기능 및 업데이트
    • 높은 DPI 지원
    • 창 크기 조정 및 이동 지원
    • 최신 버전의 Edge를 대상으로 업데이트됨
    • 더 이상 WebView2별 Nuget 패키지를 참조할 필요 없음
  • SwapChainPanel
  • MRT 핵심 지원
    • 이를 통해 시작 시 앱이 더 빠르고 가벼워지며, 리소스 조회가 더 빨라집니다.
  • Arm64 지원
  • 앱 내부 및 외부에서 끌어서 놓기
  • RenderTargetBitmap(현재 XAML 콘텐츠만 - SwapChainPanel 콘텐츠 없음)
  • 사용자 지정 커서 지원
  • 오프 스레드 입력
  • 향상된 도구/개발자 환경 기능:
    • 라이브 시각적 트리, 핫 다시 로드, 라이브 속성 탐색기 및 이와 비슷한 도구
    • WinUI 3 용 Intellisense
  • 오픈 소스 마이그레이션에 필요한 향상된 기능
  • 사용자 지정 제목 표시줄 기능: 개발자가 데스크톱 앱에서 사용자 지정 제목 표시줄을 만들 수 있는 새로운 Window.ExtendsContentIntoTitleBar 및 Window.SetTitleBar API
  • VirtualSurfaceImageSource 지원
  • 인앱 아크릴
  • 데스크톱 앱의 다중 창 지원
  • 입력 유효성 검사

피드백 및 제안 제공

WinUI GitHub 리포지토리에 대한 피드백을 환영합니다.

제한 사항 및 알려진 문제

WinUI 3 - 프로젝트 리유니언 0.8 미리 보기는 미리 보기일 뿐입니다. 버그, 제한 사항 및 기타 문제가 발생할 수도 있습니다.

WinUI 3 - 프로젝트 리유니언 0.8의 알려진 문제는 다음과 같습니다. 아래에 나열되지 않은 문제가 발견되면 WinUI GitHub 리포지토리를 통해 기존 문제에 참여하거나 새 문제를 제출하여 알려주세요.

플랫폼 및 OS 지원

WinUI 3 - 프로젝트 리유니언 0.8 미리 보기는 Windows 10 2018년 10월 업데이트(버전 1809 - 빌드 17763) 이상을 실행하는 PC와 호환됩니다.

개발자 도구

  • C# 및 C++/WinRT 앱만 지원됩니다.
  • 데스크톱 앱은 .NET 6 이상 및 C# 9를 지원하며 MSIX 앱에 패키지해야 합니다.
  • XAML 디자이너가 지원되지 않습니다.
  • 새 C++/CX 앱은 지원되지 않지만, 기존 앱은 계속 작동합니다(가능한 한 빨리 C++/WinRT로 이동).
  • 패키지되지 않은 데스크톱 배포는 지원되지 않습니다.
  • F5 키를 사용하여 데스크톱 앱을 실행하는 경우 패키징 프로젝트를 실행하고 있는지 확인합니다. 앱 프로젝트에서 F5 키를 누르면 WinUI 3에서 아직 지원하지 않는 패키지되지 않은 앱이 실행됩니다.

누락된 플랫폼 기능

  • Xbox 지원

  • HoloLens 지원

  • 창 팝업

    • 구체적으로 ShouldConstrainToRootBounds 속성은 속성 값에 관계없이 항상 true로 설정된 것처럼 작동합니다.

  • 다음을 포함한 수동 입력 지원:

  • 배경 아크릴

  • MediaElement 및 MediaPlayerElement

  • MapControl

  • SwapChainPanel은 투명성을 지원하지 않습니다.

  • CompositionBackdropBrush를 사용하는 AcrylicBrush 및 기타 효과는 SwapChainPanel 또는 WebView2에서 샘플링할 수 없습니다.

  • 글로벌 표시는 솔리드 브러시인 폴백 동작을 사용합니다.

  • XAML Islands는 이 릴리스에서 지원되지 않습니다.

  • 기존의 비 WinUI 데스크톱 앱에서 직접 WinUI 3을 사용하는 경우 다음과 같은 제한 사항이 있습니다. 기존 앱을 마이그레이션할 때 현재 사용할 수 있는 경로는 새 WinUI 3 프로젝트를 솔루션에 추가하고 필요에 따라 논리를 조정하거나 리팩터링하는 것입니다.

  • Application.Suspending은 데스크톱 앱에서 호출되지 않습니다. 자세한 내용은 Application.Suspending Event에 대한 API 참조 설명서를 확인하세요.

  • UISettings.ColorValuesChanged 이벤트 및 AccessibilitySettings.HighContrastChanged 이벤트는 더 이상 데스크톱 앱에서 지원되지 않습니다. Windows 테마의 변경 사항을 감지하는 데 사용하는 경우 문제가 발생할 수 있습니다.

  • 이전에는 CompositionCapabilities 인스턴스를 가져오려면 CompositionCapabilites.GetForCurrentView()를 호출했습니다. 그러나 이 호출에서 반환된 기능은 보기에 종속되지 않았습니다. 이 문제를 해결하고 반영하기 위해 이번 릴리스에서 GetForCurrentView() static을 삭제했으므로 이제 CompositionCapabilties 객체를 직접 만들 수 있습니다.

  • CoreWindow, ApplicationView, CoreApplicationView, CoreDispatcher 및 해당 종속성은 데스크톱 앱에서 지원되지 않습니다(아래 참조).

데스크톱 앱의 CoreWindow, ApplicationView, CoreApplicationView 및 CoreDispatcher

WinUI 3 미리 보기 4 버전과 이후 표준 버전의 새 기능, CoreWindow, ApplicationView, CoreApplicationView CoreDispatcher 및 해당 종속성은 데스크톱 앱에서 사용할 수 없습니다. 예를 들어 Window.Dispatcher 속성은 항상 null이지만 Window.DispatcherQueue 속성을 대안으로 사용할 수 있습니다.

이러한 API는 UWP 앱에서만 작동합니다. 과거 미리 보기에서는 데스크톱 앱에서도 부분적으로 작동했지만 미리 보기 4부터는 완전히 사용하지 않도록 설정되었습니다. 이러한 API는 스레드당 창이 하나만 있고 WinUI 3의 기능 중 하나가 향후 여러 개를 사용할 수 있는 UWP 사례를 위해 설계되었습니다.

이러한 API의 존재 여부에 내부적으로 의존하는 API가 있으므로 결과적으로 데스크톱 앱에서 지원되지 않습니다. 이러한 API에는 일반적으로 정적 GetForCurrentView 메서드가 있습니다. 예를 들어 UIViewSettings.GetForCurrentView가 있습니다.

영향을 받는 API와 이러한 API의 해결 방법 및 대안에 대한 자세한 내용은 데스크톱 앱에서 지원되지 않는 Windows 런타임 API를 참조하세요.

알려진 문제

  • .NET SDK 및 winrt.runtime.dll의 버전이 일치하지 않아 빌드 오류가 발생할 수 있습니다. 해결 방법으로 다음을 시도할 수 있습니다.

    명시적으로 .NET SDK를 올바른 버전으로 설정합니다. 앱의 올바른 버전을 확인하려면 프로젝트 파일에서 <TargetFramework> 태그를 찾습니다. 앱이 <TargetFramework> 태그에서 대상으로 하는 Windows SDK 빌드 번호(예: 18362 또는 19041)를 사용하여 다음 항목을 프로젝트 파일에 추가한 다음, 프로젝트를 저장합니다.

    <ItemGroup>            
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.{Target Windows SDK Build Number}.16" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.{Target Windows SDK Build Number}.16" />
</ItemGroup>

    이 해결 방법은 .NET SDK 5.0.203 및 이전 버전에 필요하지만 .NET SDK 5.0.204 또는 5.0.300에는 필요하지 않습니다.

  • Visual Studio 2019 16.10 Preview 2를 사용할 때 Live Visual Tree에서 충돌이 발생할 수 있습니다. 이를 방지하려면 최신 Visual Studio 2019 16.10 미리 보기로 업데이트하세요.

  • SetTitleBar가 설정되지 않았거나 null인 경우 창 캡션 단추의 위치가 잘못될 수 있음

WinUI 3 - 프로젝트 리유니언 0.8 미리 보기에서 제공하는 모든 컨트롤과 기능이 들어있는 샘플 앱은 WinUI 3 Controls Gallery(이전 명칭: XAML Controls Gallery - WinUI 3 버전)를 확인하세요.

WinUI 3 Controls Gallery 앱
WinUI 3 Controls Gallery 앱의 예

WinUI 3 Controls Gallery 앱은 Microsoft Store를 통해 사용할 수 있습니다.

또한 GitHub 리포지토리를 복제하여 샘플을 다운로드할 수 있습니다. 이렇게 하려면 다음 명령을 사용하여 winui3 분기를 복제합니다.

참고 항목

또한 이 GitHub 리포지토리에는 WinUI 3 - 프로젝트 리유니언 0.8 미리 보기를 사용하는 WinUI 3 Controls Gallery의 버전을 제공하는 winui3preview 분기가 있습니다.

git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git

복제 후, 로컬 Git 환경에서 winui3 분기로 전환해야 합니다.

git checkout winui3

참고 항목