연습 - WinUI 3 컨트롤을 사용하여 C# 구성 요소를 만들고 Windows 앱 SDK를 사용하는 C++/WinRT 앱에서 사용

아티클
04/20/2023

C#/WinRT는 WinUI 사용자 지정 형식 및 사용자 지정 컨트롤을 포함하여 Windows 런타임 구성 요소 작성을 지원합니다. 이러한 구성 요소는 Windows 앱 SDK를 사용하는 C# 또는 C++/WinRT 애플리케이션에서 사용할 수 있습니다. NuGet 패키지 지원으로 런타임 구성 요소를 작성하려면 C#/WinRT v1.6.4 이상을 사용하는 것이 좋습니다.

지원되는 시나리오에 대한 자세한 내용은 C#/WinRT GitHub 리포지토리에서 C#/WinRT 구성 요소 작성을 참조하세요.

이 연습에서는 사용자 지정 WinUI 3 컨트롤을 사용하여 C# 구성 요소를 작성하는 방법과 Windows 앱 SDK 프로젝트 템플릿을 사용하여 C++/WinRT 앱에서 해당 구성 요소를 사용하는 방법을 보여 줍니다.

전제 조건

이 연습에는 다음 도구와 구성 요소가 필요합니다.

Windows 앱 SDK를 사용하여 C#/WinRT 구성 요소 작성

Windows 앱 SDK에서 제공하는 클래스 라이브러리(데스크톱의 WinUI 3) 템플릿을 사용하여 새 C# 라이브러리 프로젝트를 만듭니다. 이 연습에서는 라이브러리 프로젝트의 이름을 WinUIComponentCs로 지정하고 솔루션 이름을 AuthoringWinUI로 지정했습니다.

같은 디렉터리에 솔루션 및 프로젝트 배치 확인란을 선택하지 않은 상태로 둡니다. 그렇지 않으면 이전 섹션의 C++ 애플리케이션에 대한 packages 폴더가 결국 C# 라이브러리 프로젝트를 방해하게 됩니다.
기본적으로 포함된 Class1.cs 파일을 삭제합니다.
프로젝트에 최신 Microsoft.Windows.CsWinRT NuGet 패키지를 설치합니다.

i. 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리를 선택합니다.

ii. Microsoft.Windows.CsWinRT 패키지를 검색하고 최신 버전을 설치합니다.
라이브러리 프로젝트에 다음 속성을 추가합니다.
```
<PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
```
- CsWinRTComponent 속성은 프로젝트가 Windows 런타임 구성 요소임을 지정하므로 프로젝트를 빌드할 때 .winmd 파일이 생성됩니다.
라이브러리에 사용자 지정 컨트롤 또는 사용자 정의 컨트롤을 추가합니다. 이렇게 하려면 Visual Studio에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 추가>새 항목을 클릭한 다음 왼쪽 창에서 WinUI를 선택합니다. 이 연습에서는 새 사용자 정의 컨트롤(WinUI 3)을 추가하고 이름을 NameReporter.xaml로 지정했습니다. NameReporter 사용자 정의 컨트롤을 사용하면 사용자가 이름과 성을 적절한 TextBox 컨트롤에 입력하고 단추를 클릭할 수 있습니다. 그러면 컨트롤에 사용자가 입력한 이름의 메시지 상자가 표시됩니다.

다음 코드를 NameReporter.xaml 파일에 붙여넣습니다.

<UserControl
x:Class="WinUIComponentCs.NameReporter"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:WinUIComponentCs"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">

    <StackPanel HorizontalAlignment="Center">
        <StackPanel.Resources>
            <Style x:Key="BasicTextStyle" TargetType="TextBlock" BasedOn="{StaticResource BodyTextBlockStyle}">
                <Setter Property="Margin" Value="10,10,10,10"/>
            </Style>
        </StackPanel.Resources>

        <TextBlock Text="Enter your name." Margin="0,0,0,10"/>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                First Name:
            </TextBlock>
            <TextBox Name="firstName" />
        </StackPanel>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                Last Name:
            </TextBlock>
            <TextBox Name="lastName" />
        </StackPanel>
        <Button Content="Submit" Click="Button_Click" Margin="0,0,0,10"/>
        <TextBlock Name="result" Style="{StaticResource BasicTextStyle}" Margin="0,0,0,10"/>
    </StackPanel>
</UserControl>

NameReporter.xaml.cs에 다음 메서드를 추가합니다.

using System.Text;
...
private void Button_Click(object sender, RoutedEventArgs e)
{
    StringBuilder displayText = new StringBuilder("Hello, ");
    displayText.AppendFormat("{0} {1}.", firstName.Text, lastName.Text);
    result.Text = displayText.ToString();
}

이제 WinUIComponentCs 프로젝트를 빌드하여 구성 요소에 대한 .winmd 파일을 생성할 수 있습니다.

참고 항목

최종 앱 소비자가 참조할 수 있도록 구성 요소를 NuGet 패키지로 패키지할 수도 있습니다. 자세한 내용은 C#/WinRT Github 리포지토리에서 C#/WinRT 구성 요소 작성을 참조하세요.

Windows 앱 SDK C++/WinRT 앱에서 구성 요소 참조

다음 단계에서는 C++/WinRT Windows 앱 SDK 애플리케이션의 이전 섹션에서 만든 구성 요소를 사용하는 방법을 보여 줍니다. C++에서 C#/WinRT 구성 요소를 사용하려면 현재 단일 프로젝트 빈 앱, 패키지(데스크톱의 WinUI 3) 템플릿을 사용해야 합니다. C# 구성 요소는 클래스 등록 없이 C# 패키지 앱에서도 참조할 수 있습니다.

