Gerar uma projeção em C# de um componente C++/WinRT, distribuir como um NuGet para aplicativos .NET

Neste tópico, cobrimos o uso do C#/WinRT para gerar um assembly de projeção de C# .NET (ou de interoperabilidade) a partir de um componente Windows Runtime C++/WinRT e como distribuí-lo como um pacote NuGet para aplicativos .NET.

Em .NET 6 e posteriores, o consumo de arquivos winMD (metadados Windows) não tem mais suporte (consulte O suporte embutido para WinRT é removido do .NET). Em vez disso, a ferramenta C#/WinRT pode ser usada para gerar um assembly de projeção para qualquer arquivo WinMD, o que permite o consumo de componentes WinRT de aplicativos .NET. Assemblagem de projeção também é conhecida como assemblagem de interoperabilidade. Este passo a passo mostra como fazer o seguinte:

• Use o pacote C#/WinRT para gerar uma projeção em C# de um componente C++/WinRT.
• Distribua o componente, juntamente com o conjunto de projeção, como um pacote NuGet.
• Utilize o pacote NuGet em uma aplicação de console .NET.

Pré-requisitos

Este passo a passo e o exemplo correspondente exigem as seguintes ferramentas e componentes:

• Visual Studio 2022 ou posterior com a carga de trabalho de desenvolvimento Plataforma Universal do Windows instalada. Em Installation Details>Plataforma Universal do Windows development, verifique a opção ferramentas C++ (v14x) para Plataforma Universal do Windows.
• .NET LTS (SDK 8.0) ou posterior.

Usaremos Visual Studio 2022 ou posterior e .NET 8 neste passo a passo.

Criar um componente de Windows Runtime C++/WinRT simples

Para seguir este passo a passo, você deve ter previamente um componente Windows Runtime C++/WinRT (WRC) a partir do qual gerará o assembly de projeção para C#.

Este tutorial usa o SimpleMathComponent WRC da amostra de projeção C#/WinRT no GitHub, que você já baixou ou clonou. SimpleMathComponent foi criado a partir do modelo de projeto Windows Runtime Component (C++/WinRT) Visual Studio.

Para abrir o projeto SimpleMathComponent no Visual Studio, abra o arquivo \CsWinRT\src\Samples\NetProjectionSample\CppWinRTComponentProjectionSample.sln, que você encontrará no download ou clone do repositório.

O código neste projeto fornece a funcionalidade para as operações matemáticas básicas mostradas no arquivo de cabeçalho abaixo.

// 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);
    };
}

Você pode confirmar que a propriedade Windows Desktop Compatible está definida como Yes para o projeto de componente SimpleMathComponent Windows Runtime C++/WinRT. Para fazer isso, nas propriedades do projeto para SimpleMathComponent, em Configuration Properties>General>Project Defaults, defina a propriedade Windows Desktop Compatible como Sim. Isso garante que os binários de runtime corretos sejam carregados para consumir aplicativos .NET da área de trabalho.

Para obter etapas mais detalhadas sobre como criar um componente C++/WinRT e gerar um arquivo WinMD, consulte Windows Runtime componentes com C++/WinRT.

Adicionar um projeto de projeção à solução de componente

Primeiro, com a solução CppWinRTComponentProjectionSample ainda aberta no Visual Studio, remova o projeto SimpleMathProjection dessa solução. Em seguida, exclua do sistema de arquivos a pasta SimpleMathProjection (ou renomeie-a se preferir). Essas etapas são necessárias para que você possa seguir este passo a passo.

