Gerar uma projeção C# a partir de um componente C++/WinRT, distribuir como um NuGet para aplicações .NET

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

Em .NET 6 e posteriores, o consumo de ficheiros de metadados de Windows (WinMD) deixou de ser suportado (ver O suporte incorporado para WinRT é removido do .NET). Em vez disso, a ferramenta C#/WinRT pode ser usada para gerar um conjunto de projeção para qualquer ficheiro WinMD, o que permite o consumo de componentes WinRT a partir de aplicações .NET. Um conjunto de projeção também é conhecido como um conjunto de interoperabilidade. Este passo a passo mostra como fazer o seguinte:

• Use o pacote C#/WinRT para gerar uma projeção em C# a partir de um componente C++/WinRT.
• Distribua o componente, juntamente com a montagem de projeção, como um pacote NuGet.
• Consume o pacote NuGet de uma aplicação de consola .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 Detalhes de Instalação>desenvolvimento de Plataforma Universal do Windows, verifique a opção ferramentas C++ (v14x) de Plataforma Universal do Windows.
• .NET 8.0 SDK (LTS) ou posterior.

Vamos usar o Visual Studio 2022 ou posteriores e o .NET 8 neste walkthrough.

Crie um componente simples de Windows Runtime em C++/WinRT

Para seguir este guia, deve primeiro ter um componente Windows Runtime (WRC) em C++/WinRT a partir do qual gerar a montagem de projeção em C#.

Este tutorial usa o WRC SimpleMathComponent do exemplo C#/WinRT projection no GitHub, que já descarregou 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, abre o ficheiro \CsWinRT\src\Samples\NetProjectionSample\CppWinRTComponentProjectionSample.sln, que encontrarás no teu 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);
    };
}

Pode confirmar que a propriedade Windows Desktop Compatible está definida para Sim para o projeto SimpleMathComponent C++/WinRT Windows Runtime component. Para isso, nas propriedades de project para SimpleMathComponent, em Configuration Properties>General>Project Defaults, defina a propriedade Windows Desktop Compatible para Sim. Isso garante que os binários corretos em tempo de execução sejam carregados para serem utilizados por aplicações de ambiente de trabalho .NET.

Página de propriedades

Para passos mais detalhados sobre como criar um componente C++/WinRT e gerar um ficheiro WinMD, consulte componentes Windows Runtime com C++/WinRT.

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

Primeiro, com a solução CppWinRTComponentProjectionSample ainda aberta em Visual Studio, remove o projeto SimpleMathProjection dessa solução. Em seguida, exclua do seu 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 Explorador de Soluções, clique com o botão direito no nó da solução e clique em Add>New Project.
   2. Na caixa de diálogo Adicionar um novo projeto, digite na caixa de pesquisa Biblioteca de Classes. Escolha C# da lista de línguas e depois escolha Windows da lista da plataforma. Escolha o modelo de projeto C# chamado simplesmente Biblioteca de Classes (sem prefixos nem sufixos) e clique em Avançar.
   3. Nomeie o novo projeto SimpleMathProjection. O local já deve estar definido para a mesma \CsWinRT\src\Samples\NetProjectionSample pasta em que a pasta SimpleMathComponent está, mas confirme isso. Em seguida, clique em Avançar.
   4. Na página Informação adicional, selecione .NET 8.0 (Suporte a longo prazo) e depois escolha Criar.

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

3. Use os passos abaixo para instalar o pacote NuGet C#/WinRT.

   1. Em Explorador de Soluções, clique com o botão direito no seu projeto SimpleMathProjection e selecione Gerir Pacotes NuGet.
   2. No separador Browse escreve ou cola Microsoft.Windows. CsWinRT na caixa de pesquisa, nos resultados de pesquisa seleciona o item com a versão mais recente e depois clica em Install para instalar o pacote no projeto SimpleMathProjection.

