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

2025-06-10

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

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

Это важно

Некоторые из наиболее важных элементов C++/WinRT, которые следует учитывать, описаны в разделах: поддержка пакета SDK для C++/WinRT и поддержка Visual Studio для C++/WinRT, XAML, расширения VSIX и пакета NuGet.

См. также Где можно найти примеры приложений C++/WinRT?.

Проекции языка

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

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

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

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

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

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

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

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

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

Это важно

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

Так как C++/WinRT использует функции из стандарта C++17, пакет NuGet задает свойство проекта языка C/C++>язык>C++ уровня "Стандартный">СТАНДАРТ ISO C++17 (/std:c++17) в 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)

Шаблон проекта для приложения универсальной платформы Windows (UWP), имеющего пользовательский интерфейс XAML.

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)

Шаблон проекта для приложения универсальной платформы Windows (UWP), который не использует XAML.

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

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

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

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

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

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

Шаблон проекта для компонента; обычно для использования из универсальной платформы Windows (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, в этом разделе содержатся важные сведения об обновлении этих проектов для работы с новой версией. Если вы не обновляете, то сведения в этом разделе по-прежнему будут полезны.

С точки зрения поддерживаемых версий Windows SDK и 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.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. Начиная с Windows SDK версии 10.0.17763.0 (Windows 10, версии 1809), эти заголовки создаются для вас внутри папки вашего проекта $(GeneratedFilesDir).

Снова для обеспечения совместимости пакет SDK для Windows также поставляется с инструментом 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++.

Предупреждение

Существуют также типы, которые можно увидеть, если вы внимательно изучаете заголовки пространства имен Windows C++/WinRT. Примером является winrt::param::hstring, но существуют также примеры коллекций. Они существуют исключительно для оптимизации привязки входных параметров, и они обеспечивают большие улучшения производительности и делают большинство вызовов шаблонов "просто работой" для связанных стандартных типов и контейнеров C++. Эти типы используются проекцией только в тех случаях, когда они приносят наибольшую ценность. Они очень оптимизированы, и они не используются для общего использования; не заманчиво использовать их самостоятельно. Не следует использовать что-либо из пространства имен winrt::impl, так как они являются типами реализаций и поэтому подлежат изменению. Вы должны продолжать использовать стандартные типы или типы из пространства имен winrt.

См. также передачу параметров через границу ABI.