1. Adicione um novo projeto de biblioteca C# à sua solução.

   1. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó da solução e clique em Add>New Project.
   2. Na caixa de diálogo Adicionar um novo projeto, digite Biblioteca de Classes na caixa de pesquisa. Escolha C# na lista de idiomas e escolha Windows na lista de plataformas. Escolha o modelo de projeto do C# simplesmente chamado Biblioteca de Classes (sem qualquer prefixo ou sufixo) e clique em Avançar.
   3. Nomeie o novo projeto SimpleMathProjection. O local provavelmente já está configurado para a mesma pasta \CsWinRT\src\Samples\NetProjectionSample na qual a pasta SimpleMathComponent está; mas confirme. Em seguida, clique em Próximo.
   4. Na página Additional information, selecione .NET 8.0 (suporte de longo prazo) e escolha Create.

2. Exclua o stub Class1.cs arquivo do projeto.

3. Use as etapas abaixo para instalar o pacote NuGet C#/WinRT.

   1. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto SimpleMathProjection e selecione Manage NuGet Packages.
   2. Na guia Browse, digite ou cole Microsoft.Windows. CsWinRT na caixa de pesquisa, nos resultados da pesquisa, selecione o item com a versão mais recente e clique em Install para instalar o pacote no projeto SimpleMathProjection.

4. Adicione a SimpleMathProjection uma referência de projeto ao projeto SimpleMathComponent . Em Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependencies sob o nó do projeto SimpleMathProjection, selecione Adicionar Referência de Projeto e selecione o projeto SimpleMathComponent>OK.

Não tente criar o projeto ainda. Faremos isso mais tarde.

Até agora, seu Gerenciador de Soluções deve ser semelhante a isso (seus números de versão serão diferentes).

Criar projetos a partir do código-fonte

Para a solução CppWinRTComponentProjectionSample na amostra de projeção C#/WinRT (que você baixou ou clonou do GitHub e agora está aberta), o local de saída do build é configurado com o arquivo Directory.Build.props para compilar fora da fonte. Isso significa que os arquivos da saída de build são gerados fora da pasta de origem. Recomendamos que você compile fora do código-fonte ao usar a ferramenta C#/WinRT. Isso impede que o compilador C# pegue inadvertidamente todos os arquivos *.cs no diretório raiz do projeto, o que pode causar erros de tipo duplicados (por exemplo, ao compilar para várias configurações e/ou plataformas).

Embora isso já esteja configurado para a solução CppWinRTComponentProjectionSample, siga as etapas abaixo para praticar a configuração por conta própria.

Para configurar sua solução para compilar fora do código-fonte:

1. Com a solução CppWinRTComponentProjectionSample ainda aberta, clique com o botão direito do mouse no nó da solução e selecione AdicionarNovo Item. Selecione o item Arquivo XML e nomeie-o Directory.Build.props (sem uma extensão .xml). Clique em Sim para substituir o arquivo existente.

2. Substitua o conteúdo do Directory.Build.props pela configuração abaixo.

   <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>
   

3. Salve e feche o arquivo Directory.Build.props .

Editar o arquivo de projeto para executar C#/WinRT

Antes de invocar a cswinrt.exe ferramenta para gerar o assembly de projeção, primeiro edite o arquivo de projeto para especificar algumas propriedades do projeto.

1. Em Gerenciador de Soluções, clique duas vezes no nó SimpleMathProjection para abrir o arquivo de projeto no editor.

2. Atualize o elemento TargetFramework para direcionar uma versão específica do SDK Windows. Isso adiciona dependências de assembly necessárias para o suporte à interoperabilidade e à projeção. Este exemplo tem como destino a versão do SDK Windows net6.0-windows10.0.19041.0 (também conhecida como Windows 10, versão 2004). Defina o elemento Platform como AnyCPU para que o assembly de projeção resultante possa ser referenciado de qualquer arquitetura de aplicativo. Para permitir que os aplicativos de referência ofereçam suporte a versões anteriores do SDK Windows, você também pode definir a propriedade TargetPlatformMinimumVersion.

   <PropertyGroup>
     <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     <!-- Set Platform to AnyCPU to allow consumption of the projection assembly from any architecture. -->
     <Platform>AnyCPU</Platform>
   </PropertyGroup>
   

   Observação

   Para este passo a passo e o código de exemplo relacionado, a solução é criada para x64 e release. Observe que o projeto SimpleMathProjection está configurado para compilar para AnyCPU para todas as configurações de arquitetura de solução.

