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, puedes crear y consumir API de Windows Runtime mediante cualquier compilador de C++17 compatible con estándares. Windows SDK incluye C++/WinRT; se introdujo en la versión 10.0.17134.0 (Windows 10, versión 1803).

C++/WinRT es la sustitución recomendada de Microsoft para la proyección de lenguaje C++/CX y la Biblioteca de plantillas de Windows Runtime C++ (WRL). En la lista completa de temas sobre C++/WinRT se incluye información sobre la interoperabilidad y la portabilidad de C++/CX y WRL.

Importante

Algunas de las partes más importantes de C++/WinRT que se deben tener en cuenta se describen en las secciones Compatibilidad del SDK con C++/WinRT y Compatibilidad de Visual Studio con C++/WinRT, XAML, la extensión VSIX y el paquete NuGet.

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

Proyecciones de lenguaje

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

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

Cuando vayas a las API de Windows Runtime, haz clic en el cuadro combinado Lenguaje en la esquina superior derecha y selecciona C++/WinRT para ver los bloques de sintaxis de API tal y como aparecen en la proyección de lenguaje C++/WinRT.

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

Para obtener compatibilidad con Visual Studio, necesitará Visual Studio 2022, Visual Studio 2019 o Visual Studio 2017 (como mínimo la versión 15.6, pero se recomienda la 15.7). Desde el instalador de Visual Studio, instale la carga de trabajo Desarrollo con la Plataforma universal de Windows. En Detallesde instalación Desarrollo de la plataforma Windows universal, compruebe las opciones de herramientas de la Plataforma universal de Windows de C++ (v14x), si aún no lo ha hecho. Además, en Windows, en ConfiguraciónActualización y seguridad>>, selecciona la opción Modo de programador en lugar de Efectuar instalación de prueba de aplicaciones.

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

Visual Studio 2022 se incluye con plantillas integradas de proyectos y elementos de C++/WinRT, para que pueda empezar a trabajar con el desarrollo de C++/WinRT de inmediato. También ofrece visualización de depuración nativa de Visual Studio (natvis) de tipos proyectados de C++/ WinRT, lo que proporciona una experiencia similar a la depuración de C#. Natvis es automático para compilaciones de depuración. Para más información, consulte Visualización de depuración nativa de Visual Studio para C++/WinRT.

Para versiones anteriores de Visual Studio, conviene descargar e instalar la última versión de la Extensión de Visual Studio C++/WinRT (VSIX) desde Visual Studio Marketplace.

  • La extensión VSIX proporciona plantillas de proyectos y elementos de C++/WinRT en Visual Studio.
  • Asimismo, proporciona una visualización de depuración nativa de Visual Studio (natvis) de los tipos proyectados de C++/WinRT.

Las plantillas de proyecto de Visual Studio para C++/WinRT se describen en las secciones siguientes. Cuando se crea un 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 ofrece compatibilidad con la compilación de 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 de VSIX).

También puedes convertir un proyecto existente si instalas 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 proyecto existente en Visual Studio, haga clic en Project Administrar NuGet paquetes...Examine, escriba o pegue Microsoft.Windows. CppWinRT en el cuadro de búsqueda, seleccione el elemento en los resultados de la búsqueda y, a continuación, haga clic en Instalar para instalar el paquete para ese proyecto. Una vez que hayas agregado el paquete, obtendrás compatibilidad de MSBuild con C++/WinRT para el proyecto, incluida la invocación de la herramienta cppwinrt.exe.

Importante

Si tienes proyectos creados con una versión de la extensión VSIX anterior a 1.0.190128.4 (o actualizados para funcionar con esta), consulta Versiones anteriores de la extensión VSIX. En esta sección encontrarás información importante sobre la configuración de los proyectos que necesitarás conocer a fin de actualizarlos para usar la versión más reciente de la extensión VSIX.

  • Dado que C++/WinRT usa características del estándar C++17, el paquete de NuGet establece la propiedad de proyecto C/C++Language C++ Language StandardISO C++17 Standard (/std:c++17) en Visual Studio.
  • También agrega la opción del compilador /bigobj.
  • Agrega la opción del compilador /await para habilitar .
  • Le indica al compilador XAML que emita código de C++/WinRT.
  • También puedes establecer Modo de conformidad: Yes (/permissive-) , que limita todavía más tu código para que sea compatible con los estándares.
  • Otra propiedad del proyecto que se debe tener en cuenta es C/C++GeneralTreat Warnings As Errors. Establece esto en Sí (/WX) o No (/WX-) según te parezca. A veces, los archivos de origen generados por la herramienta cppwinrt.exe generan advertencias hasta que les agregas tu implementación.

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