4. Adicionar ao SimpleMathProjection uma referência de projeto para o projeto SimpleMathComponent. Em Explorador de Soluções, clique com o botão direito no nó Dependências sob o nó do projeto SimpleMathProjection, selecione Adicionar Referência de Projeto e selecione o projeto SimpleMathComponent>OK.

Não tente construir o projeto ainda. Faremos isso em uma etapa posterior.

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

Crie projetos fora do código-fonte

Para a solução CppWinRTComponentProjectionSample do exemplo de projeção C#/WinRT (que baixou ou clonou do GitHub, e agora já está aberta), a localização de saída da build está configurada com o ficheiro Directory.Build.props para compilar fora do diretório fonte. Isso significa que os arquivos da saída de compilação são gerados fora da pasta de origem. Recomendamos que você crie 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).

Mesmo que isso já esteja configurado para a solução CppWinRTComponentProjectionSample , siga as etapas abaixo para obter prática em fazer a configuração por conta própria.

Para configurar sua solução para criar a partir 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 Ficheiro XML e nomeie-o Directory.Build.props (sem extensão .xml). Clique Sim para substituir o arquivo existente.

2. Substitua os conteúdos de 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 .

Edite o arquivo de projeto para executar C#/WinRT

Antes de poder invocar a cswinrt.exe ferramenta para gerar o assembly de projeção, você deve primeiro editar o arquivo de projeto para especificar algumas propriedades do projeto.

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

2. Atualize o elemento TargetFramework para direcionar uma versão específica do SDK Windows. Isso adiciona dependências de assembly que são necessárias para o suporte à interoperabilidade e projeção. Este exemplo dirige-se à 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 a partir de qualquer arquitetura de aplicativo. Para permitir que aplicações de referência suportem versões anteriores Windows SDK, pode também 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 tutorial e o código de exemplo relacionado, a solução foi 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. Esta 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 programadores de aplicações .NET, pode criar automaticamente um pacote NuGet ao construir a solução, adicionando algumas propriedades adicionais ao projeto. Para o alvo .NET, o pacote NuGet precisa incluir os assemblies de projeção e 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 Explorador de Soluções, clique com o botão direito no nó SimpleMathProjection, escolha Add>Nova Pasta 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 Explorador de Soluções, clique duas vezes no nó SimpleMathProjection para abrir o ficheiro do projeto no editor. Adicione o seguinte grupo de propriedades ao SimpleMathProjection.csproj agora aberto (imediatamente após os dois elementos existentes PropertyGroup ) para gerar automaticamente o 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 você preferir gerar um pacote separadamente, então você também pode optar por executar a nuget.exe ferramenta a partir da 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 trecho abaixo é um exemplo de especificação NuGet para distribuir SimpleMathComponent para várias estruturas de destino. Observe que a assemblagem de projeção, SimpleMathProjection.dll, é especificada em vez de SimpleMathComponent.winmd para o alvo lib\net6.0-windows10.0.19041.0\SimpleMathProjection.dll. Este comportamento é novo no .NET 6 e posteriores, e é ativado pelo C#/WinRT. A assemblagem 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 para o componente, é específico para a arquitetura. Se estiveres a dar suporte a outras plataformas (por exemplo, x86 ou Arm64), deverás primeiro criar o SimpleMathComponent para as plataformas desejadas e adicionar esses ficheiros de assembly à pasta relativa ao RID apropriada. A montagem de projeção SimpleMathProjection.dll e o componente SimpleMathComponent.winmd são ambos neutros em termos de arquitetura.

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

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

Antes de construir a solução, certifique-se de verificar as definições Gestor de Configuração no Visual Studio, em Build>Gestor de Configuração. Para este passo a passo, defina a Configuração como 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 Build Solution. Isso primeiro criará o projeto SimpleMathComponent, e, em seguida, o projeto SimpleMathProjection. O componente WinMD e o assembly de implementação (SimpleMathComponent.winmd e SimpleMathComponent.dll), bem como os ficheiros de origem de projeção e o assembly de projeção (SimpleMathProjection.dll), serão todos gerados 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 .

