C#/WinRT

C#/WinRT — это набор средств, упакованных в NuGet, который предоставляет поддержку проекции Windows Runtime (WinRT) для языка C#. Сборка проекции — это интероп-сборка, которая позволяет программировать API WinRT естественным и привычным образом для целевого языка. Проекция C#/WinRT скрывает сведения о взаимодействии между интерфейсами C# и WinRT и предоставляет сопоставления многих типов WinRT с соответствующими эквивалентами .NET, такими как строки, URI, распространенные типы значений и универсальные коллекции.

В настоящее время C#/WinRT поддерживает использование API WinRT с помощью Target Framework Monikers (TFM) в .NET. Установка TFM с определенной версией пакета SDK для Windows добавляет ссылки на проекцию и сборки среды выполнения Windows SDK, созданные C#/WinRT.

Пакет NuGet C#/WinRT NuGet позволяет создавать и ссылаться на собственные сборки взаимодействия WinRT для .NET потребителей. Последняя версия C#/WinRT также включает предварительную версию создания типов WinRT в C#.

Дополнительные сведения см. в репозитории C#/WinRT GitHub.

Мотивация для C#/WinRT

.NET (ранее известный как .NET Core) — это кроссплатформенная среда выполнения с открытым кодом, которая может использоваться для создания приложений устройства, облака и Интернета вещей.

Предыдущие версии платформы .NET Framework и .NET Core имели встроенные знания о WinRT — технологии, относящиеся к Windows. Для поддержки переносимости и эффективности .NET 6+, мы подняли поддержку проекции WinRT из .NET компилятора и среды выполнения и переместили его в набор средств C#/WinRT (см. Встроенная поддержка WinRT удаляется из .NET). Цель C#/WinRT — обеспечить четность со встроенной поддержкой WinRT, предоставляемой более ранними версиями компилятора C# и среды выполнения .NET. Дополнительные сведения см. в сопоставлениях типов Windows Runtime в .NET.

C#/WinRT также поддерживает компоненты в Windows App SDK, включая WinUI 3. Windows App SDK извлекает родные элементы управления пользовательского интерфейса Microsoft и другие встроенные компоненты из операционной системы. Это позволяет разработчикам приложений использовать последние элементы управления и компоненты в Windows 10, версии 1809 и более поздних выпусках.

Наконец, C#/WinRT — это общий набор средств и предназначен для поддержки других сценариев, в которых встроенная поддержка WinRT недоступна в компиляторе C# или среде выполнения .NET.

Что нового

Последние выпуски C#/WinRT можно найти на странице release notes в репозитории Github.

Usage

Пакет NuGet C#/WinRT можно использовать для создания проекций C# (также называемых сборками взаимодействия) из компонентов WinRT и для разработки компонентов C#/WinRT. Дополнительные сведения о сценариях использования для C#/WinRT см. в руководстве usage в нашем репозитории.

Создание и распространение сборки взаимодействия

API WinRT определяются в файлах метаданных Windows (WinMD). Пакет NuGet C#/WinRT (Microsoft.Windows.CsWinRT) включает компилятор C#/WinRT, cswinrt.exe, который можно использовать для обработки файлов WinMD и создания кода .NET C#. C#/WinRT компилирует эти исходные файлы в сборку для взаимодействия, аналогично тому, как C++/WinRT создает заголовки для проекции языка C++. Затем можно распространить сборку взаимодействия C#/WinRT вместе со сборкой реализации для .NET приложений, на которые обычно ссылаются в виде пакета NuGet.

Дополнительные сведения о том, как создавать и распространять сборки взаимодействия, см. в статье Создание проекции C# из компонента C++/WinRT и её распространение в виде пакета NuGet для .NET-приложений.

Ссылаться на межоперационную сборку

Обычно проекты приложений ссылаются на сборки взаимодействия C#/WinRT. Но на них также могут ссылаться промежуточные сборки взаимодействия. Например, сборка взаимодействия WinUI будет ссылаться на сборку взаимодействия Windows SDK.

Если вы распространяете сторонний компонент WinRT без официальной сборки взаимодействия, проект приложения может следовать процедуре создания сборки взаимодействия для создания собственных проекционных источников. Мы не рекомендуем этот подход, так как он может создавать конфликтующие проекции одного типа в процессе. Упаковка NuGet, следуя схеме семантического управления версиями , предназначена для предотвращения этого. Официальная сборка взаимодействия стороннего производителя предпочтительна.

Встроенная поддержка типов WinRT (предварительная версия)