A partir de la versión 2.0, Microsoft.Windows. El paquete NuGet CppWinRT incluye la herramienta . Puedes apuntar a la herramienta en un archivo de metadatos de tiempo de ejecución de Windows ( ) para generar una biblioteca de C++ estándar basada en archivo de encabezado que proyecta las API descritas en los metadatos para su consumo desde código cppwinrt.exe.winmd de C++/WinRT. cppwinrt.exe Los archivos de metadatos de Windows Runtime (.winmd) proporcionan una forma canónica de describir una superficie de API de Windows Runtime. Al apuntar cppwinrt.exe a los metadatos, puedes generar una biblioteca para usarla con cualquier clase en tiempo de ejecución implementada en un componente de Windows Runtime de terceros o segunda parte o implementado en tu propia aplicación. Para obtener más información, consulta Consumir API con C++/WinRT.

Con C++/WinRT, también puedes implementar tus propias clases en tiempo de ejecución con C++ estándar, sin tener que recurrir a la programación de estilo COM. Para una clase en tiempo de ejecución, solo tienes que describir tus tipos en un archivo IDL, y midl.exe y cppwinrt.exe generarán para ti tus archivos de código fuente de implementación reutilizable. Como alternativa, puedes simplemente implementar interfaces si derivas de una clase base de C++/WinRT. Para obtener más información, consulta Crear API con C++/WinRT.

Para obtener una lista de las opciones de personalización de la herramienta, establecidas a través de las propiedades del cppwinrt.exe proyecto, vea Microsoft.Windows. CppWinRT NuGet paquete cppwinrt.exe.

Puedes identificar que un proyecto usa compatibilidad de MSBuild con C++WinRT porque el paquete NuGet Microsoft.Windows.CppWinRT está instalado en el proyecto.

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

Aplicación vacía (C++/WinRT)

Plantilla de proyecto para una aplicación de la Plataforma universal de Windows (UWP) que tiene una interfaz de usuario XAML.

Visual Studio proporciona compatibilidad con el compilador XAML para generar los códigos auxiliares de los encabezados y las implementaciones a partir del archivo basado en lenguaje de definición de interfaz (IDL) (.idl) que se encuentra detrás de cada archivo de marcado XAML. En un archivo IDL, define las clases en tiempo de ejecución locales a las que quieras hacer referencia en las páginas XAML de tu aplicación y, después, compila el proyecto una sola vez para generar las plantillas de implementación en Generated Files y las definiciones del tipo de código auxiliar en Generated Files\sources. Luego, usa estas definiciones de subtipo de código auxiliar como referencia para implementar tus clases en tiempo de ejecución locales. Consulta Factorizar clases en tiempo de ejecución en archivos Midl (.idl).

La compatibilidad de la superficie de diseño XAML en Visual Studio para C++/WinRT es casi igual a la de C#. En Visual Studio, puede usar la pestaña Eventos de la ventana Propiedades para agregar controladores de eventos en 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 de la Plataforma universal de Windows (UWP) que no usa XAML.

En su lugar, usa el encabezado del espacio de nombres de Windows de C++/WinRT para el espacio de nombres Windows.ApplicationModel.Core. Después de compilar y ejecutar, haz clic en un espacio vacío para agregar un cuadrado de color; luego, haz clic en un cuadrado de color para arrastrarlo.

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

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

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

Plantilla de proyecto para una aplicación cliente C++/WinRT para escritorio de Windows, que muestra una clase 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 el consumo desde una Plataforma universal de Windows (UWP).

Esta plantilla muestra la cadena de herramientas midl.exe>cppwinrt.exe, donde se generan los metadatos de Windows Runtime (.winmd) a partir de IDL y, después, se generan los códigos auxiliares de los encabezados y las implementaciones a partir de los metadatos de Windows Runtime.

En un archivo IDL, define las clases en tiempo de ejecución de tu componente, su interfaz predeterminada y cualquier otra interfaz que implementen. Compila el proyecto una sola vez para generar module.g.cpp, module.h.cpp, plantillas de implementación en Generated Files y la definición del tipo de código auxiliar en Generated Files\sources. Luego, usa estas definiciones del tipo de código auxiliar como referencia para implementar las clases en tiempo de ejecución en tu componente. Consulta Factorizar clases en tiempo de ejecución en archivos Midl (.idl).

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

Versiones anteriores de la extensión VSIX