Pode ser necessário fechar e reabrir a solução para que o .nupkg apareça em Visual Studio como ilustrado (ou simplesmente selecionar e depois desmarcar Mostrar Todos os Ficheiros).

Referenciar o pacote NuGet numa aplicação de consola C# .NET 6

Para consumir SimpleMathComponent de um projeto .NET, pode simplesmente adicionar a um novo projeto .NET uma referência ao pacote NuGet SimpleMathComponent0.1.0-prerelease.nupkg que criámos na secçã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 contendo um projeto de Aplicativo de Console C# (criar este projeto em uma nova solução permite restaurar o pacote NuGet SimpleMathComponent independentemente).

   Importante

   Criaremos este novo projeto do Console App dentro da pasta , que você encontrará em seude exemplo de projeção C#/WinRT baixado .

   1. Numa nova instância de Visual Studio, selecione File>Novo>Project.
   2. Na caixa de diálogo Criar um novo projeto, procure o modelo de projeto Console App. Escolha o modelo de projeto C# chamado simplesmente Console App (sem prefixos nem sufixos) e clique em Avançar. Se estiveres a usar Visual Studio 2019, então o modelo do projeto é Consola Application.
   3. Nomeie o novo projeto SampleConsoleApp, defina a sua localização para a mesma pasta \CsWinRT\src\Samples\NetProjectionSample em que as pastas SimpleMathComponent e SimpleMathProjection estão, e clique em Avançar.
   4. Na página Informação adicional, selecione .NET 8.0 (Suporte a longo prazo) e depois escolha Criar.

2. Em Explorador de Soluções, clique duas vezes no nó SampleConsoleApp para abrir o ficheiro do projeto SampleConsoleApp.csproj e edite as propriedades TargetFramework e Platform para que fiquem como mostrado na lista seguinte. 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, em seguida, adicionaremos ao projeto SampleConsoleApp uma referência ao pacote SimpleMathComponent NuGet. Para restaurar o SimpleMathComponent NuGet ao criar o projeto, pode utilizar a propriedade RestoreSources com o caminho para a pasta NuGet na sua solução de componente. Copie a configuração seguinte 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 SimpleMathComponent mostrado acima está definido como . Esse caminho está correto, desde que tenhas seguido os passos deste tutorial, de modo que os projetos SimpleMathComponent e SampleConsoleApp estejam ambos na mesma pasta (neste caso, a pasta NetProjectionSample). Se fizeste algo diferente, então precisarás ajustar o caminho em conformidade. Como alternativa, você pode adicionar um feed de pacote NuGet local à 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 crie e execute o aplicativo de console. Deverá ver o resultado abaixo.

   

Problemas conhecidos

• Ao construir o projeto de projeção, pode ver um erro como: Erro MSB3271 Houve uma incompatibilidade entre a arquitetura do processador do projeto em construção "MSIL" e a arquitetura do processador, "x86", do ficheiro de implementação "..\SimpleMathComponent.dll" por ".. \SimpleMathComponent.winmd". Este desajuste pode causar falhas em tempo de execução. Por favor, considere alterar a arquitetura do processador alvo do seu projeto através do Gestor de Configuração para alinhar as arquiteturas de processador entre o seu projeto e o ficheiro de implementação, ou escolher um ficheiro winmd com um ficheiro de implementação que tenha uma arquitetura de processador que corresponda à arquitetura de processador alvo do seu projeto. Para contornar este erro, adicione a seguinte propriedade ao seu ficheiro de projeto da biblioteca C#:

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

Outras considerações

O assembly de projeção (ou interoperabilidade) em C# que mostramos como criar neste tópico é bastante simples — 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 de Aplicações Windows, no projeto de projeção terias de adicionar uma referência ao pacote NuGet do SDK de Aplicações Windows. Se alguma dessas referências estiver faltando, 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 é necessário neste momento.

Recursos

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