C#/WinRT

C#/WinRT는 C# 언어에 대한 WinRT(Windows 런타임) 프로젝션 지원을 제공하는 NuGet 패키지 도구 키트입니다. 프로젝션 어셈블리는 대상 언어에 대해 자연스럽고 친숙한 방식으로 WinRT API를 프로그래밍할 수 있는 interop 어셈블리입니다. C#/WinRT 프로젝션은 C# 및 WinRT 인터페이스 간의 interop 세부 정보를 숨기고 문자열, URI, 공통 값 형식 및 제네릭 컬렉션과 같은 적절한 .NET 동등한 항목에 많은 WinRT 형식의 매핑을 제공합니다.

C#/WinRT는 현재 .NET에서 TFM( 대상 프레임워크 모니커 )을 사용하여 WinRT API 사용을 지원합니다. 특정 Windows SDK 버전으로 TFM을 설정하면 C#/WinRT에서 생성된 Windows SDK 프로젝션 및 런타임 어셈블리에 대한 참조가 추가됩니다.

C#/WinRT NuGet 패키지를 사용하면 .NET 소비자를 위한 고유한 WinRT interop 어셈블리를 만들고참조할 수 있습니다. 최신 C#/WinRT 버전에는 C#의 WinRT 형식 작성 미리 보기 도 포함되어 있습니다.

자세한 내용은 C#/WinRT GitHub 리포지토리를 참조하세요.

C#/WinRT에 대한 동기 부여

.NET (이전의 .NET Core)은 디바이스, 클라우드 및 IoT 애플리케이션을 빌드하는 데 사용할 수 있는 오픈 소스 플랫폼 간 런타임입니다.

이전 버전의 .NET Framework 및 .NET Core에는 Windows 관련 기술인 WinRT에 대한 기본 제공 지식이 있었습니다. .NET 6 이상의 이식성 및 효율성 목표를 지원하기 위해 .NET 컴파일러 및 런타임에서 WinRT 프로젝션 지원을 해제하고 C#/WinRT 도구 키트로 이동했습니다( WinRT에 대한 기본 제공 지원은 .NET에서 제거됨 참조). C#/WinRT의 목표는 이전 버전의 C# 컴파일러 및 .NET 런타임에서 제공하는 기본 제공 WinRT 지원과 패리티를 제공하는 것입니다. 자세한 내용은 Windows 런타임 형식의 .NET 매핑을 참조하세요.

C#/WinRT는 WinUI 3을 포함하여 Windows 앱 SDK의 구성 요소도 지원합니다. Windows 앱 SDK는 네이티브 Microsoft UI 컨트롤 및 기타 네이티브 구성 요소를 운영 체제에서 해제합니다. 이를 통해 앱 개발자는 Windows 10 버전 1809 이상 릴리스에서 최신 컨트롤 및 구성 요소를 사용할 수 있습니다.

마지막으로 C#/WinRT는 일반적인 도구 키트이며 C# 컴파일러 또는 .NET 런타임에서 WinRT에 대한 기본 제공 지원을 사용할 수 없는 다른 시나리오를 지원하기 위한 것입니다.

새로운 소식

최신 C#/WinRT 릴리스는 Github 리포지토리의 릴리스 정보 페이지에서 찾을 수 있습니다.

Usage

C#/WinRT NuGet 패키지는 WinRT 구성 요소 및 C#/WinRT 구성 요소 작성에서 C# 프로젝션(interop 어셈블리라고도 함)을 생성하는 데 사용할 수 있습니다. C#/WinRT의 사용 시나리오에 대한 자세한 내용은 리포지토리의 사용 가이드 를 참조하세요.

interop 어셈블리 생성 및 배포

WinRT API는 WinMD(Windows 메타데이터) 파일에 정의됩니다. C#/WinRT NuGet 패키지(Microsoft.Windows.CsWinRT)에는 WinMD 파일을 처리하고 .NET C# 코드를 생성하는 데 사용할 수 있는 C#/WinRT 컴파일러cswinrt.exe포함되어 있습니다. C#/WinRT는 C++/WinRT가 C++ 언어 프로젝션에 대한 헤더를 생성하는 방법과 유사하게 이러한 소스 파일을 interop 어셈블리로 컴파일합니다. 그런 다음 일반적으로 NuGet 패키지로 참조할 .NET 애플리케이션의 구현 어셈블리와 함께 C#/WinRT interop 어셈블리를 배포할 수 있습니다.

