Compartir a través de

Introducción a C++/WinRT

 

 

C++/WinRT es una proyección de lenguaje C++17 moderna totalmente estándar para las API de Windows Runtime (WinRT), implementadas como una biblioteca basada en archivos de encabezado y diseñadas para proporcionarte acceso de primera clase a la API moderna de Windows. Con C++/WinRT, puedes crear y consumir API de Windows Runtime con 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 el reemplazo recomendado de Microsoft para la proyección del lenguaje C++/CX y la Windows Runtime C++ Template Library (WRL) . La lista completa de temas de sobre C++/WinRT incluye información tanto acerca de la interoperación con como de la portabilidad desde 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 Visual Studio para 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 está diseñada para tener acceso 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 las APIs de Windows Runtime, haga clic en el cuadro combinado de Idioma en la esquina superior derecha y seleccione C++/WinRT para ver los bloques de sintaxis de API como se muestran 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 la compatibilidad con Visual Studio, 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>del desarrollo de la Plataforma Universal de Windows, compruebe la opción de herramientas de C++ (v14x) para la Plataforma Universal de Windows si no lo ha hecho ya. Y, en Configuración de> WindowsPrivacidad y seguridad (Windows 10: Actualización y seguridad) >Para desarrolladores, habilite la opción modo desarrollador (Windows 10: no la opción transferir localmente aplicaciones).

Aunque se recomienda desarrollar con las versiones más recientes de Visual Studio y Windows SDK, Si usa una versión de C++/WinRT que se incluye con Windows SDK antes de la versión 10.0.17763.0 (Windows 10, versión 1809), para usar los encabezados de espacios de nombres de Windows mencionados anteriormente, necesitará una versión de destino mínima de Windows SDK en el proyecto de 10.0.17134.0 (Windows 10, versión 1803).

Visual Studio 2022 se envía con plantillas de proyecto y elementos de C++/WinRT integrados, lo que le permite empezar a trabajar con el desarrollo de C++/WinRT de inmediato. También incluye la visualización de depuración nativa de Visual Studio (natvis) de tipos proyectados de C++/WinRT, proporcionando una experiencia similar a la depuración de C#. Natvis se aplica automáticamente a las compilaciones de depuración. Para obtener más información, consulta Visual Studio Native Debug Visualization para C++/WinRT.

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

  • 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) de tipos proyectados de C++/WinRT.

Las plantillas de proyecto de Visual Studio 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 con la compilación de C++/WinRT (propiedades y destinos de MSBuild), lo que hace 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 el proyecto existente en Visual Studio, haga clic en Project>Manage NuGet Packages...>Busque, 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 proyecto. Una vez que haya agregado el paquete, obtendrá compatibilidad de C++/WinRT con MSBuild para el proyecto, incluida la invocación de la herramienta cppwinrt.exe.

Importante

Si tiene proyectos creados con (o actualizados con) una versión de la extensión VSIX anterior a la 1.0.190128.4, consulte Versiones anteriores de la extensión VSIX. Esa sección contiene información importante sobre la configuración de los proyectos, que deberá saber para actualizarlos para usar la versión más reciente de la extensión VSIX.

  • Dado que C++/WinRT usa características del estándar de C++17, el paquete NuGet establece la propiedad del proyecto C/C++>Language>Estándar de 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 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-) al gusto. A veces, los archivos de origen generados por la cppwinrt.exe herramienta generan advertencias hasta que añades tu 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 cppwinrt.exe herramienta . Puedes usar la herramienta cppwinrt.exe en un archivo de metadatos de Windows Runtime (.winmd) para generar una biblioteca estándar de C++ basada en archivos de encabezado que proyectos las API descritas en los metadatos para su uso desde el código C++/WinRT. Los archivos de metadatos de Windows Runtime (.winmd) proporcionan una manera canónica de describir una superficie de la API de Windows Runtime. Al apuntar cppwinrt.exe a metadatos, puedes generar una biblioteca para usarla con cualquier clase en tiempo de ejecución implementada en un componente de Windows Runtime de segundo o tercer partido, o en tu propia aplicación. Para obtener más información, consulta Utilizar 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. En el caso de una clase en tiempo de ejecución, simplemente describa los tipos en un archivo IDL y midl.exe y cppwinrt.exe generan los archivos de código fuente estándar de implementación. También puede implementar interfaces derivando de una clase base de C++/WinRT. Para obtener más información, consulta API de autor con C++/WinRT.