3. Adicione um segundo PropertyGroup elemento (imediatamente após o primeiro) que define várias propriedades C#/WinRT.

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

   Aqui estão alguns detalhes sobre as configurações neste exemplo:

   • A CsWinRTIncludes propriedade especifica quais namespaces projetar.
   • A CsWinRTGeneratedFilesDir propriedade define o diretório de saída no qual os arquivos de origem de projeção são gerados. Essa propriedade é definida como OutDir, definida em Directory.Build.props da seção acima.

4. Salve e feche o arquivo SimpleMathProjection.csproj e clique para Recarregar projetos, se necessário.

Criar um pacote NuGet com a projeção

Para distribuir o assembly de projeção para .NET desenvolvedores de aplicativos, você pode criar automaticamente um pacote NuGet ao criar a solução adicionando algumas propriedades de projeto adicionais. Para destinos .NET, o pacote NuGet precisa incluir o assembly de projeção e o de implementação do componente.

1. Use as etapas abaixo para adicionar um arquivo de especificação do NuGet (.nuspec) ao projeto SimpleMathProjection .

   1. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó SimpleMathProjection, escolha Add>New Folder e nomeie a pasta nuget.
   2. Clique com o botão direito do mouse na pasta nuget, escolha Adicionar>Novo Item, escolha arquivo XML e nomeie-o SimpleMathProjection.nuspec.

2. Em Gerenciador de Soluções, clique duas vezes no nó SimpleMathProjection para abrir o arquivo de projeto no editor. Adicione o seguinte grupo de propriedades ao agora aberto SimpleMathProjection.csproj (imediatamente após os dois elementos PropertyGroup existentes) para a geração automática do pacote. Essas propriedades especificam o NuspecFile e o diretório para gerar o pacote NuGet.

   <PropertyGroup>
     <GeneratedNugetDir>.\nuget\</GeneratedNugetDir>
     <NuspecFile>$(GeneratedNugetDir)SimpleMathProjection.nuspec</NuspecFile>
     <OutputPath>$(GeneratedNugetDir)</OutputPath>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
   </PropertyGroup>
   

   Observação

   Se preferir gerar um pacote separadamente, você também poderá optar por executar a nuget.exe ferramenta na linha de comando. Para obter mais informações sobre como criar um pacote NuGet, consulte Criar um pacote usando a CLI nuget.exe.