interop 어셈블리를 생성하고 배포하는 방법에 대한 자세한 내용은 C++/WinRT 구성 요소에서 C# 프로젝션 생성, .NET 앱용 NuGet으로 배포를 참조하세요.

interop 어셈블리 참조

일반적으로 C#/WinRT interop 어셈블리는 애플리케이션 프로젝트에서 참조됩니다. 그러나 이들은 중간 interop 어셈블리에 의해 다시 참조될 수도 있습니다. 예를 들어 WinUI interop 어셈블리는 Windows SDK interop 어셈블리를 참조합니다.

공식 interop 어셈블리 없이 타사 WinRT 구성 요소를 배포하는 경우 애플리케이션 프로젝트는 자체 프라이빗 프로젝션 원본을 생성하기 위해 interop 어셈블리를 생성하는 절차를 따를 수 있습니다. 프로세스 내에서 동일한 형식의 충돌하는 프로젝션을 생성할 수 있으므로 이 방법은 권장하지 않습니다. NuGet 패키징은 시맨틱 버전 관리 체계에 따라 이를 방지하기 위해 설계되었습니다. 공식 제3자 interop 어셈블리가 선호됩니다.

WinRT 형식에 대한 임베디드 지원(미리 보기)

C#/WinRT 버전 1.4.1부터 .NET 및 .NET Standard 2.0에 대한 Windows SDK 프로젝션 및 런타임 원본을 라이브러리 또는 앱의 출력에 포함하기 위한 지원이 포함됩니다. 이는 Windows SDK 형식의 사용이 자체 포함되는 경우에 유용합니다. 포함된 지원은 라이브러리 또는 앱 출력 크기를 줄이는 WinRT.Runtime.dll 및 Microsoft.Windows.SDK.NET.dll 대한 종속성을 제거합니다. 또한 라이브러리 개발자가 하위 수준 지원을 제공하고 다중 대상 지정의 필요성을 제거할 수 있습니다.

자세한 내용은 리포지토리의 C#/WinRT 포함 설명서를 참조하세요.

WinRT 형식 활성화

C#/WinRT는 운영 체제에서 호스트하는 WinRT 유형뿐만 아니라 Win2D와 같은 타사 구성 요소의 활성화를 지원합니다. Windows 10 버전 1903 이상에서 사용할 수 있는 등록이 필요 없는 WinRT 활성화( Windows 런타임 구성 요소를 사용하여 패키지되지 않은 데스크톱 앱 향상 참조)를 통해 데스크톱 애플리케이션에서 타사 구성 요소의 활성화를 지원합니다. 네이티브 C++ 구성 요소는 Windows 데스크톱 호환 속성을 True로 설정해야 하며, 이는 프로젝트 속성 또는 .vcxproj 파일을 통해 수행하여 Microsoft.VCLibs.Desktop 이진 파일을 소비 앱에 참조하고 전달할 수 있게 합니다. 그렇지 않으면 구성 요소가 UWP 앱만을 대상으로 할 경우, 해당 앱들은 VCRT 전달자 패키지를 필요로 합니다.

또한 C#/WinRT는 Windows가 위에서 설명한 대로 형식을 활성화하지 못하는 경우 활성화 대체 경로를 제공합니다. 이 경우 C#/WinRT는 정규화된 형식 이름을 기반으로 네이티브 구현 DLL을 찾아 요소를 점진적으로 제거합니다. 예를 들어 대체 논리는 다음 모듈에서 Contoso.Controls.Widget 형식을 순서대로 활성화하려고 시도합니다.

1. Contoso.Controls.Widget.dll
2. Contoso.Controls.dll
3. Contoso.dll