Начиная с версии 1.4.1 C#/WinRT, добавлена поддержка внедрения проекции Windows SDK и исходных кодов среды выполнения для .NET и .NET Standard 2.0 в выходные данные вашей библиотеки или приложения. Это полезно в случаях, когда использование типов windows SDK является автономным. Встроенная поддержка удаляет зависимости от WinRT.Runtime.dll и Microsoft.Windows.SDK.NET.dll что сокращает размер выходных данных библиотеки или приложения. Она также позволяет разработчикам библиотек предоставлять поддержку нижнего уровня и удалять необходимость многоцелевой поддержки.

Дополнительные сведения см. в документации C#/WinRT embedded в нашем репозитории.

Активация типа WinRT

C#/WinRT поддерживает активацию типов WinRT, размещенных операционной системой, а также сторонних компонентов, таких как Win2D. Поддержка активации сторонних компонентов в классическом приложении включена с помощью активации без регистрации WinRT (см. Повышение функциональности не упакованных классических приложений с использованием компонентов Windows Runtime), доступной в Windows 10 версии 1903 и более поздние версии. Компоненты, написанные на языке C++, должны задать для свойства Windows Desktop Compatible значение True либо через свойства проекта, либо через файл .vcxproj, чтобы осуществлять ссылку и пересылку двоичных файлов Microsoft.VCLibs.Desktop для потребляющих приложений. В противном случае приложениям, которые потребляют этот пакет, потребуется пакет VCRT Forwarders, если компонент предназначен только для приложений UWP.

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> project, например:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  В C#/WinRT версии 1.2.1 и более поздних версиях TargetPlatformVersionэто свойство по умолчанию является производным от версии пакета SDK для Windows, указанной в свойстве TargetFramework .

• Ошибка CS0246: не удалось найти тип или имя пространства имен 'Windows' (возможно, отсутствует директива using или ссылка на сборку?)

  Чтобы устранить эту ошибку, измените <TargetFramework> свойство для конкретной версии Windows, например:

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

  Для получения более подробной информации об указании свойства см. документацию по вызову API Windows Runtime.

• System.InvalidCastException при приведении к интерфейсу с атрибутом ComImport

  При приведении объекта к интерфейсу с атрибутом ComImport необходимо использовать оператор .As<> вместо явного оператора приведения. Рассмотрим пример.

  someObject.As<SomeComImportInterface>
  

  Дополнительные сведения см. в руководстве COM interop.

• System.Runtime.InteropServices.COMException: класс не зарегистрирован (0x80040154 (REGDB_E_CLASSNOTREG))

  • Если вы видите это исключение при использовании проекции C#/WinRT из компонента C++/WinRT, убедитесь, что компонент установил свойство Windows Desktop Compatible в значение True либо через свойства проекта, либо через файл .vcxproj.

ошибки управления версиями пакета SDK .NET

Вы можете столкнуться со следующими ошибками или предупреждениями в проекте, созданном с более ранней версией .NET SDK, чем используемые зависимости.

Сообщение об ошибке или предупреждении	Причина
Предупреждение MSB3277: обнаружены конфликты между различными версиями WinRT.Runtime или Microsoft.Windows.SDK.NET которые не удалось устранить.	Это предупреждение сборки возникает при ссылке на библиотеку, которая предоставляет типы Windows SDK на поверхности API.
Ошибка CS1705: сборка "AssemblyName1" использует "TypeName", который имеет более высокую версию, чем ссылка на сборку "AssemblyName2".	Эта ошибка компилятора сборки возникает при ссылке и использовании предоставленных типов Windows SDK в библиотеке.
System.IO.FileLoadException	Эта ошибка среды выполнения может возникать при вызове определенных API-интерфейсов в библиотеке, которая не предоставляет типы windows SDK.

Чтобы устранить эти ошибки, обновите пакет SDK .NET до последней версии. Это гарантирует, что версии сборок среды выполнения и пакета SDK для Windows, используемые приложением, совместимы со всеми зависимостями. Эти ошибки могут возникать с ранними обновлениями или обновлениями компонентов в пакете SDK .NET, так как исправления среды выполнения могут требовать обновления версий сборок.

Известные проблемы

Известные проблемы и критические изменения отмечаются в репозитории C#/WinRT GitHub.

Если возникли функциональные проблемы с пакетом NuGet C#/WinRT, компилятором cswinrt.exe или созданными источниками проекции, отправьте нам проблемы с помощью страницы проблем C#/WinRT.

Дополнительные ресурсы

• C#/WinRT GitHub репозиторий