Para obtener una lista de las opciones de personalización de la herramienta cppwinrt.exe, establézcalas a través de las propiedades del proyecto, consulte el archivo léame del paquete NuGet Microsoft.Windows.CppWinRT.

Puede identificar un proyecto que use la compatibilidad de MSBuild de C++/WinRT con la presencia de paquete NuGet microsoft.Windows.CppWinRT instalado en el proyecto.

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

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

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

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, utilice esas definiciones de tipos stub como referencia para implementar las clases locales en tiempo de ejecución. Consulte la factorización de clases de 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 para la Plataforma universal de Windows (UWP) que no usa XAML.

En su lugar, utiliza 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, 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 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 de C++/WinRT para escritorio de Windows, que muestra un Windows Runtime Windows.Foundation.Uri dentro de un cuadro de mensajes 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 midl.exe>cppwinrt.exe cadena de herramientas, donde se generan los metadatos de Windows Runtime (.winmd) a partir de IDL, y luego se generan las plantillas de implementación y encabezados 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 las definiciones de tipos stub como referencia para implementar las clases en tiempo de ejecución de su componente. Consulte la factorización de clases de tiempo de ejecución en archivos Midl (.idl).

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

Versiones anteriores de la extensión VSIX

Recomendamos que instales (o actualices a) la versión más reciente de la extensión VSIX de . 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 términos de versiones compatibles de Windows SDK y Visual Studio, y la configuración de Visual Studio, la información sobre la compatibilidad de Visual Studio con C++/WinRT, XAML, la extensión VSIX y el paquete NuGet mencionada en la sección se aplica también a versiones anteriores de la extensión VSIX de la sección anterior. 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. El 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 proyecto en Visual Studio, haga clic en Project>Manage NuGet Packages...>Busque, 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.

Creado con (o actualizado a) entre 1.0.181002.2 y 1.0.190128.3

Si el proyecto se creó con una versión de la extensión VSIX entre la 1.0.181002.2 y la 1.0.190128.3, inclusive, el paquete NuGet Microsoft.Windows.CppWinRT se instaló automáticamente en el proyecto mediante la plantilla de 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 lo hizo, dado que 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 instalado o no el Microsoft.Windows.CppWinRT paquete NuGet.

Para actualizar el proyecto, siga las instrucciones de la sección anterior y asegúrese 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 <CppWinRTEnabled>true</CppWinRTEnabled> a menos que también tenga 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 el .vcxproj contiene <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, puede optar por quitarlo para compilar sin tener que instalar la extensión de C++/WinRT VSIX.

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 Windows SDK contiene una biblioteca estándar de C++ basada en archivos de cabecera para utilizar las API de Windows (API de Windows Runtime en espacios de nombres de Windows). Esos encabezados están dentro de la carpeta %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. A partir de la versión 10.0.17763.0 de Windows SDK (Windows 10, versión 1809), estos encabezados se generan automáticamente dentro de la carpeta $(GeneratedFilesDir) del proyecto.

De nuevo por motivos de compatibilidad, Windows SDK también incluye la cppwinrt.exe herramienta . Sin embargo, se recomienda instalar y usar la versión más reciente de cppwinrt.exe, que se incluye con 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 su programación con C++/WinRT, puede utilizar las características estándar del lenguaje C++ y los tipos de datos estándar de C++ yde C++/WinRT, incluidos algunos tipos de datos de la Biblioteca Estándar de C++. Pero también conocerá algunos tipos de datos personalizados en la proyección y puede 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++.

Advertencia

También hay tipos que puede ver si estudia detenidamente los encabezados de espacio de nombres de Windows de C++/WinRT. Un ejemplo es winrt::param::hstring, pero también hay ejemplos de colecciones. Existen únicamente para optimizar el enlace de los parámetros de entrada y producen grandes mejoras de rendimiento y hacen que la mayoría de los patrones de llamada "solo funcionen" para los tipos y contenedores estándar de C++ relacionados. Estos tipos únicamente se utilizan en la proyección en casos en los que aportan más valor. Están altamente optimizados y no son para uso general; no se sientan tentados a usarlos ustedes mismos. Tampoco debe usar nada del espacio de nombres winrt::impl, ya que son tipos de implementación y, por lo tanto, sujetos a cambios. Debe seguir usando tipos estándar o tipos del espacio de nombres winrt de .

Consulte también Pasar parámetros al límite de ABI.

API importantes