Общие сведения о C++/WinRT

C++/WinRT — это полностью стандартная современная языковая проекция C++17 для API-интерфейсов среда выполнения Windows (WinRT), реализованная в виде библиотеки заголовочных файлов и предназначенная для предоставления первоклассного доступа к современному API Windows. С помощью C++/WinRT можно создавать и использовать среда выполнения Windows API с помощью любого компилятора C++17, совместимого со стандартами. Пакет SDK Windows включает C++/WinRT; он появился в версии 10.0.17134.0 (Windows 10 версии 1803).

C++/WinRT является рекомендуемой Microsoft заменой для языковой проекции C++/CX и библиотеки шаблонов C++ для среда выполнения Windows (WRL). Полный список тем о C++/WinRT включает сведения как о взаимодействии с C++/CX и WRL, так и о переносе с C++/CX и WRL.

См. также сведения о том , где можно найти примеры приложений C++/WinRT?.

Языковые проекции

среда выполнения Windows основан на API-интерфейсах объектной модели компонентов (COM) и предназначен для доступа через проекции языка. Проекция скрывает сведения COM и обеспечивает более естественный интерфейс программирования для заданного языка.

Проекция языка C++/WinRT в справочном содержимом API среда выполнения Windows

При просмотре среда выполнения Windows API щелкните поле со списком языка в правом верхнем углу и выберите C++/WinRT, чтобы просмотреть блоки синтаксиса API, как они отображаются в проекции языка C++/WinRT.

Поддержка C++/WinRT, XAML, расширения VSIX и пакета NuGet в Visual Studio

Для поддержки Visual Studio вам потребуется Visual Studio 2022 или Visual Studio 2019 или Visual Studio 2017 (по крайней мере версия 15.6; рекомендуется по крайней мере 15.7). В установщике Visual Studio установите рабочую нагрузку разработки универсальная платформа Windows. В разделе "Сведения об установке">"Разработка для универсальная платформа Windows" установите флажок "Средства универсальная платформа Windows для C++ (v14x)", если вы еще не сделали этого. В Windows Параметры>Конфиденциальность и безопасность (Windows 10: Обновление и безопасность) >Для разработчиков включите параметр Режим разработчика (Windows 10: а не параметр Загрузка неопубликованных приложений).

Хотя мы рекомендуем разрабатываться с помощью последних версий Visual Studio и пакета SDK Windows, если вы используете версию C++/WinRT, которая поставляется с пакетом SDK Windows до 10.0.17763.0 (Windows 10 версии 1809), то для использования заголовков пространств имен Windows, упомянутых выше, потребуется минимум. Windows целевая версия пакета SDK в проекте 10.0.17134.0 (Windows 10 версии 1803).

Visual Studio 2022 поставляется с встроенными шаблонами проектов и элементов C++/WinRT, чтобы сразу начать разработку C++/WinRT. Он также поставляется с Visual Studio собственной визуализацией отладки (natvis) проектируемых типов C++/WinRT; обеспечивая интерфейс отладки, аналогичный отладке C#. Natvis является автоматическим для отладочных сборок. Дополнительные сведения см. в разделе Собственная визуализация отладки Visual Studio для C++/WinRT.

Для более старых версий Visual Studio необходимо скачать и установить последнюю версию расширения C++/Win Visual Studio RT (VSIX) из Visual Studio Marketplace.

• Расширение VSIX предоставляет шаблоны проектов и элементов C++/WinRT в Visual Studio.
• Кроме того, вы получаете встроенную в Visual Studio визуализацию отладки (natvis) для проецируемых типов C++/WinRT.

Шаблоны проектов Visual Studio для C++/WinRT описаны в следующих разделах. При создании нового проекта C++/WinRT с установленной последней версией расширения VSIX в новый проект C++/WinRT автоматически устанавливается пакет NuGet Microsoft.Windows.CppWinRT. Microsoft.Windows. Пакет NuGet CppWinRT предоставляет поддержку сборки C++/WinRT (свойства и целевые объекты MSBuild), что делает проект переносимым между компьютером разработки и агентом сборки (на котором установлен только пакет NuGet, а не расширение VSIX).

