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

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

En este tutorial se muestra cómo crear un componente simple 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 creación de C#/WinRT. Para obtener más información sobre la creación, consulte Componentes de creación.

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

Requisitos previos

En este tutorial se requieren los siguientes componentes y herramientas:

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

Creación de un componente de Windows Runtime sencillo de C++/WinRT

Comience creando un nuevo proyecto en Visual Studio. Seleccione la plantilla de proyecto Biblioteca de clases y póngale al proyecto el nombre AuthoringDemo. Deberá realizar las siguientes adiciones y modificaciones en el proyecto:

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

   <PropertyGroup>
       <TargetFramework>net6.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: Usar la opción TFM.

2. Instale el paquete NuGet Microsoft.Windows.CsWinRT en el 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 última versión. En este tutorial se usa la versión 1.4.1 de C#/WinRT.

3. Agregue un nuevo elemento PropertyGroup que establezca la propiedad CsWinRTComponent. Esto especifica que el proyecto es un componente de Windows Runtime, por lo que se genera un archivo .winmd cuando compila el componente.

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

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

4. Puede crear las clases en tiempo de ejecución mediante archivos de clase de biblioteca .cs. Haga clic con el botón derecho en el archivo Class1.cs y cámbiele el nombre a 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. No olvide 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 de .winmd para el componente. Haga clic con el botón derecho en el proyecto del Explorador de soluciones y seleccione 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 pasos siguientes se muestra cómo empaquetar el componente AuthoringDemo. Al generar el paquete, C#/WinRT configura el componente y hospeda ensamblados en el paquete para permitir su consumo desde aplicaciones nativas.

Hay varias maneras de generar el paquete NuGet:

• Si quiere generar un paquete NuGet cada vez que compila el proyecto, agregue la siguiente propiedad al archivo de proyecto AuthoringDemo y luego vuelva a compilar 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 Paquete.

Al compilar el paquete, la ventana Compilar debe indicar que el paquete NuGet AuthoringDemo.1.0.0.nupkg se creó correctamente. Consulte Crear 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 Runtime Windows creados en 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.

Nota:

El consumo de un componente de C#/WinRT desde aplicaciones de C#/.NET es compatible con la referencia de paquete o la referencia de proyecto. Este escenario equivale a consumir cualquier biblioteca de clases de C# normal y no implica la activación de WinRT en la mayoría de los casos. A partir de C#/WinRT 1.3.5, las referencias de proyecto para los consumidores de C# requieren .NET 6.

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 así lo decide.

   a. En el Explorador de soluciones, haga clic con el botón derecho en el nodo de la solución y seleccione 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. Nombre el nuevo proyecto 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 tenga que configurar los orígenes de paquetes para agregar una referencia al paquete NuGet AuthoringDemo. Para ello, haga clic en el icono Configuración en el Administrador de paquetes NuGet y agregue un origen de paquete a la ruta de acceso apropiada.

     

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

     

   • Opción 2 (referencia de proyecto):

     a. Haga clic con el botón derecho en el proyecto 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 obtener 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 póngale 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. Para las aplicaciones empaquetadas, el consumidor de aplicaciones debe registrar las clases activables en su archivo de manifiesto de paquete Package.appxmanifest, como se explica en Tutorial: Crear un componente de C# con controles WinUI 3 y consumir desde una aplicación de SDK de aplicación Windows C++.

   b. Modifique el proyecto para incluir el archivo de manifiesto en la salida al implementar el proyecto. Haga clic en el archivo CppConsoleApp.exe.manifest en el Explorador de soluciones y establezca la propiedad Content en True. A continuación se muestra un ejemplo del aspecto que tiene.

   

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

   #include <winrt/AuthoringDemo.h>
   

5. Abra main.cpp en los archivos de origen del proyecto y reemplácelo con 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. Debería ver el resultado siguiente.

   

Temas relacionados

• Código de ejemplo
• Componentes de creación
• Hospedaje de componentes administrados