Walkthrough: gerar uma projeção do .NET 5 de um componente/WinRT do C++ e distribuir o NuGetWalkthrough: Generate a .NET 5 projection from a C++/WinRT component and distribute the NuGet

Este tutorial mostra como usar o C#/WinRT para gerar uma projeção do .NET 5 para um componente/WinRT do C++, criar o pacote NuGet associado e referenciar o pacote NuGet de um aplicativo de console do .NET 5 C#.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.

Você pode baixar o exemplo completo deste passo a passos do GitHub aqui.You can download the full sample for this walkthrough from GitHub here.

Observação

Este tutorial foi escrito para a versão prévia mais recente do C#/WinRT (RC2).This walkthrough is written for the latest preview of C#/WinRT (RC2). Esperamos que a próxima versão de 1,0 tenha mais atualizações e aprimoramentos na experiência do desenvolvedor.We expect the upcoming 1.0 release to have further updates and improvements to the developer experience.

Pré-requisitosPrerequisites

Este passo a passos e o exemplo correspondente exigem as seguintes ferramentas e componentes:This walkthrough and the corresponding sample requires the following tools and components:

Criar um componente simples de tempo de execução C++/WinRTCreate a simple C++/WinRT Runtime component

Para seguir este passo a passos, você deve primeiro ter um componente C++/WinRT para o qual criar uma projeção do .NET 5.To follow this walkthrough, you must first have a C++/WinRT component for which to create a .NET 5 projection. Este tutorial usa o projeto SimpleMathComponent no exemplo relacionado do GitHub aqui.This walkthrough uses the SimpleMathComponent project in the related sample from GitHub here. Este é um projeto de componente Windows Runtime (C++/WinRT) que foi criado usando a extensão VSIX/WinRT do c++.This is a Windows Runtime Component (C++/WinRT) project that was created by using the C++/WinRT VSIX extension. Depois de copiar o projeto para o computador de desenvolvimento, abra a solução no Visual Studio 2019 Preview.After you copy the project to your development computer, open the solution in Visual Studio 2019 Preview.

O código neste projeto fornece a funcionalidade para operações matemáticas básicas mostradas no arquivo de cabeçalho abaixo.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 obter etapas mais detalhadas sobre como criar um componente/WinRT do C++ e gerar um arquivo. winmd, consulte Windows Runtime Components with C++/WinRT.For more detailed steps about creating a C++/WinRT component and generating a .winmd file, see Windows Runtime components with C++/WinRT.

Observação

Se você estiver implementando IInspectable:: GetRuntimeClassName em seu componente, ele deverá retornar um nome de classe WinRT válido.If you are implementing IInspectable::GetRuntimeClassName in your component, it must return a valid WinRT class name. Como C#/WinRT usa a cadeia de caracteres de nome de classe para interoperabilidade, um nome de classe de tempo de execução incorreto gerará uma InvalidCastException.Because C#/WinRT uses the class name string for interop, an incorrect runtime class name will raise an InvalidCastException.

Adicionar um projeto de projeção à solução de componenteAdd a projection project to the component solution

