Tutorial: Crear un componente de C#/WinRT y consumirlo desde C++/WinRT

C#/WinRT permite a los desarrolladores que usan .NET crear sus propios componentes de Windows Runtime en C# mediante un proyecto de biblioteca de clases. Los componentes creados se pueden consumir en aplicaciones de escritorio nativas como referencia de paquete o como referencia de proyecto con algunas modificaciones.

En este tutorial se muestra cómo crear un componente sencillo de Windows Runtime mediante C#/WinRT, distribuir el componente como un paquete NuGet y consumir el componente desde una aplicación de consola de C++/WinRT. Para obtener el ejemplo completo que proporciona el código de este artículo, consulte el ejemplo de autoría de C#/WinRT de . Para obtener más información sobre la autoría, consulte Componentes de autoría.

Para ver un tutorial sobre la creación de controles WinUI con C#/WinRT específicamente para su uso en aplicaciones de Windows App SDK, consulte el artículo Tutorial: Creación de un componente de C# con controles WinUI 3 y consumo desde una aplicación de Windows App SDK de C++

Prerrequisitos

Este tutorial requiere las siguientes herramientas y componentes:

• Visual Studio 2022
• SDK de .NET 6.0 o posterior
• VSIX de C++/WinRT para plantillas de proyecto de C++/WinRT

Crear un componente sencillo de Windows Runtime con C#/WinRT

Empiece por crear un nuevo proyecto en Visual Studio. Seleccione la plantilla de proyecto Biblioteca de Clases y asigne al proyecto el nombre AuthoringDemo. Deberá realizar las siguientes adiciones y modificaciones al proyecto:

1. TargetFramework Actualice en el archivo AuthoringDemo.csproj y agregue los siguientes elementos a PropertyGroup:

   <PropertyGroup>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
       <Platforms>x64</Platforms>
   </PropertyGroup>
   

   Para acceder a los tipos de Windows Runtime, debe establecer una versión específica de Windows SDK en el TFM. Para obtener más información sobre la versión compatible, consulte .NET 6 y versiones posteriores: Uso de la opción TFM.

2. Instale el paquete NuGet Microsoft.Windows.CsWinRT en tu proyecto.

   a) En el Explorador de soluciones, haga clic con el botón derecho en el nodo del proyecto y seleccione Administrar paquetes NuGet.

   b. Busque el paquete NuGet Microsoft.Windows.CsWinRT e instale la versión más reciente. En este tutorial se usa C#/WinRT versión 1.4.1.

3. Agregue un nuevo PropertyGroup elemento que establezca la CsWinRTComponent propiedad . Esto especifica que el proyecto es un componente de Windows Runtime para que se genere un .winmd archivo al compilar el proyecto.

   <PropertyGroup>   
       <CsWinRTComponent>true</CsWinRTComponent>
   </PropertyGroup>
   

   Para obtener una lista completa de las propiedades del proyecto de C#/WinRT, consulte la documentación de NuGet de C#/WinRT.

4. Puede crear sus clases en tiempo de ejecución mediante los archivos de clase de la biblioteca .cs. Haga clic con el botón derecho en el Class1.cs archivo y cámbielo por Example.cs. Agregue el código siguiente a este archivo, que agrega una propiedad pública y un método a la clase en tiempo de ejecución. Recuerde marcar las clases que quiera exponer en el componente en tiempo de ejecución como public.

   namespace AuthoringDemo
   {
       public sealed class Example
       {
           public int SampleProperty { get; set; }
   
           public static string SayHello()
           {
               return "Hello from your C# WinRT component";
           }
       }
   }
   

5. Ahora puede compilar el proyecto para generar el archivo para el .winmd componente. Seleccione el proyecto en Explorador de solucioneshaciendo clic con el botón derecho, y luego haga clic en Compilar. Verá el archivo generado AuthoringDemo.winmd en la carpeta de salida de compilación.

Generación de un paquete NuGet para el componente

La mayoría de los desarrolladores querrán distribuir y compartir su componente de Windows Runtime como un paquete NuGet. Otra opción es consumir el componente como referencia de proyecto. En los siguientes pasos se muestra cómo empaquetar el componente AuthoringDemo. Al generar el paquete, C#/WinRT configura el componente y los ensamblados de host en el paquete para permitir su consumo desde aplicaciones nativas.

Hay varias maneras de generar el paquete NuGet:

• Si desea generar un paquete NuGet cada vez que compile el proyecto, agregue la siguiente propiedad al archivo de proyecto AuthoringDemo y vuelva a generar el proyecto.

  <PropertyGroup>
      <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
  

• Como alternativa, puede generar un paquete NuGet haciendo clic con el botón derecho en el proyecto AuthoringDemo en el Explorador de soluciones y seleccionando Pack.