В качестве альтернативы можно преобразовать существующий проект, вручную установив пакет NuGet Microsoft.Windows.CppWinRT. После установки (или обновления до) последней версии расширения VSIX откройте существующий проект в Visual Studio, выберите Project>Manage NuGet Packages...>Обзор, введите или вставьте Microsoft.Windows.CppWinRT в поле поиска, выберите элемент в результатах поиска, а затем нажмите Установить, чтобы установить пакет для этого проекта. После добавления пакета проект получит поддержку MSBuild для C++/WinRT, включая вызов средства cppwinrt.exe.

• Так как C++/WinRT использует функции из стандарта C++17, пакет NuGet задает свойство проекта C/>C++Language>C++ Language Standard> в Visual Studio.
• Он также добавляет параметр компилятора /bigobj .
• Он добавляет параметр компилятора /await для включения co_await.
• Он указывает компилятору XAML генерировать код C++/WinRT.
• Кроме того, может потребоваться задать режим соответствия: Да (/permissive-), что также ограничивает код соответствием стандартам.
• Следует также учитывать такое свойство проекта, как C/C++>Общие>Считать предупреждения ошибками. Задайте для этого значение "Да(/WX) или Нет (/WX-) для вкуса. Иногда исходные файлы, созданные cppwinrt.exe средством, создают предупреждения, пока не добавите к ним реализацию.

При настройке системы, как описано выше, вы сможете создавать и создавать или открывать проект C++/WinRT в Visual Studio и развертывать его.

Начиная с версии 2.0, в пакет NuGet Microsoft.Windows.CppWinRT входит средство cppwinrt.exe. Вы можете указать средству cppwinrt.exe файл метаданных среда выполнения Windows (.winmd), чтобы создать стандартную библиотеку C++, основанную на заголовочных файлах, которая предоставляет проекцию API, описанных в метаданных, для использования в коде C++/WinRT. среда выполнения Windows файлы метаданных (.winmd) предоставляют канонический способ описания поверхности API среда выполнения Windows. Указывая cppwinrt.exe на метаданные, вы можете создать библиотеку для использования с любым классом среды выполнения, реализованным во втором или стороннем среда выполнения Windows компоненте или реализованном в собственном приложении. Дополнительные сведения см. в разделе "Использование API с помощью C++/WinRT".

С помощью C++/WinRT можно также реализовать собственные классы среды выполнения с помощью стандартного C++, не прибегая к программированию в стиле COM. Для класса среды выполнения вам достаточно описать свои типы в файле IDL, а midl.exe и cppwinrt.exe автоматически сгенерируют для вас файлы шаблонного исходного кода реализации. Кроме того, можно просто реализовать интерфейсы, производные от базового класса C++/WinRT. Дополнительные сведения см. в статье "Создание API" с помощью C++/WinRT.

Список вариантов настройки для средства cppwinrt.exe, задаваемых свойствами проекта, см. в файле readme пакета NuGet Microsoft.Windows.CppWinRT.

Вы можете определить проект, использующий поддержку C++/WinRT для MSBuild, по наличию в проекте установленного пакета NuGet Microsoft.Windows.CppWinRT.

Ниже приведены шаблоны проектов Visual Studio, предоставляемые расширением VSIX.

Пустое приложение (C++/WinRT)

Шаблон проекта для приложения Universal Windows Platform (UWP) с пользовательским интерфейсом XAML. Для классических приложений WinUI 3 используйте вместо этого шаблон «Пустое приложение, пакетированное (WinUI 3 в классическом приложении)».

Visual Studio предоставляет поддержку компиляции XAML для создания шаблонов файлов реализации и заголовочных файлов из файла языка определения интерфейсов (IDL) (.idl), связанного с каждым файлом разметки XAML. В файле IDL определите все локальные классы среды выполнения, на которые вы хотите ссылаться в XAML-страницах приложения, а затем один раз соберите проект, чтобы создать шаблоны реализации в Generated Files и определения типов-заглушек в Generated Files\sources. Затем используйте эти определения типов для заглушек в качестве ориентира при реализации классов локальной среды выполнения. См. Вынесение классов среды выполнения в файлы MIDL (.idl).