Se você clonar o exemplo do repositório, primeiro exclua o projeto SimpleMathProjection para seguir o passo a passo.If you have cloned the sample from the repo, first delete the SimpleMathProjection project to follow the walkthrough step by step.

  1. Adicione um novo projeto de biblioteca de classes (.NET Core) à sua solução.Add a new Class Library (.NET Core) project to your solution.

    1. Em Gerenciador de soluções, clique com o botão direito do mouse no nó da solução e clique em Adicionar -> novo projeto.In Solution Explorer, right click your solution node and click Add -> New Project.
    2. Na caixa de diálogo Adicionar novo projeto, pesquise o modelo de projeto da biblioteca de classes (.NET Core) .In the Add New Project dialog box, search for the Class Library (.NET Core) project template. Selecione o modelo e clique em Avançar.Select the template and click Next.
    3. Nomeie o novo projeto SimpleMathProjection e clique em criar.Name the new project SimpleMathProjection and click Create.
  2. Exclua o arquivo Class1.cs vazio do projeto.Delete the empty Class1.cs file from the project.

  3. Instale o pacote NuGet do C#/WinRT.Install the C#/WinRT NuGet package.

    1. Em Gerenciador de soluções, clique com o botão direito do mouse no projeto SimpleMathProjection e selecione gerenciar pacotes NuGet.In Solution Explorer, right click your SimpleMathProjection project and select Manage NuGet Packages.
    2. Procure o pacote NuGet Microsoft. Windows. CsWinRT e instale a versão mais recente.Search for the Microsoft.Windows.CsWinRT NuGet package and install the latest version.
  4. Adicione uma referência de projeto ao projeto SimpleMathComponent .Add a project reference to the SimpleMathComponent project. Em Gerenciador de soluções, clique com o botão direito do mouse no nó dependências no projeto SimpleMathProjection , selecione Adicionar referência de projetoe selecione o projeto SimpleMathComponent .In Solution Explorer, right click the Dependencies node under the SimpleMathProjection project, select Add Project Reference, and select the SimpleMathComponent project.

    Observação

    Se você estiver usando o Visual Studio 16,8 Preview 4 ou posterior, você concluirá esta seção depois de concluir a etapa 4.If you are using Visual Studio 16.8 Preview 4 or later, you are done with this section after completing step 4. Se você estiver usando o Visual Studio 16,8 Preview 3, também deverá concluir a etapa 5.If you are using Visual Studio 16.8 Preview 3, you must also complete step 5.

  5. Se você estiver usando o Visual Studio 16,8 Preview 3: em Gerenciador de soluções, clique duas vezes no nó SimpleMathProjection para abrir o arquivo de projeto no editor, adicione os seguintes elementos ao arquivo e, em seguida, salve e feche o arquivo.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>
    

    Esses elementos instalam a versão necessária do pacote do NuGet Microsoft.net. compilers. Toolset , que inclui o compilador C# mais recente.These elements install the required version of the Microsoft.Net.Compilers.Toolset NuGet package, which includes the latest C# compiler. Este tutorial tem a instalação deste pacote NuGet por meio dessas referências de arquivo de projeto porque a versão necessária desse pacote pode não estar disponível no feed NuGet público padrão.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.

Após essas etapas, sua Gerenciador de soluções deve ser semelhante a esta.After these steps, your Solution Explorer should look similar to this.

Gerenciador de Soluções mostrando dependências de projeto de projeção

Editar o arquivo de projeto para executar C#/WinRTEdit the project file to execute C#/WinRT

