C#/WinRT

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

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

Пакет NuGet C#/WinRT позволяет создавать и ссылаться на собственные сборки взаимодействия 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. Дополнительные сведения см. в сопоставлениях .NET типов среды выполнения Windows.

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

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

Что нового

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

Usage

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

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

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 (предварительная версия)

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

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

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

C#/WinRT поддерживает активацию типов WinRT, размещенных операционной системой, а также сторонних компонентов, таких как Win2D. Поддержка активации сторонних компонентов в настольном приложении включена с использованием активации WinRT, не требующей регистрации (см. статью "Улучшение неупакованных настольных приложений с помощью компонентов среды выполнения Windows"), доступной в Windows 10, версии 1903 и более поздних версий. Нативные компоненты C++ должны задать для свойства Совместимость с рабочим столом Windows значение 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> свойства проекта, например:

  <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.

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

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

  someObject.As<SomeComImportInterface>
  

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

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

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

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

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

Сообщение об ошибке или предупреждении	Причина
Предупреждение 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