Introducción a C++/WinRT

C++/WinRT es una moderna proyección de lenguaje C++17 totalmente estándar para las API de Windows Runtime (WinRT), implementada como una biblioteca basada en archivos de encabezado y diseñada para darte acceso de primera clase a la API moderna de Windows. Con C++/WinRT, puede crear y consumir Windows Runtime API mediante cualquier compilador de C++17 compatible con estándares. El SDK de Windows incluye C++/WinRT; se introdujo en la versión 10.0.17134.0 (Windows 10, versión 1803).

C++/WinRT es el reemplazo recomendado por Microsoft de la proyección del lenguaje C++/CX y de la Windows Runtime C++ Template Library (WRL). La lista completa de temas sobre C++/WinRT incluye información sobre la interoperación con y la portabilidad desde, C++/CX y WRL.

Consulte también ¿Dónde puedo encontrar aplicaciones de ejemplo de C++/WinRT?.

Proyecciones de idiomas

El Windows Runtime se basa en las API del modelo de objetos componentes (COM) y está diseñada para acceder a ellas a través de proyecciones de lenguaje. Una proyección oculta los detalles COM y proporciona una experiencia de programación más natural para un lenguaje determinado.

Proyección del lenguaje C++/WinRT en el contenido de referencia de la API de Windows Runtime

Al examinar Windows Runtime API, haga clic en el cuadro combinado Lenguaje de la esquina superior derecha y seleccione C++/WinRT para ver los bloques de sintaxis de API tal como aparecen en la proyección del lenguaje C++/WinRT.

Visual Studio compatibilidad con C++/WinRT, XAML, la extensión VSIX y el paquete NuGet

Para obtener Visual Studio soporte técnico, necesitará Visual Studio 2022 o Visual Studio 2019 o Visual Studio 2017 (al menos la versión 15.6; se recomienda al menos 15.7). Desde el instalador de Visual Studio, instale la carga de trabajo de Desarrollo de la Plataforma universal de Windows. En Detalles de instalación>desarrollo de la Plataforma universal de Windows, seleccione la opción herramientas de la Plataforma universal de Windows para C++ (v14x) si aún no lo ha hecho. Y, en Windows configuración>Privacidad y seguridad (Windows 10: Actualización y seguridad Seguridad) >Para los desarrolladores, habilite la opción Modo de desarrollador (Windows 10: no la opción De instalación de prueba de aplicaciones).

Aunque recomendamos que desarrolle con las versiones más recientes de Visual Studio y del SDK de Windows, si usa una versión de C++/WinRT incluida en el SDK de Windows anterior a la versión 10.0.17763.0 (Windows 10, versión 1809), para poder usar los encabezados de los espacios de nombres de Windows mencionados anteriormente, necesitará que su proyecto tenga como mínimo la versión de destino 10.0.17134.0 del SDK de Windows (Windows 10, versión 1803).

Visual Studio 2022 incluye plantillas de proyecto y de elemento de C++/WinRT integradas, para que pueda empezar a desarrollar con C++/WinRT de inmediato. También incluye la visualización de depuración nativa de Visual Studio (natvis) de los tipos proyectados de C++/WinRT, lo que ofrece una experiencia similar a la depuración de C#. Natvis es automático para las compilaciones de depuración. Para obtener más información, consulta la visualización de depuración nativa de Visual Studio para C++/WinRT.

Para las versiones anteriores de Visual Studio, le conviene descargar e instalar la versión más reciente de la extensión de Visual Studio C++/WinRT (VSIX) desde el Visual Studio Marketplace.

• La extensión VSIX proporciona plantillas de proyecto y elemento de C++/WinRT en Visual Studio.
• Además, proporciona visualización de depuración nativa de Visual Studio (natvis) para los tipos proyectados de C++/WinRT.

Los Visual Studio plantillas de proyecto para C++/WinRT se describen en las secciones siguientes. Al crear un nuevo proyecto de C++/WinRT con la versión más reciente de la extensión VSIX instalada, el nuevo proyecto de C++/WinRT instala automáticamente el paquete NuGet Microsoft.Windows.CppWinRT. El paquete NuGet Microsoft.Windows.CppWinRT proporciona compatibilidad de compilación para C++/WinRT (propiedades y destinos de MSBuild), lo que permite que el proyecto sea portátil entre una máquina de desarrollo y un agente de compilación (en el que solo está instalado el paquete NuGet, y no la extensión VSIX).