3. Abra o arquivo SimpleMathProjection.nuspec para editar as propriedades de criação do pacote e cole o código a seguir. O snippet a seguir é um exemplo de especificação do NuGet para distribuir SimpleMathComponent para várias estruturas de destino. Observe que o conjunto de projeção, SimpleMathProjection.dll, é especificado em vez de SimpleMathComponent.winmd para o destino lib\net6.0-windows10.0.19041.0\SimpleMathProjection.dll. Esse comportamento é novo no .NET 6 e posterior e é habilitado pelo C#/WinRT. A montagem de implementação, SimpleMathComponent.dll, também deve ser distribuída e será carregada em tempo de execução.

   <?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="net6.0-windows10.0.19041.0" />
         <group targetFramework=".NETCoreApp3.0" />
         <group targetFramework="UAP10.0" />
         <group targetFramework=".NETFramework4.6" />
       </dependencies>
     </metadata>
     <files>
       <!--Support .NET 6, .NET Core 3, UAP, .NET Framework 4.6, C++ -->
       <!--Architecture-neutral assemblies-->
       <file src="..\..\_build\AnyCPU\Release\SimpleMathProjection\bin\SimpleMathProjection.dll" target="lib\net6.0-windows10.0.19041.0\SimpleMathProjection.dll" />
       <file src="..\..\_build\x64\Release\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\netcoreapp3.0\SimpleMathComponent.winmd" />
       <file src="..\..\_build\x64\Release\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\uap10.0\SimpleMathComponent.winmd" />
       <file src="..\..\_build\x64\Release\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\net46\SimpleMathComponent.winmd" />
       <!--Architecture-specific implementation DLLs should be copied into RID-relative folders-->
       <file src="..\..\_build\x64\Release\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.dll" target="runtimes\win10-x64\native\SimpleMathComponent.dll" />
       <!--To support x86 and Arm64, build SimpleMathComponent for those other architectures and uncomment the entries below.-->
       <!--<file src="..\..\_build\Win32\Release\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.dll" target="runtimes\win10-x86\native\SimpleMathComponent.dll" />-->
       <!--<file src="..\..\_build\arm64\Release\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.dll" target="runtimes\win10-arm64\native\SimpleMathComponent.dll" />-->
     </files>
   </package>
   

   Observação

   SimpleMathComponent.dll, o conjunto de implementação do componente, é específico da arquitetura. Se você estiver dando suporte a outras plataformas (por exemplo, x86 ou Arm64), primeiro crie SimpleMathComponent para as plataformas desejadas e adicione esses arquivos de assembly à pasta apropriada relativa a RID. A montagem de projeção SimpleMathProjection.dll e o componente SimpleMathComponent.winmd são neutros em termos de arquitetura.

4. Salve e feche os arquivos que você acabou de editar.

Criar a solução para gerar a projeção e o pacote NuGet

Antes de compilar a solução, verifique as configurações Gerenciador de Configurações no Visual Studio, em Build>Gerenciador de Configurações. Para este passo a passo, defina a Configuração para Release e a Plataforma para x64 para a solução.

Neste ponto, agora você pode criar a solução. Clique com o botão direito do mouse no nó da solução e selecione Criar solução. Isso criará primeiro o projeto SimpleMathComponent e, em seguida, o projeto SimpleMathProjection. O componente WinMD e o assembly de implementação (SimpleMathComponent.winmd e SimpleMathComponent.dll), os arquivos de origem de projeção e o assembly de projeção (SimpleMathProjection.dll), serão gerados todos no diretório de saída _build. Você também poderá ver o pacote NuGet gerado, SimpleMathComponent0.1.0-prerelease.nupkg, na pasta \SimpleMathProjection\nuget .

Talvez seja necessário fechar e reabrir a solução para que o .nupkg apareça em Visual Studio conforme ilustrado (ou apenas selecione e desmarque Show Todos os Arquivos).

Referenciar o pacote NuGet em um aplicativo de console do C# .NET 6

Para consumir SimpleMathComponent de um projeto .NET, você pode simplesmente adicionar a um novo projeto .NET uma referência ao pacote NuGet SimpleMathComponent0.1.0-prerelease.nupkg criado na seção anterior. As etapas a seguir demonstram como fazer isso criando um aplicativo de Console simples em uma solução separada.

1. Use as etapas abaixo para criar uma nova solução que contenha um projeto de Aplicativo de Console em C# (a criação desse projeto em uma nova solução permite que você restaure o pacote NuGet SimpleMathComponent de forma independente).

   Importante

   Criaremos um novo projeto de Aplicativo de Console dentro da pasta \CsWinRT\src\Samples\NetProjectionSample, que você encontrará no seu download ou clone do exemplo de projeção C#/WinRT .

   1. Em uma nova instância de Visual Studio, selecione File>New>Project.
   2. Na caixa de diálogo Criar um novo projeto, procure pelo template de projeto Aplicativo de Console. Escolha o modelo de projeto do C# chamado simplesmente Aplicativo de Console (sem prefixos nem sufixos) e clique em Avançar. Se você estiver usando Visual Studio 2019, o modelo de projeto será Console Application.
   3. Nomeie o novo projeto SampleConsoleApp, defina seu local como a mesma pasta de \CsWinRT\src\Samples\NetProjectionSample em que as pastas SimpleMathComponent e SimpleMathProjection estão e clique em Próximo.
   4. Na página Additional information, selecione .NET 8.0 (suporte de longo prazo) e escolha Create.

