Tutorial: generación de una proyección de .NET 5 desde un componente/WinRT de C++ y distribución de NuGetWalkthrough: Generate a .NET 5 projection from a C++/WinRT component and distribute the NuGet

En este tutorial se muestra cómo usar C#/WinRT para generar una proyección de .net 5 para un componente/WinRT de C++, crear el paquete de Nuget asociado y hacer referencia al paquete de Nuget desde una aplicación de consola de C# de .net 5.This walkthrough shows how to use C#/WinRT to generate a .NET 5 projection for a C++/WinRT component, create the associated NuGet package, and reference the NuGet package from a .NET 5 C# console application.

Puede descargar el ejemplo completo de este tutorial en GitHub aquí.You can download the full sample for this walkthrough from GitHub here.

Nota

Este tutorial está escrito para la versión preliminar más reciente de C#/WinRT (RC2).This walkthrough is written for the latest preview of C#/WinRT (RC2). Esperamos que la próxima versión 1,0 tenga más actualizaciones y mejoras en la experiencia del desarrollador.We expect the upcoming 1.0 release to have further updates and improvements to the developer experience.

Requisitos previosPrerequisites

Este tutorial y el ejemplo correspondiente requieren las herramientas y los componentes siguientes:This walkthrough and the corresponding sample requires the following tools and components:

Crear un componente de tiempo de ejecución de C++/WinRT simpleCreate a simple C++/WinRT Runtime component

Para seguir este tutorial, primero debe tener un componente/WinRT de C++ para el que crear una proyección de .NET 5.To follow this walkthrough, you must first have a C++/WinRT component for which to create a .NET 5 projection. En este tutorial se usa el proyecto SimpleMathComponent en el ejemplo relacionado de github aquí.This walkthrough uses the SimpleMathComponent project in the related sample from GitHub here. Se trata de un proyecto de componente de Windows Runtime (C++/WinRT) que se creó con la extensión VSIX/WinRT de c++.This is a Windows Runtime Component (C++/WinRT) project that was created by using the C++/WinRT VSIX extension. Después de copiar el proyecto en el equipo de desarrollo, abra la solución en Visual Studio 2019 versión preliminar.After you copy the project to your development computer, open the solution in Visual Studio 2019 Preview.

El código de este proyecto proporciona la funcionalidad para las operaciones matemáticas básicas que se muestran en el archivo de encabezado siguiente.The code in this project provides the functionality for basic math operations shown in the header file below.

// SimpleMath.h
...
namespace winrt::SimpleMathComponent::implementation
{
    struct SimpleMath: SimpleMathT<SimpleMath>
    {
        SimpleMath() = default;
        double add(double firstNumber, double secondNumber);
        double subtract(double firstNumber, double secondNumber);
        double multiply(double firstNumber, double secondNumber);
        double divide(double firstNumber, double secondNumber);
    };
}

Para obtener pasos más detallados sobre la creación de un componente/WinRT de C++ y la generación de un archivo. winmd, vea Windows Runtime componentes con c++/WinRT.For more detailed steps about creating a C++/WinRT component and generating a .winmd file, see Windows Runtime components with C++/WinRT.

Nota