Поддержка поверхности конструктора XAML в Visual Studio для C++/WinRT почти не уступает C#. В Visual Studio можно использовать вкладку "События" окна "Свойства" для добавления обработчиков событий в проект C++/WinRT. Вы также можете добавить обработчики событий в код вручную. Дополнительные сведения см. в разделе "Обработка событий с помощью делегатов в C++/WinRT ".

Основное приложение (C++/WinRT)

Шаблон проекта для приложения Universal Windows Platform (UWP), которое не использует XAML. В этом шаблоне нет эквивалента WinUI 3.

Вместо этого используется заголовочный файл пространства имён Windows C++/WinRT для пространства имён Windows.ApplicationModel.Core. После создания и запуска щелкните пустое пространство, чтобы добавить цветной квадрат; затем щелкните цветной квадрат, чтобы перетащить его.

Консольное приложение Windows (C++/WinRT)

Шаблон проекта для клиентского приложения C++/WinRT для Windows Desktop с пользовательским интерфейсом консоли.

Настольное приложение Windows (C++/WinRT)

Шаблон проекта для клиентского приложения C++/WinRT для классического рабочего стола Windows, которое отображает объект среда выполнения Windows Windows.Foundation.Uri в окне сообщения Win32 MessageBox.

Компонент среды выполнения Windows (C++/WinRT)

Шаблон проекта для компонента; обычно для использования из Universal Windows Platform (UWP).

Этот шаблон демонстрирует цепочку инструментов midl.exe>cppwinrt.exe, в которой метаданные среда выполнения Windows (.winmd) генерируются из IDL, а затем на основе метаданных среда выполнения Windows генерируются файлы реализации и заголовочные файлы-заглушки.

В файле IDL определите классы среды выполнения в компоненте, их интерфейс по умолчанию и любые другие интерфейсы, которые они реализуют. Соберите проект один раз, чтобы создать module.g.cpp, module.h.cpp шаблоны реализации в Generated Files и заглушки определений типов в Generated Files\sources. Затем используйте эти определения типа заглушки для ссылки на реализацию классов среды выполнения в компоненте. См. Выделение классов среды выполнения в файлы MIDL (.idl).

Включите в пакет скомпилированный бинарный файл компонента среда выполнения Windows и его .winmd вместе с приложением UWP, которое их использует.

Более ранние версии расширения VSIX

Рекомендуется установить (или обновить до) последнюю версию расширения VSIX. По умолчанию он настроен на автоматическое обновление. Если это сделать, и у вас есть проекты, созданные с версией расширения VSIX до версии 1.0.190128.4, в этом разделе содержатся важные сведения об обновлении этих проектов для работы с новой версией. Если вы не обновляете, то сведения в этом разделе по-прежнему будут полезны.

С точки зрения поддерживаемых версий пакета SDK Windows и Visual Studio и конфигурации Visual Studio сведения в Visual Studio поддержке C++/WinRT, XAML, расширения VSIX и раздела пакета NuGet, приведенного выше, применяются к более ранним версиям расширения VSIX. В приведенной ниже информации описываются важные различия в поведении и настройке проектов, созданных с более ранними версиями (или обновленными для работы с ними).

Создано ранее 1.0.181002.2

Если проект был создан с версией расширения VSIX ранее 1.0.181002.2, поддержка сборки C++/WinRT была встроена в ту версию расширения VSIX. В проекте задано свойство <CppWinRTEnabled>true</CppWinRTEnabled> в файле .vcxproj.

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

Вы можете обновить проект, вручную установив пакет NuGet Microsoft.Windows.CppWinRT. После установки (или обновления до) последней версии расширения VSIX откройте проект в Visual Studio, выберите Project>Manage NuGet Packages...>Обзор, введите или вставьте Microsoft.Windows.CppWinRT в поле поиска, выберите элемент в результатах поиска, а затем нажмите Установить, чтобы установить пакет для проекта.