Te recomendamos que instales la versión más reciente de la extensión VSIX (o que actualices a esta). Está configurada de forma predeterminada para actualizarse automáticamente. Si lo haces y tienes proyectos creados con una versión de la extensión VSIX anterior a 1.0.190128.4, encontrarás en esta sección información importante sobre cómo actualizar esos proyectos para que funcionen con la nueva versión. Aunque no lleves a cabo la actualización, la información de esta sección te resultará útil.

En lo que respecta a las versiones admitidas de Windows SDK y Visual Studio, así como a la configuración de Visual Studio, la información contenida en 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. La información siguiente describe diferencias importantes relacionadas con el comportamiento y la configuración de proyectos creados con anteriores versiones (o actualizados para funcionar con estas).

Proyectos creados con una versión anterior a 1.0.181002.2

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

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

Puedes actualizar el proyecto si instalas 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 proyecto en Visual Studio, haga clic en Project Administrar NuGet paquetes...Examine, escriba o pegue Microsoft.Windows. CppWinRT en el cuadro de búsqueda, seleccione el elemento en los resultados de la búsqueda y, a continuación, haga clic en Instalar para instalar el paquete para el proyecto.

Proyectos creados con una versión entre 1.0.181002.2 y 1.0.190128.3 (o actualizados a estas)

Si el proyecto se creó con una versión de la extensión VSIX entre 1.0.181002.2 y 1.0.190128.3 (ambas incluidas), la plantilla de proyecto instaló automáticamente el paquete NuGet Microsoft.Windows.CppWinRT en el proyecto. También es posible que hayas actualizado un proyecto anterior para usar una versión de la extensión VSIX de este intervalo. Si lo hizo, como la compatibilidad con la compilación también estaba presente en las versiones de la extensión VSIX en este intervalo, es posible que el proyecto actualizado tenga o no Microsoft.Windows. Paquete de NuGet CppWinRT instalado.

Para actualizar el proyecto, sigue las instrucciones de la sección anterior y asegúrate de que el 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 si no tiene también <CppWinRTEnabled>true</CppWinRTEnabled><CppWinRTEnabled>true</CppWinRTEnabled> instalado. Un proyecto con esta configuración genera el siguiente mensaje de error de compilación: "The C++/WinRT VSIX no longer provides project build support. Please add a project reference to the Microsoft.Windows.CppWinRT Nuget package" (VSIX de C++WinRT ya no proporciona compatibilidad con la compilación del proyecto. Agregue una referencia de proyecto al paquete Microsoft.Windows.CppWinRT Nuget).

Como se mencionó anteriormente, ahora los proyectos C++/WinRT deben tener instalado el paquete NuGet.

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

Además, si .vcxproj contiene <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, puedes quitarlo para compilar sin que esté instalada la extensión VSIX de C++/WinRT.

Compatibilidad del SDK con C++/WinRT

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

También por motivos de compatibilidad, Windows SDK incluye la herramienta cppwinrt.exe. Sin embargo, se recomienda instalar y usar en su lugar la versión más reciente de , que se cppwinrt.exe incluye con cppwinrt.exe Ese paquete y cppwinrt.exe se describen en las secciones anteriores.

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

En la programación de C++/WinRT, puedes 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ás algunos tipos de datos personalizados en la proyección y podrás optar por usarlos. Por ejemplo, usamos winrt::hstring en el ejemplo de código de inicio rápido de Introducción a C++/WinRT.

winrt::com_array es otro tipo que probablemente uses en algún momento, pero es menos probable que uses directamente un tipo como winrt::array_view. También puedes optar por no usarlo para no tener ningún código que cambiar si aparece un tipo equivalente en la biblioteca estándar de C++.

Advertencia

Además, hay tipos que probablemente verás si estudias detenidamente los encabezados del espacio de nombres de Windows de C++/WinRT. Un ejemplo es winrt::param::hstring, pero hay también ejemplos de colección. Estos existen solamente para optimizar el enlace de parámetros de entrada. Además, producen grandes mejoras de rendimiento y hacen que la mayoría de los patrones de llamada "solo funcionen" con contenedores y tipos de C++ estándar relacionados. La proyección solo usa estos tipos en los casos en los que agregan un mayor valor. Están muy optimizados y no están destinados a un uso general, por lo que no debes intentar usarlos. Tampoco debes usar nada del espacio de nombres winrt::impl, puesto que son tipos de implementación y, por tanto, están sujetos a cambios. Debes seguir usando los tipos estándar o los tipos del espacio de nombres winrt.

Consulta también Pasar parámetros a los límites de la ABI.

API importantes