Antes de poder invocar cswinrt.exe e gerar o assembly de projeção, você deve editar o arquivo de projeto para o projeto de projeção.Before you can invoke cswinrt.exe and generate the projection assembly, you must edit the project file for the projection project.

  1. Em Gerenciador de soluções, clique duas vezes no nó SimpleMathProjection para abrir o arquivo de projeto no editor.In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor.

  2. Atualize o TargetFramework elemento para fazer referência à SDK do Windows.Update the TargetFramework element to reference the Windows SDK. Isso adiciona depedencies de assembly que são necessários para o suporte de interoperabilidade e projeção.This adds assembly depedencies that are necessary for the interop and projection support. Nosso exemplo tem como alvo a versão mais recente do Windows 10, a partir deste passo a passos, net 5.0-Windows 10.0.19041.0 (também conhecido como SDK versão 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. Adicione um novo PropertyGroup elemento que define várias propriedades cswinrt .Add a new PropertyGroup element that sets several cswinrt properties.

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

    Aqui estão alguns detalhes sobre as configurações neste exemplo:Here are some details about the settings in this example:

    • A CsWinRTIncludes propriedade especifica quais namespaces projetar.The CsWinRTIncludes property specifies which namespaces to project.
    • A CsWinRTGeneratedFilesDir propriedade define o diretório de saída onde os arquivos da projeção são gerados, que definimos na seção a seguir sobre a compilação da origem.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. A versão mais recente do C#/WinRT a partir deste passo a passos pode exigir a especificação de metadados do Windows.The latest C#/WinRT version as of this walkthrough may require specifying Windows Metadata. Isso será corrigido em uma versão futura do C#/WinRT.This will be fixed in a future release of C#/WinRT. Isso pode ser fornecido com:This can be supplied with either:

    • Uma referência de pacote, como Microsoft. Windows. Sdk. ContractsouA package reference, such as to Microsoft.Windows.SDK.Contracts, or

    • Um valor explícito define o com a CsWinRTWindowsMetadata Propriedade:An explicit value set the with the CsWinRTWindowsMetadata property:

      <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
      
  5. Salve e feche o arquivo SimpleMathProjection. csproj .Save and close the SimpleMathProjection.csproj file.

Compilar projetos fora da origemBuild projects out of source

No exemplo relacionado, a compilação é configurada com o arquivo Directory. Build. props .In the related sample, the build is configured with the Directory.build.props file. Os arquivos gerados da criação dos projetos SimpleMathComponent e SimpleMathProjection aparecem na pasta _Build no nível da solução.The generated files from building both the SimpleMathComponent and SimpleMathProjection projects appear in the _build folder at the solution level. Para configurar seus projetos para compilação fora da origem, copie o arquivo Directory. Build. props abaixo para o diretório que contém o arquivo de solução.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>

Embora essa etapa não seja necessária para gerar uma projeção, ela fornece simplicidade gerando arquivos de compilação de ambos os projetos no mesmo diretório e facilitando a limpeza da compilação.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. Observe que, se você não compilar a origem, o SimpleMathComponent. winmd e o assembly de interoperabilidade SimpleMathComponent.dll serão gerados em diretórios diferentes em suas respectivas pastas de projeto.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. Esses arquivos são referenciados em SimpleMathProjection. nuspec abaixo, portanto, os caminhos teriam que ser alterados de acordo.These files are both referenced in SimpleMathProjection.nuspec below, so the paths would have to be changed accordingly.

Criar um pacote NuGet a partir da projeçãoCreate a NuGet package from the projection

Para distribuir e usar o assembly de interoperabilidade, você pode criar automaticamente um pacote NuGet ao compilar a solução adicionando algumas propriedades de projeto adicionais.To distribute and use the interop assembly, you can automatically create a NuGet package when building the solution by adding some additional project properties. Esse pacote incluirá o assembly de interoperabilidade e uma dependência no pacote NuGet do C#/WinRT para o assembly de tempo de execução C#/WinRT necessário.This package will include the interop assembly and a dependency on the C#/WinRT NuGet package for the required C#/WinRT runtime assembly. Esse assembly de tempo de execução é nomeado winrt.runtime.dll para destinos do .NET 5,0.This runtime assembly is named winrt.runtime.dll for .NET 5.0 targets.

  1. Adicione um arquivo de especificação NuGet (. nuspec) ao projeto SimpleMathProjection .Add a NuGet spec (.nuspec) file to the SimpleMathProjection project.

    1. Em Gerenciador de soluções, clique com o botão direito do mouse no nó SimpleMathProjection , escolha Adicionar -> nova pastae nomeie a pasta NuGet.In Solution Explorer, right-click the SimpleMathProjection node, choose Add -> New Folder, and name the folder nuget.
    2. Clique com o botão direito do mouse na pasta NuGet , escolha Adicionar -> novo item, escolha o arquivo XML e nomeie-o SimpleMathProjection. nuspec.Right-click the nuget folder, choose Add -> New Item, choose the XML file, and name it SimpleMathProjection.nuspec.
  2. Adicione o seguinte a SimpleMathProjection. csproj para gerar automaticamente o pacote.Add the following to SimpleMathProjection.csproj to automatically generate the package. Essas propriedades especificam o NuspecFile e o diretório para gerar o pacote 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 a solução para gerar a projeção e o pacote NuGetBuild the solution to generate the projection and NuGet package

Neste ponto, agora você pode criar a solução: clique com o botão direito do mouse no nó da solução e selecione Compilar solução.At this point you can now build the solution: right click on your solution node and select Build Solution. Isso criará primeiro o projeto de componente e, em seguida, o projeto de projeção.This will first build the component project and then the projection project. Os arquivos Interop . cs e o assembly serão gerados no diretório de saída, além dos arquivos de metadados do projeto 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. Você também poderá ver o pacote NuGet gerado simplemathcomponent 0.1.0-prerelease. nupkg na pasta NuGet .You will also be able to see the the generated NuGet package SimpleMathComponent0.1.0-prerelease.nupkg in the nuget folder.

Gerenciador de Soluções mostrando a geração de projeção

Referenciar o pacote NuGet em um aplicativo de console do .NET 5,0 em C#Reference the NuGet package in a C# .NET 5.0 console application

Para consumir o SimpleMathComponentprojetado, você pode simplesmente adicionar uma referência ao pacote do NuGet recém-criado em seu aplicativo.To consume the projected SimpleMathComponent, you can simply add a reference to the newly created NuGet package in your application. As etapas a seguir demonstram como fazer isso criando um aplicativo de console simples em uma solução separada.The following steps demonstrate how to do this by creating a simple Console app in a separate solution.

  1. Crie uma nova solução com um projeto de aplicativo de console (.NET Core) .Create a new solution with a Console App (.NET Core) project.

    1. No Visual Studio, selecione Arquivo -> Novo -> Projeto.In Visual Studio, select File -> New -> Project.
    2. Na caixa de diálogo Adicionar novo projeto, procure o modelo de projeto aplicativo de console (.NET Core) .In the Add New Project dialog box, search for the Console App (.NET Core) project template. Selecione o modelo e clique em Avançar.Select the template and click Next.
    3. Nomeie o novo projeto SampleConsoleApp e clique em criar.Name the new project SampleConsoleApp and click Create. A criação desse projeto em uma nova solução permite que você restaure o pacote NuGet do SimpleMathComponent separadamente.Creating this project in a new solution allows you to restore the SimpleMathComponent NuGet package separately.
  2. Em Gerenciador de soluções, clique duas vezes no nó SampleConsoleApp para abrir o arquivo de projeto SampleConsoleApp. csproj e atualize o moniker da estrutura de destino e a configuração da plataforma, conforme mostrado no exemplo a seguir.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. Adicione o pacote NuGet SimpleMathComponent ao projeto SampleConsoleApp .Add the SimpleMathComponent NuGet package to the SampleConsoleApp project. Você também precisará do pacote NuGet Microsoft. VCRTForwarders. 140 , que é necessário em aplicativos que não são empacotados em um pacote 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 o NuGet do SimpleMathComponent ao compilar o projeto, você pode usar a RestoreSources propriedade com o caminho para a pasta do NuGet em sua solução de componente.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>
    

    Observe que, para este passo a passos, o caminho de restauração do NuGet para o SimpleMathComponent pressupõe que ambos os arquivos de solução estejam no mesmo diretório.Note that for this walkthrough, the NuGet restore path for the SimpleMathComponent assumes that both solution files are in the same directory. Como alternativa, você pode Adicionar um feed de pacote NuGet local à sua solução.Alternatively, you can add a local NuGet package feed to your solution.

  4. Edite o arquivo Program.cs para usar a funcionalidade fornecida pelo 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. Compile e execute o aplicativo de console.Build and run the console app. Você deve ver a saída abaixo.You should see the output below.

    Saída de NET5 do console

RecursosResources