별도의 WAP(Windows 애플리케이션 패키지) 프로젝트를 사용하는 패키지 앱의 사용량은 현재 지원되지 않습니다. 지원되는 프로젝트 구성에 대한 최신 업데이트는 C#/WinRT GitHub 리포지토리에서 C#/WinRT 구성 요소 작성을 참조하세요.

솔루션에 새 C++ Windows 앱 SDK 애플리케이션 프로젝트를 추가합니다. Visual Studio에서 솔루션을 마우스 오른쪽 단추로 클릭하고 추가>새 프로젝트를 선택합니다. Windows 앱 SDK에서 제공하는 C++ 빈 앱, 패키지(데스크톱의 WinUI 3) 템플릿을 선택합니다. 이 연습에서는 앱 이름을 CppApp으로 지정했습니다.
C++ 앱의 프로젝트 참조를 C# 구성 요소에 추가합니다. Visual Studio에서 C++ 프로젝트를 마우스 오른쪽 단추로 클릭하고 추가>참조를 선택한 다음 WinUIComponentCs 프로젝트를 선택합니다.

참고 항목

구성 요소를 NuGet 패키지 참조로 사용하는 것은 몇 가지 제한 사항과 함께 지원됩니다. 즉, 사용자 지정 사용자 정의 컨트롤이 있는 구성 요소는 현재 NuGet 패키지 참조로 사용할 수 없습니다.

앱의 pch.h 헤더 파일에 다음 줄을 추가합니다.

#include <winrt/WinUIComponentCs.h>
#include <winrt/WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.h>

패키지 매니페스트 파일 Package.appxmanifest를 엽니다.

참고 항목

Visual Studio 솔루션 탐색기에 Package.appxmanifest 파일이 표시되지 않는 알려진 문제가 있습니다. 이 문제를 해결하려면 C++ 프로젝트를 마우스 오른쪽 단추로 클릭하고 프로젝트 언로드를 선택한 다음 프로젝트를 두 번 클릭하여 CppApp.vcxproj 파일을 엽니다. 프로젝트 파일에 다음 항목을 추가하고 프로젝트를 다시 로드합니다.
```
<ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
    <SubType>Designer</SubType>
    </AppxManifest>
</ItemGroup>
```
Package.appxmanifest에서 다음 활성화 가능한 클래스 등록을 추가합니다. 또한 WinUI 형식을 활성화하려면 WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider 클래스에 대해 추가 ActivatableClass 항목이 필요합니다. 파일을 편집하려면 Package.appxmanifest 파일을 마우스 오른쪽 단추로 클릭하고 연결 프로그램>XML(텍스트 편집기)을 선택합니다.
```

<Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
        <InProcessServer>
            <Path>WinRT.Host.dll</Path>
            <ActivatableClass ActivatableClassId="WinUIComponentCs.NameReporter" ThreadingModel="both" />
            <ActivatableClass ActivatableClassId="WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider" ThreadingModel="both" />
        </InProcessServer>
    </Extension>
</Extensions>
```
MainWindow.xaml 파일을 엽니다.

i. 파일 맨 위에 구성 요소의 네임스페이스에 대한 참조를 추가합니다.
```
xmlns:custom="using:WinUIComponentCs"
```
ii. 기존 XAML 코드에 사용자 정의 컨트롤을 추가합니다.
```
<StackPanel>
    ...
    <custom:NameReporter/>
</StackPanel>
```
CppApp을 시작 프로젝트로 설정하고, CppApp을 마우스 오른쪽 단추로 클릭하고, 시작 프로젝트로 설정을 선택합니다. 솔루션 구성을 x86으로 설정합니다. 빌드하기 전에 Visual Studio 2022 빌드 도구를 사용하여 빌드하도록 솔루션의 대상을 다시 지정해야 할 수도 있습니다. 솔루션을 마우스 오른쪽 단추로 클릭하고, Retarget 솔루션을 선택한 다음 Platform Toolset을 v143으로 업그레이드합니다.
앱을 빌드하고 실행하여 사용자 지정 NameReporter 컨트롤을 확인합니다.

알려진 문제점

C# 구성 요소를 프로젝트 참조로 사용하려면 PublishReadyToRun을 False로 설정해야 합니다. 자세한 내용은 Github Issue #1151을 참조하세요.
C++에서 AnyCPU를 위해 빌드된 C# 구성 요소를 사용하는 것은 현재 x86 애플리케이션에서만 지원됩니다. x64 및 Arm64 앱에서 다음과 유사한 런타임 오류가 발생합니다. %1은 유효한 Win32 애플리케이션이 아닙니다. 자세한 내용은 Github 문제 #1151을 참조하세요.

Share via

연습 - WinUI 3 컨트롤을 사용하여 C# 구성 요소를 만들고 Windows 앱 SDK를 사용하는 C++/WinRT 앱에서 사용

전제 조건

Windows 앱 SDK를 사용하여 C#/WinRT 구성 요소 작성

Windows 앱 SDK C++/WinRT 앱에서 구성 요소 참조

알려진 문제점

피드백

추가 리소스

Share via

연습 - WinUI 3 컨트롤을 사용하여 C# 구성 요소를 만들고 Windows 앱 SDK를 사용하는 C++/WinRT 앱에서 사용

전제 조건

Windows 앱 SDK를 사용하여 C#/WinRT 구성 요소 작성

Windows 앱 SDK C++/WinRT 앱에서 구성 요소 참조

알려진 문제점

관련 항목

피드백

추가 리소스