C#/WinRT

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

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

Пакет 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. Дополнительные сведения см. в .NET сопоставлениях типов среда выполнения Windows.

C#/WinRT также поддерживает компоненты в Windows App SDK, включая WinUI 3. Windows App SDK интегрирует нативные элементы управления пользовательского интерфейса Майкрософт и другие нативные компоненты из операционной системы. Это позволяет разработчикам приложений использовать последние элементы управления и компоненты в 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 (Майкрософт.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 поддержка включается для внедрения проекции пакета SDK Windows и источников среды выполнения как для .NET, так и для .NET standard 2.0 в выходные данные библиотеки или приложения. Это полезно в случаях, когда использование типов пакета SDK Windows является автономным. Встроенная поддержка устраняет зависимости от WinRT.Runtime.dll и Майкрософт.Windows.SDK.NET.dll, что уменьшает размер выходного файла библиотеки или приложения. Она также позволяет разработчикам библиотек предоставлять поддержку нижнего уровня и удалять необходимость многоцелевой поддержки.

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

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

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

  Обратитесь к документации по вызову среда выполнения Windows API для получения более подробной информации о спецификации свойства <TargetFramework>.

• 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, чем любая из зависимостей, могут возникнуть следующие ошибки или предупреждения.

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

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

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

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

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

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