C#/WinRT는 LoadLibrary 대체 검색 순서 를 사용하여 구현 DLL을 찾습니다. 이 대체 동작을 사용하는 앱은 앱 모듈과 함께 구현 DLL을 패키지해야 합니다.

일반적인 오류 및 문제 해결

• 오류: "Windows 메타데이터가 제공되지 않거나 검색되지 않았습니다."

  프로젝트 속성을 사용하여 Windows 메타데이터를 <CsWinRTWindowsMetadata> 지정할 수 있습니다. 예를 들면 다음과 같습니다.

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  C#/WinRT 버전 1.2.1 이상에서 이 속성은 기본적으로 TargetPlatformVersion속성에 지정된 Windows SDK 버전에서 TargetFramework 파생됩니다.

• 오류 CS0246: 형식 또는 네임스페이스 이름 'Windows'를 찾을 수 없습니다(using 지시문 또는 어셈블리 참조가 누락되었나요?)

  이 오류를 해결하려면 속성을 편집 <TargetFramework> 하여 특정 Windows 버전을 대상으로 지정합니다. 예를 들면 다음과 같습니다.

  <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
  

  속성 지정 에 대한 자세한 내용은 <TargetFramework>에 대한 문서를 참조하세요.

• 인터페이스가 특성을 가지고 있을 때 System.InvalidCastException 예외가 발생합니다.

  개체를 ComImport 특성이 있는 인터페이스로 캐스팅할 때, 명시적인 .As<> 대신 연산자를 사용해야 합니다. 다음은 그 예입니다.

  someObject.As<SomeComImportInterface>
  

  자세한 내용은 COM interop 가이드를 참조하세요.

• System.Runtime.InteropServices.COMException: 등록되지 않은 클래스(0x80040154(REGDB_E_CLASSNOTREG))

  • C++/WinRT 구성 요소에서 C#/WinRT 프로젝션을 사용할 때 이 예외가 표시되는 경우 구성 요소가 프로젝트 속성을 통해 또는 파일을 통해 Windows 데스크톱 호환 속성을 .vcxproj로 설정했는지 확인합니다.

.NET SDK 버전 관리 오류

종속성보다 이전 .NET SDK 버전으로 빌드된 프로젝트에서 다음과 같은 오류 또는 경고가 발생할 수 있습니다.

오류 또는 경고 메시지	이유
경고 MSB3277: 해결할 수 없는 여러 버전의 WinRT.Runtime 또는 Microsoft.Windows.SDK.NET 간에 충돌이 발생했습니다.	이 빌드 경고는 해당 API 화면에 Windows SDK 형식을 노출하는 라이브러리를 참조할 때 발생합니다.
오류 CS1705: 어셈블리 'AssemblyName1'은 참조된 어셈블리 'AssemblyName2'보다 버전이 높은 'TypeName'을 사용합니다.	이 빌드 컴파일러 오류는 라이브러리에서 노출된 Windows SDK 형식을 참조하고 사용할 때 발생합니다.
System.IO.FileLoadException	이 런타임 오류는 Windows SDK 형식을 노출하지 않는 라이브러리에서 특정 API를 호출할 때 발생할 수 있습니다.

이러한 오류를 해결하려면 .NET SDK를 최신 버전으로 업데이트합니다. 이렇게 하면 애플리케이션에서 사용하는 런타임 및 Windows SDK 어셈블리 버전이 모든 종속성과 호환됩니다. 런타임 수정 시 어셈블리 버전에 대한 업데이트가 필요할 수 있으므로 .NET SDK에 대한 초기 서비스/기능 업데이트에서 이러한 오류가 발생할 수 있습니다.

알려진 문제

알려진 문제 및 호환성이 손상되는 변경 내용은 C#/WinRT GitHub 리포지토리에 나와 있습니다.

C#/WinRT NuGet 패키지, cswinrt.exe 컴파일러 또는 생성된 프로젝션 원본에 대한 기능 문제가 발생하는 경우 C#/WinRT 문제 페이지를 통해 문제를 제출합니다.

추가 리소스

• C#/WinRT GitHub 리포지토리