Como alternativa, puede convertir un proyecto existente instalando manualmente el paquete NuGet Microsoft.Windows.CppWinRT. Después de instalar (o actualizar a) la versión más reciente de la extensión VSIX, abra la project existente en Visual Studio, haga clic en Project>Administrar paquetes NuGet...>Examine, escriba o pegue Microsoft.Windows. CppWinRT en el cuadro de búsqueda, seleccione el elemento en los resultados de búsqueda y, a continuación, haga clic en Instalar para instalar el paquete para ese project. Una vez que hayas agregado el paquete, obtendrás compatibilidad de MSBuild para C++/WinRT en el proyecto, incluida la invocación de la herramienta cppwinrt.exe.

• Dado que C++/WinRT usa características del estándar C++17, el paquete NuGet establece la propiedad del proyecto C/C++>Idioma>Estándar del lenguaje C++>Estándar ISO C++17 (/std:c++17) en Visual Studio.
• También agrega la opción del compilador /bigobj .
• Agrega la opción del compilador /await para habilitar co_await.
• Indica al compilador XAML que emita codegen de C++/WinRT.
• También puede establecer el modo de conformidad: Sí (/permissive-), lo que restringe aún más el código para que sea compatible con los estándares.
• Otra propiedad de proyecto que se debe tener en cuenta es C/C++>General>Tratar advertencias como errores. Establézcalo en Sí(/WX) o No (/WX-) para probar. A veces, los archivos fuente generados por la herramienta cppwinrt.exe muestran advertencias hasta que añada su implementación.

Con el sistema configurado como se ha descrito anteriormente, podrá crear y compilar, o abrir, un proyecto de C++/WinRT en Visual Studio e implementarlo.

A partir de la versión 2.0, el paquete NuGet Microsoft.Windows.CppWinRT incluye la herramienta cppwinrt.exe. Puede hacer que la herramienta cppwinrt.exe apunte a un archivo de metadatos de Windows Runtime (.winmd) para generar una biblioteca de C++ estándar basada en archivos de cabecera que expone las API descritas en los metadatos para su uso desde código C++/WinRT. Los archivos de metadatos de Windows Runtime (.winmd) proporcionan una forma canónica de describir la superficie de una API de Windows Runtime. Al apuntar cppwinrt.exe a los metadatos, puede generar una biblioteca para usarla con cualquier clase del entorno de ejecución implementada en un componente de Windows Runtime de otro fabricante o de terceros, o en su propia aplicación. Para obtener más información, consulta Consumir API con C++/WinRT.

Con C++/WinRT, también puede implementar sus propias clases en tiempo de ejecución mediante C++estándar, sin recurrir a la programación de estilo COM. Para una clase del entorno de ejecución, solo tienes que describir tus tipos en un archivo IDL, y midl.exe y cppwinrt.exe generan por ti los archivos de código fuente base de implementación. También puede implementar interfaces derivando de una clase base de C++/WinRT. Para obtener más información, consulta Creación de API con C++/WinRT.

Para obtener una lista de las opciones de personalización de la herramienta cppwinrt.exe, configuradas mediante las propiedades del proyecto, consulte el archivo readme del paquete NuGet Microsoft.Windows.CppWinRT.

Puede identificar un proyecto que utiliza la compatibilidad con MSBuild de C++/WinRT por la presencia del paquete NuGet Microsoft.Windows.CppWinRT instalado en el proyecto.

Estas son las plantillas de proyecto Visual Studio proporcionadas por la extensión VSIX.

Aplicación en blanco (C++/WinRT)

Plantilla de proyecto para una aplicación de Plataforma universal de Windows (UWP) que tiene una interfaz de usuario XAML. En el caso de las aplicaciones de escritorio de WinUI 3, use la plantilla Aplicación vacía empaquetada (WinUI 3 en escritorio) en su lugar.

Visual Studio proporciona compatibilidad con el compilador XAML para generar códigos auxiliares de implementación y encabezado a partir del archivo de lenguaje de definición de interfaz (IDL) (.idl) que se encuentra detrás de cada archivo de marcado XAML. En un archivo IDL, defina las clases en tiempo de ejecución locales a las que quiera hacer referencia en las páginas XAML de la aplicación y, a continuación, compile el proyecto una vez para generar plantillas de implementación en Generated Filesy definiciones de tipo de código auxiliar en Generated Files\sources. A continuación, usa esas definiciones de tipos provisionales como referencia para implementar tus clases locales de tiempo de ejecución. Consulte Incorporación de clases en tiempo de ejecución en archivos MIDL (.idl).