2. Em Gerenciador de Soluções, clique duas vezes no nó SampleConsoleApp para abrir o arquivo de projeto SampleConsoleApp.csproj, e edite as propriedades TargetFramework e Platform para que elas fiquem conforme mostrado na listagem a seguir. Adicione o Platform elemento se ele não estiver lá.

   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
     <Platform>x64</Platform>
   </PropertyGroup>
   

3. Com o arquivo de projeto SampleConsoleApp.csproj ainda aberto, adicionaremos ao projeto SampleConsoleApp uma referência ao pacote NuGet SimpleMathComponent . Para restaurar o SimpleMathComponent NuGet ao compilar o projeto, você pode usar a propriedade RestoreSources com o caminho para a pasta nuget na sua solução de componentes. Copie a configuração a seguir e cole-a em SampleConsoleApp.csproj (dentro do elemento Project).

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

   Importante

   O caminho para o pacote do SimpleMathComponent, conforme mostrado acima, é definido como . Esse caminho está correto, desde que você tenha seguido as etapas neste passo a passo, para que os projetos SimpleMathComponent e SampleConsoleApp estejam na mesma pasta (a NetProjectionSample pasta, nesse caso). Se você tiver feito algo diferente, precisará ajustar esse caminho adequadamente. Como alternativa, você pode adicionar um feed local de pacotes NuGet à sua solução.

4. Edite o arquivo Program.cs para usar a funcionalidade fornecida pelo SimpleMathComponent.

   var x = new SimpleMathComponent.SimpleMath();
   Console.WriteLine("Adding 5.5 + 6.5 ...");
   Console.WriteLine(x.add(5.5, 6.5).ToString());
   

5. Salve e feche os arquivos que você acabou de editar e compile e execute o aplicativo de console. Você deve ver a saída abaixo.

   

Problemas conhecidos

• Ao criar o projeto de projeção, você pode ver um erro como: Error MSB3271 Havia uma incompatibilidade entre a arquitetura do processador do projeto que está sendo criado "MSIL" e a arquitetura do processador, "x86", do arquivo de implementação "..\SimpleMathComponent.dll" para ".. \SimpleMathComponent.winmd". Essa incompatibilidade pode causar falhas de runtime. Considere alterar a arquitetura do processador de destino do seu projeto por meio do Gerenciador de Configurações para alinhar as arquiteturas do processador entre o projeto e o arquivo de implementação ou escolha um arquivo winmd com um arquivo de implementação que tenha uma arquitetura de processador que corresponda à arquitetura do processador de destino do seu projeto. Para contornar esse erro, adicione a seguinte propriedade ao arquivo de projeto da biblioteca C#:

  <PropertyGroup>
      <!-- Workaround for MSB3271 error on processor architecture mismatch -->
      <ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>None</ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>
  </PropertyGroup>
  

Considerações adicionais

O assembly de projeção (ou interoperabilidade) do C# que mostramos como criar neste tópico é bastante simples: ele não tem dependências em outros componentes. Mas para gerar uma projeção em C# para um componente C++/WinRT que tenha referências a tipos de SDK do Aplicativo Windows, no projeto de projeção, você precisaria adicionar uma referência ao pacote NuGet SDK do Aplicativo Windows. Se essas referências estiverem ausentes, você verá erros como "Tipo <T> não pôde ser encontrado".

Outra coisa que fazemos neste tópico é distribuir a projeção como um pacote NuGet. Esse é atualmente necessário.

Recursos

• Exemplo de código completo para este passo a passo
• Documentação do NuGet C#/WinRT
• documentação NuGet.exe