Si está implementando IInspectable:: getruntimeclassname ( en el componente, debe devolver un nombre de clase de WinRT válido.If you are implementing IInspectable::GetRuntimeClassName in your component, it must return a valid WinRT class name. Dado que C#/WinRT usa la cadena de nombre de clase para la interoperabilidad, un nombre de clase en tiempo de ejecución incorrecto generará una excepción InvalidCastException.Because C#/WinRT uses the class name string for interop, an incorrect runtime class name will raise an InvalidCastException.

Agregar un proyecto de proyección a la solución de componentesAdd a projection project to the component solution

Si ha clonado el ejemplo del repositorio, elimine primero el proyecto SimpleMathProjection para seguir el tutorial paso a paso.If you have cloned the sample from the repo, first delete the SimpleMathProjection project to follow the walkthrough step by step.

  1. Agregue un nuevo proyecto de biblioteca de clases (.net Core) a la solución.Add a new Class Library (.NET Core) project to your solution.

    1. En Explorador de soluciones, haga clic con el botón secundario en el nodo de la solución y haga clic en Agregar -> nuevo proyecto.In Solution Explorer, right click your solution node and click Add -> New Project.
    2. En el cuadro de diálogo Agregar nuevo proyecto, busque la plantilla de proyecto biblioteca de clases (.net Core) .In the Add New Project dialog box, search for the Class Library (.NET Core) project template. Seleccione la plantilla y haga clic en siguiente.Select the template and click Next.
    3. Asigne al nuevo proyecto el nombre SimpleMathProjection y haga clic en crear.Name the new project SimpleMathProjection and click Create.
  2. Elimine el archivo Class1.CS vacío del proyecto.Delete the empty Class1.cs file from the project.

  3. Instale el paquete NuGet/WinRT de C#.Install the C#/WinRT NuGet package.

    1. En Explorador de soluciones, haga clic con el botón derecho en el proyecto SimpleMathProjection y seleccione administrar paquetes NuGet.In Solution Explorer, right click your SimpleMathProjection project and select Manage NuGet Packages.
    2. Busque el paquete NuGet Microsoft. Windows. CsWinRT e instale la versión más reciente.Search for the Microsoft.Windows.CsWinRT NuGet package and install the latest version.
  4. Agregue una referencia de proyecto al proyecto SimpleMathComponent .Add a project reference to the SimpleMathComponent project. En Explorador de soluciones, haga clic con el botón secundario en el nodo dependencias en el proyecto SimpleMathProjection , seleccione Agregar referencia de proyectoy seleccione el proyecto SimpleMathComponent .In Solution Explorer, right click the Dependencies node under the SimpleMathProjection project, select Add Project Reference, and select the SimpleMathComponent project.

    Nota

    Si usa Visual Studio 16,8 Preview 4 o una versión posterior, ha terminado con esta sección después de completar el paso 4.If you are using Visual Studio 16.8 Preview 4 or later, you are done with this section after completing step 4. Si usa Visual Studio 16,8 Preview 3, también debe completar el paso 5.If you are using Visual Studio 16.8 Preview 3, you must also complete step 5.

  5. Si usa Visual Studio 16,8 Preview 3: en Explorador de soluciones, haga doble clic en el nodo SimpleMathProjection para abrir el archivo de proyecto en el editor, agregue los siguientes elementos al archivo y, a continuación, guarde y cierre el archivo.If you're using Visual Studio 16.8 Preview 3: In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor, add the following elements to the file, and then save and close the file.

    <ItemGroup>
      <PackageReference Include="Microsoft.Net.Compilers.Toolset" Version="3.8.0-4.20472.6" />
    </ItemGroup>
    
    <PropertyGroup>
      <RestoreSources>
        https://api.nuget.org/v3/index.json;
        https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json
      </RestoreSources>
    </PropertyGroup>
    

    Estos elementos instalan la versión necesaria del paquete de NuGet Microsoft.net. compiladores. Toolset , que incluye el último compilador de C#.These elements install the required version of the Microsoft.Net.Compilers.Toolset NuGet package, which includes the latest C# compiler. En este tutorial se instala este paquete NuGet a través de estas referencias de archivo de proyecto porque es posible que la versión requerida de este paquete no esté disponible en la fuente de NuGet pública predeterminada.This walkthrough has you install this NuGet package via these project file references because the required version of this package may not be available on the default public NuGet feed.

Después de estos pasos, el Explorador de soluciones debe ser similar a este.After these steps, your Solution Explorer should look similar to this.

Explorador de soluciones que muestra las dependencias del proyecto de proyección

Editar el archivo de proyecto para ejecutar C#/WinRTEdit the project file to execute C#/WinRT

Antes de poder invocar cswinrt.exe y generar el ensamblado de proyección, debe editar el archivo de proyecto para el proyecto de proyección.Before you can invoke cswinrt.exe and generate the projection assembly, you must edit the project file for the projection project.

  1. En Explorador de soluciones, haga doble clic en el nodo SimpleMathProjection para abrir el archivo de proyecto en el editor.In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor.

  2. Actualice el TargetFramework elemento para hacer referencia al Windows SDK.Update the TargetFramework element to reference the Windows SDK. Esto agrega depedencies de ensamblado que son necesarios para la compatibilidad con la interoperabilidad y proyección.This adds assembly depedencies that are necessary for the interop and projection support. Nuestro ejemplo tiene como destino la versión más reciente de Windows 10, tal como se muestra en este tutorial, net 5.0-Windows 10.0.19041.0 (también conocido como SDK versión 2004).Our sample targets the latest Windows 10 release as of this walkthrough, net5.0-windows10.0.19041.0 (also known as SDK version 2004).

    <PropertyGroup>
      <TargetFramework>net5.0-windows10.0.19041.0</TargetFramework>
      <Platforms>x64</Platforms>
    </PropertyGroup>
    
  3. Agregue un nuevo PropertyGroup elemento que establezca varias propiedades cswinrt .Add a new PropertyGroup element that sets several cswinrt properties.

    <PropertyGroup>
      <CsWinRTIncludes>SimpleMathComponent</CsWinRTIncludes>
      <CsWinRTGeneratedFilesDir>$(OutDir)</CsWinRTGeneratedFilesDir>
    </PropertyGroup>
    

    Estos son algunos detalles sobre la configuración de este ejemplo:Here are some details about the settings in this example:

    • La CsWinRTIncludes propiedad especifica los espacios de nombres que se van a proyectar.The CsWinRTIncludes property specifies which namespaces to project.
    • La CsWinRTGeneratedFilesDir propiedad establece el directorio de salida donde se generan los archivos de la proyección, que se establecen en la sección siguiente sobre la creación fuera del origen.The CsWinRTGeneratedFilesDir property sets the output directory where files from the projection are generated, which we set in the following section on building out of source.
  4. La versión más reciente de C#/WinRT en este tutorial puede requerir la especificación de los metadatos de Windows.The latest C#/WinRT version as of this walkthrough may require specifying Windows Metadata. Esto se corregirá en una versión futura de C#/WinRT.This will be fixed in a future release of C#/WinRT. Esto se puede proporcionar con cualquiera de las siguientes opciones:This can be supplied with either:

    • Una referencia de paquete, como a Microsoft. Windows. SDK. Contracts, oA package reference, such as to Microsoft.Windows.SDK.Contracts, or

    • Un valor explícito establece con la CsWinRTWindowsMetadata propiedad:An explicit value set the with the CsWinRTWindowsMetadata property:

      <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
      
  5. Guarde y cierre el archivo SimpleMathProjection. csproj .Save and close the SimpleMathProjection.csproj file.

Compilar proyectos fuera del origenBuild projects out of source

En el ejemplo relacionado, la compilación se configura con el archivo Directory. Build. props .In the related sample, the build is configured with the Directory.build.props file. Los archivos generados de la compilación de los proyectos SimpleMathComponent y SimpleMathProjection aparecen en la carpeta _build en el nivel de solución.The generated files from building both the SimpleMathComponent and SimpleMathProjection projects appear in the _build folder at the solution level. Para configurar los proyectos para compilar fuera de origen, copie el archivo Directory. Build. props siguiente en el directorio que contiene el archivo de solución.To configure your projects to build out of source, copy the Directory.build.props file below to the directory containing your solution file.

<Project>
  <PropertyGroup>
    <BuildOutDir>$([MSBuild]::NormalizeDirectory('$(SolutionDir)_build', '$(Platform)', '$(Configuration)'))</BuildOutDir>
    <OutDir>$([MSBuild]::NormalizeDirectory('$(BuildOutDir)', '$(MSBuildProjectName)', 'bin'))</OutDir>
    <IntDir>$([MSBuild]::NormalizeDirectory('$(BuildOutDir)', '$(MSBuildProjectName)', 'obj'))</IntDir>
  </PropertyGroup>
</Project>

Aunque este paso no es necesario para generar una proyección, proporciona simplicidad generando archivos de compilación desde ambos proyectos en el mismo directorio y facilitando la limpieza de la compilación.Although this step is not required to generate a projection, it provides simplicity by generating build files from both projects in the same directory and making build cleanup easier. Tenga en cuenta que si no crea un origen, tanto SimpleMathComponent. winmd como el ensamblado de interoperabilidad SimpleMathComponent.dll se generarán en directorios diferentes en sus carpetas de proyecto respectivas.Note that if you do not build out of source, both SimpleMathComponent.winmd and the interop assembly SimpleMathComponent.dll will be generated in different directories in their respective project folders. A continuación, se hace referencia a estos archivos en SimpleMathProjection. nuspec , por lo que las rutas de acceso tendrían que cambiarse según corresponda.These files are both referenced in SimpleMathProjection.nuspec below, so the paths would have to be changed accordingly.

Creación de un paquete NuGet desde la proyecciónCreate a NuGet package from the projection

Para distribuir y usar el ensamblado de interoperabilidad, puede crear automáticamente un paquete NuGet al compilar la solución agregando algunas propiedades adicionales del proyecto.To distribute and use the interop assembly, you can automatically create a NuGet package when building the solution by adding some additional project properties. Este paquete incluirá el ensamblado de interoperabilidad y una dependencia en el paquete NuGet/WinRT de C# para el ensamblado en tiempo de ejecución de C#/WinRT requerido.This package will include the interop assembly and a dependency on the C#/WinRT NuGet package for the required C#/WinRT runtime assembly. Este ensamblado en tiempo de ejecución se denomina winrt.runtime.dll para los destinos de .net 5,0.This runtime assembly is named winrt.runtime.dll for .NET 5.0 targets.

  1. Agregue un archivo de especificación de NuGet (. nuspec) al proyecto SimpleMathProjection .Add a NuGet spec (.nuspec) file to the SimpleMathProjection project.

    1. En Explorador de soluciones, haga clic con el botón secundario en el nodo SimpleMathProjection , elija Agregar -> nueva carpetay asigne a la carpeta el nombre Nuget.In Solution Explorer, right-click the SimpleMathProjection node, choose Add -> New Folder, and name the folder nuget.
    2. Haga clic con el botón derecho en la carpeta Nuget , elija Agregar -> nuevo elemento, elija el archivo XML y asígnele el nombre SimpleMathProjection. nuspec.Right-click the nuget folder, choose Add -> New Item, choose the XML file, and name it SimpleMathProjection.nuspec.
  2. Agregue lo siguiente a SimpleMathProjection. csproj para generar automáticamente el paquete.Add the following to SimpleMathProjection.csproj to automatically generate the package. Estas propiedades especifican el NuspecFile y el directorio para generar el paquete NuGet.These properties specify the NuspecFile and the directory to generate the NuGet package.

    <PropertyGroup>
      <GeneratedNugetDir>.\nuget\</GeneratedNugetDir>
      <NuspecFile>$(GeneratedNugetDir)SimpleMathProjection.nuspec</NuspecFile>
      <OutputPath>$(GeneratedNugetDir)</OutputPath>
      <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    </PropertyGroup>
    
    
  3. Open the SimpleMathProjection.nuspec file to edit the package creation properties. Below is an example of a C++/WinRT component NuGet spec. Notice the dependency on CsWinRT for the net5.0 target framework moniker, as well as the target for lib\net5.0\SimpleMathProjection.dll, which points to the projection assembly SimpleMathComponent.dll instead of SimpleMathComponent.winmd. This behavior is new in .NET 5.0 and enabled by C#/WinRT.

    <?xml version="1.0" encoding="utf-8"?>
    <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
      <metadata>
        <id>SimpleMathComponent</id>
        <version>0.1.0-prerelease</version>
        <authors>Contoso Math Inc.</authors>
        <description>A simple component with basic math operations</description>
        <dependencies>
          <group targetFramework=".NETCoreApp3.0" />
          <group targetFramework="UAP10.0" />
          <group targetFramework=".NETFramework4.6" />
          <group targetFramework="net5.0">
            <dependency id="Microsoft.Windows.CsWinRT" version="0.8.0" exclude="Build,Analyzers" />
          </group>
        </dependencies>
      </metadata>
      <files>
        <!--Support net46+, netcore3, net5, uap, c++ -->
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\netcoreapp3.0\SimpleMathComponent.winmd" />
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\uap10.0\SimpleMathComponent.winmd" />
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\net46\SimpleMathComponent.winmd" />
        <file src="..\..\_build\x64\Debug\SimpleMathProjection\bin\SimpleMathProjection.dll" target="lib\net5.0\SimpleMathProjection.dll" />
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.dll" target="runtimes\win10-x64\native\SimpleMathComponent.dll" />
      </files>
    </package>
    

Compilar la solución para generar la proyección y el paquete NuGetBuild the solution to generate the projection and NuGet package

En este momento ya puede compilar la solución: haga clic con el botón derecho en el nodo de la solución y seleccione compilar solución.At this point you can now build the solution: right click on your solution node and select Build Solution. En primer lugar, compilará el proyecto de componente y, a continuación, el proyecto de proyección.This will first build the component project and then the projection project. Los archivos Interop . CS y el ensamblado se generarán en el directorio de salida, además de los archivos de metadatos del proyecto de componente.The interop .cs files and assembly will be generated in the output directory, in addition to the metadata files from the component project. También podrá ver el paquete NuGet generado simplemathcomponent 0.1.0-prerelease. nupkg en la carpeta NuGet .You will also be able to see the the generated NuGet package SimpleMathComponent0.1.0-prerelease.nupkg in the nuget folder.

Explorador de soluciones que muestra la generación de proyección

Referencia al paquete de NuGet en una aplicación de consola de C# .NET 5,0Reference the NuGet package in a C# .NET 5.0 console application

Para consumir el SimpleMathComponentproyectado, puede simplemente agregar una referencia al paquete de NuGet recién creado en la aplicación.To consume the projected SimpleMathComponent, you can simply add a reference to the newly created NuGet package in your application. En los pasos siguientes se muestra cómo hacerlo mediante la creación de una aplicación de consola simple en una solución independiente.The following steps demonstrate how to do this by creating a simple Console app in a separate solution.

  1. Cree una nueva solución con un proyecto de aplicación de consola (.net Core) .Create a new solution with a Console App (.NET Core) project.

    1. Abra Visual Studio, seleccione Archivo -> Nuevo -> Proyecto.In Visual Studio, select File -> New -> Project.
    2. En el cuadro de diálogo Agregar nuevo proyecto, busque la plantilla de proyecto aplicación de consola (.net Core) .In the Add New Project dialog box, search for the Console App (.NET Core) project template. Seleccione la plantilla y haga clic en siguiente.Select the template and click Next.
    3. Asigne al nuevo proyecto el nombre SampleConsoleApp y haga clic en crear.Name the new project SampleConsoleApp and click Create. La creación de este proyecto en una nueva solución le permite restaurar el paquete NuGet de SimpleMathComponent por separado.Creating this project in a new solution allows you to restore the SimpleMathComponent NuGet package separately.
  2. En Explorador de soluciones, haga doble clic en el nodo SampleConsoleApp para abrir el archivo de proyecto SampleConsoleApp. csproj y actualice el moniker y la configuración de plataforma de destino, tal como se muestra en el ejemplo siguiente.In Solution Explorer, double-click the SampleConsoleApp node to open the SampleConsoleApp.csproj project file, and update the target framework moniker and platform configuration as shown in the following example.

    <PropertyGroup>
      <TargetFramework>net5.0-windows10.0.19041.0</TargetFramework>
      <Platforms>x64</Platforms>
    </PropertyGroup>
    
  3. Agregue el paquete NuGet SimpleMathComponent al proyecto SampleConsoleApp .Add the SimpleMathComponent NuGet package to the SampleConsoleApp project. También necesitará el paquete NuGet Microsoft. VCRTForwarders. 140 , que es necesario en las aplicaciones que no están empaquetadas en un paquete MSIX.You will also need the Microsoft.VCRTForwarders.140 NuGet package, which is required in apps that are not packaged in an MSIX package. Para restaurar el SimpleMathComponent NuGet al compilar el proyecto, puede usar la RestoreSources propiedad con la ruta de acceso a la carpeta NuGet en la solución de componentes.To restore the SimpleMathComponent NuGet when building the project, you can use the RestoreSources property with the path to the nuget folder in your component solution.

    <PropertyGroup>
      <RestoreSources>
          https://api.nuget.org/v3/index.json;
          ../../CppWinRTProjectionSample/SimpleMathProjection/nuget
      </RestoreSources>
    </PropertyGroup>
    
    <ItemGroup>
        <PackageReference Include="Microsoft.VCRTForwarders.140" Version="1.0.6" />
        <PackageReference Include="SimpleMathComponent" Version="0.1.0-prerelease" />
    </ItemGroup>
    

    Tenga en cuenta que para este tutorial, la ruta de acceso de restauración de NuGet para SimpleMathComponent supone que ambos archivos de solución están en el mismo directorio.Note that for this walkthrough, the NuGet restore path for the SimpleMathComponent assumes that both solution files are in the same directory. Como alternativa, puede Agregar una fuente de paquetes de NuGet local a la solución.Alternatively, you can add a local NuGet package feed to your solution.

  4. Edite el archivo Program.CS para usar la funcionalidad proporcionada por SimpleMathComponent.Edit the Program.cs file to use the functionality provided by SimpleMathComponent.

    static void Main(string[] args)
    {
        var x = new SimpleMathComponent.SimpleMath();
        Console.WriteLine("Adding 5.5 + 6.5 ...");
        Console.WriteLine(x.add(5.5, 6.5).ToString());
    }
    
  5. Compilar y ejecutar la aplicación de consola.Build and run the console app. Debería ver la salida siguiente.You should see the output below.

    Salida de NET5 de consola

RecursosResources