C#/WinRT는 C# 언어에 대한 winRT(Windows Runtime) 프로젝션 지원을 제공하는 NuGet 패키지 도구 키트입니다. 프로젝션 어셈블리는 대상 언어에 대해 자연스럽고 친숙한 방식으로 WinRT API를 프로그래밍할 수 있는 interop 어셈블리입니다. C#/WinRT 프로젝션은 C#과 WinRT 인터페이스 간의 상호 운용성 세부 사항을 숨기고, 문자열, URI, 일반 값 형식, 제네릭 컬렉션 등 여러 WinRT 형식을 적절한 .NET 대응 항목으로 매핑합니다.
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 Runtime 형식의 .NET 매핑 참조하세요.
C#/WinRT는 WinUI 3을 포함하여 Windows App SDK 구성 요소도 지원합니다. Windows App SDK 네이티브 Microsoft UI 컨트롤 및 기타 네이티브 구성 요소를 운영 체제에서 해제합니다. 이를 통해 앱 개발자는 Windows 10 버전 1809 이상 릴리스에서 최신 컨트롤 및 구성 요소를 사용할 수 있습니다.
마지막으로 C#/WinRT는 일반적인 도구 키트이며, C# 컴파일러 또는 .NET 런타임에서 WinRT에 대한 기본 제공 지원을 사용할 수 없는 다른 시나리오를 지원하기 위한 것입니다.
새로운 소식
최신 C#/WinRT 릴리스는 Github 리포지토리의 릴리스 정보 페이지에서 찾을 수 있습니다.
Usage
C#/WinRT NuGet 패키지는 C# 프로젝션(interop 어셈블리라고도 함)을 WinRT 구성 요소에서 생성하거나, C#/WinRT 구성 요소를 작성하는 데 사용할 수 있습니다. C#/WinRT의 사용 시나리오에 대한 자세한 내용은 리포지토리의 usage 가이드 참조하세요.
interop 어셈블리 생성 및 배포
WinRT API는 WinMD(Windows 메타데이터) 파일에 정의됩니다. C#/WinRT NuGet 패키지(Microsoft.Windows.CsWinRT)에는 WinMD 파일을 처리하고 .NET C# 코드를 생성하는 데 사용할 수 있는 C#/WinRT 컴파일러 cswinrt.exe 포함됩니다. C#/WinRT는 C++/WinRT가 C++ 언어 프로젝션에 대한 헤더를 생성하는 방법과 유사하게 이러한 소스 파일을 interop 어셈블리로 컴파일합니다. 그런 다음, 참조할 .NET 애플리케이션의 구현 어셈블리와 함께 C#/WinRT interop 어셈블리를 배포할 수 있습니다(일반적으로 NuGet 패키지).
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 Runtime 구성 요소를 사용하여 패키지되지 않은 데스크톱 앱 개선 참조)를 통해 데스크톱 애플리케이션에서 타사 구성 요소의 활성화가 가능해집니다. 네이티브 C++ 구성 요소는 프로젝트 속성이나 .vcxproj 파일을 통해 Windows Desktop Compatible 속성을 True로 설정해야 하며, 이는 Microsoft.VCLibs.Desktop 바이너리를 참조하고 소비 앱으로 전달하기 위함입니다. 그렇지 않으면 구성 요소가 UWP 앱만을 대상으로 할 경우, 해당 앱들은 VCRT 전달자 패키지를 필요로 합니다.
또한 C#/WinRT는 Windows가 위에서 설명한 대로 형식을 활성화하지 못하는 경우 활성화 대체 경로를 제공합니다. 이 경우 C#/WinRT는 정규화된 형식 이름을 기반으로 네이티브 구현 DLL을 찾아 요소를 점진적으로 제거합니다. 예를 들어 대체 논리는 다음 모듈에서 Contoso.Controls.Widget 형식을 순서대로 활성화하려고 시도합니다.
- Contoso.Controls.Widget.dll
- Contoso.Controls.dll
- Contoso.dll
C#/WinRT는 LoadLibrary 대체 검색 순서 를 사용하여 구현 DLL을 찾습니다. 이 대체 동작을 사용하는 앱은 앱 모듈과 함께 구현 DLL을 패키지해야 합니다.
일반적인 오류 및 문제 해결
오류: "Windows 메타데이터가 제공되지 않거나 검색되지 않았습니다."
예를 들어
<CsWinRTWindowsMetadata>project 속성을 사용하여 Windows 메타데이터를 지정할 수 있습니다.<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>인터페이스가 특성을 가지고 있을 때 System.InvalidCastException 예외가 발생합니다.
개체를
ComImport특성이 있는 인터페이스로 캐스팅할 때, 명시적인.As<>대신 연산자를 사용해야 합니다. 다음은 그 예입니다.someObject.As<SomeComImportInterface>자세한 내용은 COM interop 가이드 참조하세요.
System.Runtime.InteropServices.COMException: 등록되지 않은 클래스(0x80040154(REGDB_E_CLASSNOTREG))
- C++/WinRT 구성 요소에서 C#/WinRT 프로젝션을 사용할 때 이 예외가 표시되는 경우 구성 요소가 project 속성 또는 파일을 통해 Windows Desktop Compatible 속성을
.vcxproj로 설정했는지 확인합니다.
- C++/WinRT 구성 요소에서 C#/WinRT 프로젝션을 사용할 때 이 예외가 표시되는 경우 구성 요소가 project 속성 또는 파일을 통해 Windows Desktop Compatible 속성을
.NET SDK 버전 오류
종속성보다 이전 .NET SDK 버전으로 빌드된 project 다음과 같은 오류 또는 경고가 발생할 수 있습니다.
| 오류 또는 경고 메시지 | 이유 |
|---|---|
| 경고 MSB3277: 해결할 수 없는 여러 버전의 WinRT.Runtime 또는 Microsoft.Windows.SDK.NET 간에 충돌이 발생했습니다. | 이 빌드 경고는 해당 API surface 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 문제 페이지 통해 문제를 제출합니다.
추가 리소스
GitHub에서 Microsoft와 공동 작업
이 콘텐츠의 원본은 GitHub에서 찾을 수 있으며, 여기서 문제와 끌어오기 요청을 만들고 검토할 수도 있습니다. 자세한 내용은 참여자 가이드를 참조하세요.
Windows developer