La compatibilidad con la superficie de diseño XAML en Visual Studio para C++/WinRT está cerca de la paridad con C#. En Visual Studio, puede usar la pestaña Eventos de la ventana Propiedades para agregar controladores de eventos dentro de un proyecto de C++/WinRT. También puedes agregar controladores de eventos al código manualmente; consulta Controlar eventos mediante delegados en C++/WinRT para obtener más información.

Aplicación principal (C++/WinRT)

Plantilla de proyecto para una aplicación Plataforma universal de Windows (UWP) que no usa XAML. No hay ningún equivalente de WinUI 3 de esta plantilla.

En su lugar, usa el archivo de encabezado del espacio de nombres Windows de C++/WinRT para el espacio de nombres Windows.ApplicationModel.Core. Después de compilar y ejecutar, haga clic en un espacio vacío para agregar un cuadrado coloreado; a continuación, haga clic en un cuadrado coloreado para arrastrarlo.

Aplicación de consola de Windows (C++/WinRT)

Plantilla de proyecto para una aplicación cliente de C++/WinRT para Windows Desktop, con una interfaz de usuario de consola.

Aplicación de escritorio de Windows (C++/WinRT)

Plantilla de proyecto para una aplicación cliente de C++/WinRT para Escritorio de Windows, que muestra un Windows.Foundation.Uri de Windows Runtime en un MessageBox de Win32.

Componente de Windows Runtime (C++/WinRT)

Plantilla de proyecto para un componente; normalmente, para su uso en la Plataforma universal de Windows (UWP).

Esta plantilla muestra la cadena de herramientas midl.exe>cppwinrt.exe, donde los metadatos de Windows Runtime (.winmd) se generan a partir de IDL y, a continuación, se generan esqueletos de implementación y de encabezado a partir de los metadatos de Windows Runtime.

En un archivo IDL, defina las clases en tiempo de ejecución del componente, su interfaz predeterminada y cualquier otra interfaz que implementen. Compile el proyecto una vez para generar module.g.cpp, module.h.cpp, plantillas de implementación en Generated Filesy definiciones de tipo de código auxiliar en Generated Files\sources. A continuación, use esas definiciones de tipos auxiliares como referencia para implementar las clases de tiempo de ejecución de su componente. Consulte Incorporación de clases en tiempo de ejecución en archivos MIDL (.idl).

Agrupa el binario del componente de Windows Runtime compilado y su .winmd con la aplicación para UWP que los consume.

Versiones anteriores de la extensión VSIX

Se recomienda instalar (o actualizar a) la versión más reciente de la extensión VSIX. Está configurado para actualizarse automáticamente de forma predeterminada. Si lo hace y tiene proyectos creados con una versión de la extensión VSIX anterior a la 1.0.190128.4, esta sección contiene información importante sobre cómo actualizar esos proyectos para que funcionen con la nueva versión. Si no actualiza, encontrará la información en esta sección útil.

En lo que respecta a las versiones compatibles del SDK de Windows y de Visual Studio, y a la configuración de Visual Studio, la información de la sección anterior Compatibilidad de Visual Studio con C++/WinRT, XAML, la extensión VSIX y el paquete NuGet se aplica a versiones anteriores de la extensión VSIX. En la información siguiente se describen diferencias importantes sobre el comportamiento y la configuración de los proyectos creados con versiones anteriores (o actualizadas para trabajar con).

Creado antes de la versión 1.0.181002.2

Si el proyecto se creó con una versión de la extensión VSIX anterior a la 1.0.181002.2, la compatibilidad con la compilación de C++/WinRT estaba integrada en esa versión de la extensión VSIX. Tu proyecto tiene configurada la propiedad <CppWinRTEnabled>true</CppWinRTEnabled> en el archivo .vcxproj.

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