Cuando se construya el paquete, la ventana Compilación debe indicar que el paquete NuGet AuthoringDemo.1.0.0.nupkg se creó correctamente. Consulte Creación de un paquete mediante la CLI de dotnet para obtener más información sobre las propiedades del paquete NuGet con la CLI de .NET.

Consumo del componente desde una aplicación de C++/WinRT

Los componentes de Windows Runtime creados por C#/WinRT se pueden consumir desde cualquier lenguaje compatible con Windows Runtime (WinRT). En los pasos siguientes se muestra cómo llamar al componente creado anteriormente en una aplicación de consola de C++/WinRT.

1. Agregue un nuevo proyecto de aplicación de consola C++/WinRT a su solución. Tenga en cuenta que este proyecto también puede formar parte de una solución diferente si lo elige.

   a) En Explorador de soluciones, haga clic con el botón derecho en el nodo de la solución y luego en Agregar ->Nuevo Proyecto.

   b. En el cuadro de diálogo Agregar nuevo proyecto, busque la plantilla de proyecto Aplicación de Consola C++/WinRT. Seleccione la plantilla y haga clic en Siguiente.

   c. Asigne al nuevo proyecto el nombre CppConsoleApp y haga clic en Crear.

2. Agregue una referencia al componente AuthoringDemo, ya sea como un paquete NuGet o una referencia de proyecto.

   • Opción 1 (Referencia del paquete)::

     a) Haga clic con el botón derecho en el proyecto CppConsoleApp y seleccione Administrar paquetes NuGet. Es posible que necesite configurar las fuentes de su paquete para añadir una referencia al paquete NuGet "AuthoringDemo". Para ello, haz clic en el icono de Configuración en el Administrador de paquetes NuGet y añade un origen de paquete a la ruta adecuada.

     

     b. Después de configurar los orígenes del paquete, busque el paquete AuthoringDemo y haga clic en Instalar.

     

   • Opción 2 (referencia del proyecto)::

     a) Haga clic con el botón derecho en el proyecto de CppConsoleApp y seleccione Agregar ->Referencia. En el nodo Proyectos, agregue una referencia al proyecto AuthoringDemo.

3. Para hospedar el componente, deberá agregar un archivo de manifiesto para los registros de clases activables. Para más información sobre el hospedaje de componentes administrados, consulte Hospedaje de componentes administrados.

   a) Para agregar el archivo de manifiesto, vuelva a hacer clic con el botón derecho en el proyecto y elija Agregar -> Nuevo elemento. Busque la plantilla Archivo de texto y asígnela el nombre CppConsoleApp.exe.manifest. Pegue el siguiente contenido, que especifica las clases en tiempo de ejecución mediante entradas de registro de clases activables:

   <?xml version="1.0" encoding="utf-8"?>
   <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
       <assemblyIdentity version="1.0.0.0" name="CppConsoleApp"/>
       <file name="WinRT.Host.dll">
           <activatableClass
               name="AuthoringDemo.Example"
               threadingModel="both"
               xmlns="urn:schemas-microsoft-com:winrt.v1" />
       </file>
   </assembly>
   

   El archivo de manifiesto de aplicación es necesario para las aplicaciones que no están empaquetadas. En el caso de las aplicaciones empaquetadas, el consumidor de aplicaciones debe registrar las clases activables en el archivo de manifiesto del paquete Package.appxmanifest, como se explica en Tutorial: Crear un componente de C# con controles WinUI 3 y consumirlo en una aplicación de SDK de Windows de C++.

   b. Modifique el proyecto para incluir el archivo de manifiesto en la salida al implementar el proyecto. Haga clic en el archivo .manifest de CppConsoleApp.exeen Solution Explorer y establezca la propiedad Content de en True. Este es un ejemplo de cómo se ve esto.

   

4. Abra pch.h en los archivos de encabezado del proyecto y agregue la siguiente línea de código para incluir el componente.

   #include <winrt/AuthoringDemo.h>
   

5. Abra main.cpp en los archivos de código fuente del proyecto y reemplácelo por el siguiente contenido.

   #include "pch.h"
   #include "iostream"
   
   using namespace winrt;
   using namespace Windows::Foundation;
   
   int main()
   {
       init_apartment();
   
       AuthoringDemo::Example ex;
       ex.SampleProperty(42);
       std::wcout << ex.SampleProperty() << std::endl;
       std::wcout << ex.SayHello().c_str() << std::endl;
   }
   

6. Compile y ejecute el proyecto CppConsoleApp . Ahora debería ver la salida siguiente.

   salida de la consola de C++/WinRT

Temas relacionados

• Código de ejemplo
• componentes de autoría
• Hosting de componentes gestionados