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. Um assembly de projeção também é conhecido como um assembly 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.

Importante

Além disso, você precisará baixar ou clonar o código de exemplo deste tópico da amostra de projeção C#/WinRT no GitHub. Visite CsWinRT e clique no botão verde Código para obter o url git clone. Certifique-se de ler o arquivo README.md como exemplo.

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

Para seguir este passo a passo, você deve primeiro ter um WRC (componente do Windows Runtime) C++/WinRT por meio do qual é possível gerar o assembly de projeção 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 o consumo de aplicativos da área de trabalho .NET.

Página de propriedades compatível com a Á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.

Observação

Se você estiver implementando IInspectable::GetRuntimeClassName em seu componente, ele deve retornar um nome de classe WinRT válido. Como o C#/WinRT usa a cadeia de caracteres de nome de classe para interoperabilidade, um nome de classe de runtime incorreto gerará uma InvalidCastException.

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.

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. A localização já deve estar definida para a mesma pasta \CsWinRT\src\Samples\NetProjectionSample em que se encontra a pasta SimpleMathComponent; mas confirme isso. Em seguida, clique em Próximo.
4. Na página Additional information, selecione .NET 8.0 (suporte de longo prazo) e escolha Create.
Exclua o stub Class1.cs arquivo do projeto.
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.
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).

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

Compile projetos fora da origem

Para a solução CppWinRTComponentProjectionSample na amostra de projeção C#/WinRT (que você baixou ou clonou do GitHub e agora está aberta), a localização de saída da compilação é configurada com o arquivo Directory.Build.props para a compilação fora da origem. 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:

Com a solução CppWinRTComponentProjectionSample ainda aberta, clique com o botão direito no nó da solução e selecione Adicionar>Novo 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.

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>

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.

Em Gerenciador de Soluções, clique duas vezes no nó SimpleMathProjection para abrir o arquivo de projeto no editor.
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 de interoperabilidade e de 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>
  
  <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 Versão. Observe que o projeto SimpleMathProjection está configurado para compilar para AnyCPU para todas as configurações de arquitetura de solução.

Importante

A configuração de AnyCPU neste passo a passo se aplica ao padrão de distribuição do NuGet mostrado posteriormente no artigo. O assembly de projeção gerenciada é neutro em arquitetura, enquanto o NuGet seleciona a DLL de implementação nativa de uma pasta de runtime específica da arquitetura.

Se o projeto de projeção usar <UseUwp>true</UseUwp> ou, de outra forma, participar do empacotamento MSIX ou AppX e fizer referência direta ao projeto C++/WinRT nativo, não tenha AnyCPU como destino. Configure a projeção e os projetos nativos para usar a mesma plataforma concreta, como x86, x64 ou ARM64. Para várias arquiteturas, crie configurações de solução e projeto correspondentes e crie cada arquitetura separadamente. Caso contrário, a validação do pacote pode falhar com o erro APPX0505 porque a arquitetura de projeção neutra não corresponde ao projeto nativo referenciado.
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.
Salve e feche o arquivo SimpleMathProjection.csproj e clique em 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 os destinos .NET, o pacote NuGet precisa incluir o assembly de projeção e o conjunto de implementação do componente.

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

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 será necessário criar SimpleMathComponent para as plataformas desejadas e adicionar esses arquivos de assembly à pasta relativa RID apropriada. A montagem de projeção SimpleMathProjection.dll e o componente SimpleMathComponent.winmd são neutros em termos de arquitetura.

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 no nó da solução e selecione Solução de Compilação. Isso criará primeiro o projeto SimpleMathComponent e, em seguida, o projeto SimpleMathProjection. O componente WinMD e o conjunto de implementação (SimpleMathComponent.winmd e SimpleMathComponent.dll), os arquivos de origem da 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 .

Importante

Se qualquer um dos arquivos mencionados acima não for gerado, crie a solução uma segunda vez. Também pode ser necessário fechar e reabrir a solução antes da recompilação.

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

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

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.

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 esse novo projeto de Aplicativo de Console dentro da pasta \CsWinRT\src\Samples\NetProjectionSample, que você encontrará na amostra de projeção C#/WinRT baixada ou clonada.
1. Em uma nova instância de Visual Studio, selecione File>New>Project.
2. Na caixa de diálogo Criar um novo projeto, pesquise o modelo de projeto de Aplicativo de Console. Escolha o modelo de projeto C# que é chamado simplesmente de 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 a 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 Additional information, selecione .NET 8.0 (suporte de longo prazo) e escolha Create.
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>
```
Com o arquivo de projeto SampleConsoleApp.csproj ainda aberto, adicionaremos ao projeto SampleConsoleApp uma referência ao pacote NuGet SimpleMathComponent . Para restaurar o NuGet SimpleMathComponent ao compilar o projeto, você pode usar a propriedade RestoreSources com o demarcador para a pasta nuget na solução do componente. 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 demarcador RestoreSources para o pacote SimpleMathComponent mostrado acima é definido como ../SimpleMathProjection/nuget. 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). Caso tenha feito algo diferente, você precisará ajustar esse demarcador de modo compatível. Como alternativa, você pode adicionar um feed do pacote NuGet local à sua solução.

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());

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>
    
    <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. Isso é necessário no momento.

Recursos

Comentários

Esta página foi útil?

Last updated on 2026-08-30