Puede actualizar el proyecto instalando manualmente el paquete NuGet Microsoft.Windows.CppWinRT. Después de instalar (o actualizar a) la versión más reciente de la extensión VSIX, abra el project en Visual Studio, haga clic en Project>Administrar paquetes NuGet...>Examine, escriba o pegue Microsoft.Windows. CppWinRT en el cuadro de búsqueda, seleccione el elemento en los resultados de búsqueda y, a continuación, haga clic en Instalar para instalar el paquete para el project.

Creado con (o actualizado a) entre 1.0.181002.2 y 1.0.190128.3

Si su proyecto se creó con una versión de la extensión VSIX entre la 1.0.181002.2 y la 1.0.190128.3, ambas incluidas, el paquete NuGet Microsoft.Windows.CppWinRT se instaló automáticamente en el proyecto mediante la plantilla del proyecto. Es posible que también haya actualizado un proyecto anterior para usar una versión de la extensión VSIX en este intervalo. Si es así, entonces —ya que la compatibilidad de compilación también seguía estando presente en las versiones de la extensión VSIX de este rango—, es posible que su proyecto actualizado tenga o no instalado el paquete NuGet Microsoft.Windows.CppWinRT.

Para actualizar tu proyecto, sigue las instrucciones de la sección anterior y asegúrate de que tu proyecto tenga instalado el paquete NuGet Microsoft.Windows.CppWinRT.

Configuraciones de actualización no válidas

Con la versión más reciente de la extensión VSIX, no es válido que un proyecto tenga la propiedad <CppWinRTEnabled>true</CppWinRTEnabled> si no tiene también instalado el paquete NuGet Microsoft.Windows.CppWinRT. Un proyecto con esta configuración genera el mensaje de error de compilación" "El VSIX de C++/WinRT ya no proporciona compatibilidad con la compilación del proyecto. Agregue una referencia de proyecto al paquete NuGet Microsoft.Windows.CppWinRT.

Como se mencionó anteriormente, un proyecto de C++/WinRT ahora debe tener instalado el paquete NuGet en él.

Puesto que el <CppWinRTEnabled> elemento ahora está obsoleto, puede editar .vcxprojy eliminar el elemento opcionalmente. No es estrictamente necesario, pero es una opción.

Además, si .vcxproj contiene <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, puede quitarlo para poder compilar sin necesidad de instalar la extensión VSIX de C++/WinRT.

Compatibilidad del SDK con C++/WinRT

Aunque ahora solo está presente por motivos de compatibilidad, a partir de la versión 10.0.17134.0 (Windows 10, versión 1803), el SDK de Windows contiene una biblioteca estándar de C++ basada en archivos de encabezado para consumir API de Windows de primera entidad (Windows Runtime API en espacios de nombres Windows). Esos encabezados están dentro de la carpeta %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. A partir de la versión 10.0.17763.0 del SDK de Windows (Windows 10 versión 1809), estos encabezados se generan automáticamente dentro de la carpeta $(GeneratedFilesDir) del proyecto.

De nuevo por motivos de compatibilidad, el SDK de Windows también incluye la cppwinrt.exe herramienta . Sin embargo, le recomendamos que, en su lugar, instale y use la versión más reciente de cppwinrt.exe, que se incluye en el paquete NuGet Microsoft.Windows.CppWinRT. Ese paquete y cppwinrt.exe, se describen en las secciones anteriores.

Tipos personalizados en la proyección de C++/WinRT

En la programación de C++/WinRT, puede usar características estándar del lenguaje C++ y tipos de datos estándar de C++ y C++/WinRT, incluidos algunos tipos de datos de la biblioteca estándar de C++. Pero también descubrirá algunos tipos de datos personalizados en la proyección, y podrá optar por usarlos. Por ejemplo, usamos winrt::hstring en el ejemplo de código de inicio rápido en Introducción a C++/WinRT.

winrt::com_array es otro tipo que es probable que use en algún momento. Pero es menos probable que use directamente un tipo como winrt::array_view. O bien, puede optar por no usarlo para que no tenga ningún código que cambiar si y cuando aparezca un tipo equivalente en la biblioteca estándar de C++.

API importantes

• struct winrt::hstring
• Espacio de nombres winrt

Temas relacionados

• C++/CX
• Extensión de C++/WinRT para Visual Studio (VSIX)
• Introducción a C++/WinRT
• Tipos de datos estándar de C++ y C++/WinRT
• Control de cadenas en C++/WinRT
• API de Windows Runtime