Создан с версией 1.0.181002.2 или обновлён до версии в диапазоне от 1.0.181002.2 до 1.0.190128.3

Если ваш проект был создан с использованием версии расширения VSIX от 1.0.181002.2 до 1.0.190128.3 включительно, то пакет NuGet Microsoft.Windows.CppWinRT автоматически устанавливался в проект шаблоном проекта. Возможно, вы также обновили старый проект, чтобы использовать версию расширения VSIX в этом диапазоне. Если это так, то, поскольку поддержка сборки также по-прежнему присутствовала в версиях расширения VSIX в этом диапазоне, в обновлённом проекте пакет NuGet Microsoft.Windows.CppWinRT может как быть установлен, так и отсутствовать.

Чтобы обновить проект, следуйте инструкциям из предыдущего раздела и убедитесь, что в вашем проекте установлен пакет NuGet Microsoft.Windows.CppWinRT.

Недопустимые конфигурации обновления

В последней версии расширения VSIX недопустимо, чтобы проект имел свойство <CppWinRTEnabled>true</CppWinRTEnabled>, если при этом у него не установлен пакет NuGet Microsoft.Windows.CppWinRT. Проект с этой конфигурацией создает сообщение об ошибке сборки: "VSIX C++/WinRT больше не предоставляет поддержку сборки проекта. Добавьте ссылку на пакет NuGet Microsoft.Windows.CppWinRT в проект.

Как уже упоминалось выше, в проекте C++/WinRT теперь должен быть установлен пакет NuGet.

Так как элемент <CppWinRTEnabled> теперь устарел, вы можете при желании изменить .vcxproj и удалить этот элемент. Это не обязательно, но это вариант.

Кроме того, если ваш .vcxproj содержит <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, то этот элемент можно удалить, чтобы выполнять сборку без необходимости устанавливать расширение VSIX для C++/WinRT.

Поддержка пакета SDK для C++/WinRT

Хотя в настоящее время он присутствует только по соображениям совместимости, начиная с версии 10.0.17134.0 (Windows 10 версии 1803), пакет SDK Windows содержит стандартную библиотеку C++ на основе заголовков для использования интерфейсов API Windows стороннего производителя (api среда выполнения Windows в пространствах имен Windows). Эти заголовки находятся в папке %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Начиная с версии 10.0.17763.0 пакета SDK для Windows (Windows 10, версия 1809), эти заголовки создаются в папке $(GeneratedFilesDir) вашего проекта.

Опять же, для обеспечения совместимости Windows SDK также включает инструмент cppwinrt.exe. Однако вместо этого мы рекомендуем установить и использовать последнюю версию cppwinrt.exe, входящую в пакет NuGet Microsoft.Windows.CppWinRT. Этот пакет и cppwinrt.exeописан в разделах выше.

Пользовательские типы в проекции C++/WinRT

В программировании C++/WinRT можно использовать стандартные функции языка C++ и стандартные типы данных C++ и C++/WinRT, включая некоторые типы данных стандартной библиотеки C++. Но вам также станут известны некоторые пользовательские типы данных в проекции, и вы можете при желании использовать их. Например, мы используем winrt::hstring в примере кода быстрого запуска в руководстве по началу работы с C++/WinRT.

winrt::com_array — это другой тип, который вы, скорее всего, будете использовать в какой-то момент. Но вы менее склонны напрямую использовать тип, например winrt::array_view. Или вы можете не использовать его таким образом, чтобы у вас не было кода для изменения, если и когда эквивалентный тип отображается в стандартной библиотеке C++.

Важные API

• структура winrt::hstring
• пространство имен winrt

Связанные темы

• C++/CX
• Расширение C++/WinRT Visual Studio (VSIX)
• Начало работы с C++/WinRT
• Стандартные типы данных C++ и C++/WinRT
• Обработка строк в C++/WinRT
• API среды выполнения Windows