Passo a passo: criar um componente C#/WinRT e consumi-lo de C++/WinRT

Artigo
09/05/2023

O C#/WinRT permite que os desenvolvedores .NET criem seus componentes do Windows Runtime em C# usando um projeto de biblioteca de classes. Os componentes criados podem ser consumidos em aplicativos nativos da área de trabalho como uma referência de pacote ou como uma referência de projeto com algumas modificações.

Este tutorial demonstra como criar um componente simples do Windows Runtime usando C#/WinRT, distribuí-lo como um pacote NuGet e consumi-lo de um aplicativo de console do C++/WinRT. Para obter o exemplo completo que fornece o código para este artigo, consulte o exemplo de criação do C#/WinRT. Para obter mais detalhes sobre criação, consulte Criar componentes.

Para obter um passo a passo sobre como criar controles da WinUI com C#/WinRT especificamente para uso em aplicativos SDK do Aplicativo Windows, consulte o artigo Passo a passo: criar um componente C# com controles da WinUI 3 e consumir de um aplicativo SDK do Aplicativo Windows C++

Pré-requisitos

Este tutorial exige os seguintes componentes e ferramentas:

Visual Studio 2022
SDK do .NET 6.0 ou posterior
VSIX do C++/WinRT para modelos de projeto do C++/WinRT

Criar um componente simples do Windows Runtime usando C#/WinRT

Comece criando um projeto no Visual Studio. Selecione o modelo de projeto da Biblioteca de classes e nomeie o projeto como AuthoringDemo. Você deve fazer as seguintes adições e modificações no projeto:

Atualize o TargetFramework no arquivo AuthoringDemo.csproj e adicione os seguintes elementos ao PropertyGroup:
```
<PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platforms>x64</Platforms>
</PropertyGroup>
```
Para acessar os tipos do Windows Runtime, você precisa definir uma versão específica do SDK do Windows no TFM. Para obter mais detalhes sobre a versão com suporte, consulte .NET 6 e posteriores: use a opção TFM.
Instale o pacote NuGet Microsoft.Windows.CsWinRT no seu projeto.

a. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Gerenciar pacotes NuGet.

b. Pesquise pelo pacote NuGet Microsoft.Windows.CsWinRT e instale a versão mais recente. Esse tutorial usa C#/WinRT versão 1.4.1.
Adicione um novo elemento PropertyGroup que define a propriedade CsWinRTComponent. Isso especifica que seu projeto é um componente do Windows Runtime, para que um arquivo .winmd seja gerado ao compilar o projeto.
```
<PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
```
Para ver uma lista completa de propriedades do projeto C#/WinRT, consulte a documentação do NuGet C#/WinRT.
Você pode criar classes de runtime usando arquivos de classe da biblioteca .cs. Clique com o botão direito do mouse no arquivo Class1.cs e renomeie-o para Example.cs. Adicione o seguinte código a esse arquivo, que adiciona uma propriedade pública e um método à classe de runtime. Lembre-se de marcar todas as classes que você deseja expor no componente de runtime como public.
```
namespace AuthoringDemo
{
    public sealed class Example
    {
        public int SampleProperty { get; set; }

        public static string SayHello()
        {
            return "Hello from your C# WinRT component";
        }
    }
}
```
Agora você pode compilar o projeto para gerar o arquivo de .winmd para o seu componente. Clique com o botão direito do mouse no Gerenciador de Soluções e clique em Compilar. Você verá o arquivo AuthoringDemo.winmd gerado em sua pasta de saída da compilação.

Gerar um pacote NuGet para o componente

A maioria dos desenvolvedores deseja distribuir e compartilhar o componente do Windows Runtime como um pacote NuGet. Outra opção é consumir o componente como uma referência de projeto. As etapas a seguir demonstram como empacotar o componente AuthoringDemo. Quando você gera o pacote, o C#/WinRT configura o componente e os assemblies de hospedagem no pacote para habilitar o consumo de aplicativos nativos.

Há várias maneiras de gerar o pacote NuGet:

Se você quiser gerar um pacote NuGet toda vez que compilar o projeto, adicione a seguinte propriedade ao arquivo de projeto AuthoringDemo e recompile o projeto.
```
<PropertyGroup>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>
```
Como alternativa, você pode gerar um pacote NuGet clicando com o botão direito do mouse no projeto AuthoringDemo no Gerenciador de Soluções e selecionando Pacote.

Quando você compilar o pacote, a janela de Compilação deve indicar que o pacote NuGet AuthoringDemo.1.0.0.nupkg foi criado com sucesso. Consulte Criar um pacote usando a CLI do dotnet para obter mais detalhes sobre as propriedades do pacote NuGet com a CLI do .NET.

Consumir o componente de um aplicativo C++/WinRT

Os componentes do Windows Runtime criados do C#/WinRT podem ser consumidos de qualquer linguagem compatível com o WinRT (Windows Runtime). As etapas a seguir demonstram como chamar o componente de criação acima em um aplicativo de console do C++/WinRT.

Observação

O consumo de um componente C#/WinRT de aplicativos C#/.NET tem suporte da referência do pacote ou da referência do projeto. Esse cenário é equivalente a consumir qualquer biblioteca de classes C# comum e não envolve a ativação do WinRT na maioria dos casos. Do C#/WinRT 1.3.5 e versões posteriores, as referências de projeto para consumidores de C# exigem o .NET 6.

Adicionar um novo projeto de aplicativo de console do C++/WinRT à sua solução. Observe que esse projeto também pode fazer parte de uma solução diferente se você quiser.

a. No Gerenciador de Soluções, clique com o botão direito do mouse no nó da sua solução e clique em Adicionar ->Novo Projeto.

b. Na caixa de diálogo Adicionar projeto, pesquise o modelo de projeto de aplicativo de console C++/WinRT. Selecione o modelo e clique em Avançar.

c. Nomeie o novo projeto como CppConsoleApp e clique em Criar.
Adicione uma referência ao componente AuthoringDemo, seja como um pacote NuGet ou uma referência de projeto.
- Opção 1 (referência do pacote):
  
  a. Clique com o botão direito do mouse no projeto CppConsoleApp e selecione Gerenciar pacotes NuGet. Talvez seja necessário configurar as fontes de pacotes para adicionar uma referência ao pacote NuGet AuthoringDemo. Para fazer isso, clique no ícone de Configurações no Gerenciador de pacotes NuGet e adicione uma fonte de pacotes ao demarcador apropriado.
  
  b. Depois de configurar as fontes de pacotes, pesquise o pacote AuthoringDemo e clique em Instalar.
- Opção 2 (referência do projeto):
  
  a. Clique com o botão direito do mouse no projeto CppConsoleApp e selecione Adicionar>Referência. No nó Projetos, adicione uma referência ao projeto AuthoringDemo.
Para hospedar o componente, você vai precisar adicionar um arquivo de manifesto para registros de classe ativável. Para obter mais detalhes sobre hospedagem de componentes gerenciados, consulte Hospedagem de componente gerenciado.

a. Para adicionar o arquivo de manifesto, clique novamente com o botão direito do mouse no projeto e escolha Adicionar > Novo item. Pesquise o modelo de arquivo de texto e nomeie-o CppConsoleApp.exe.manifest. Cole o seguinte conteúdo, que especifica as classes de runtime usando entradas de registro de classe ativável:
```
<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
    <assemblyIdentity version="1.0.0.0" name="CppConsoleApp"/>
    <file name="WinRT.Host.dll">
        <activatableClass
            name="AuthoringDemo.Example"
            threadingModel="both"
            xmlns="urn:schemas-microsoft-com:winrt.v1" />
    </file>
</assembly>
```
O arquivo de manifesto do aplicativo é necessário para aplicativos que não são empacotados. Para aplicativos empacotados, o consumidor do aplicativo deve registrar as classes ativas no arquivo de manifesto do pacote Package.appxmanifest, conforme explicado em Passo a passo: criar um componente C# com controles da WinUI 3 e consumir de um aplicativo SDK do Aplicativo Windows C++.

b. Modifique o projeto para incluir o arquivo de manifesto na saída ao implantar o projeto. Clique no arquivo CppConsoleApp.exe.manifest no Gerenciador de Soluções e defina a propriedade Conteúdo como Verdadeiro. Este é um exemplo de como isso se parece.
Abra pch.h nos arquivos de cabeçalho do projeto e adicione a linha de código a seguir para incluir o componente.
```
#include <winrt/AuthoringDemo.h>
```

Abra main.cpp nos arquivos de origem do projeto e substitua-o pelo conteúdo a seguir.

#include "pch.h"
#include "iostream"

using namespace winrt;
using namespace Windows::Foundation;

int main()
{
    init_apartment();

    AuthoringDemo::Example ex;
    ex.SampleProperty(42);
    std::wcout << ex.SampleProperty() << std::endl;
    std::wcout << ex.SayHello().c_str() << std::endl;
}

Compile e execute o projeto CppConsoleApp. Agora você deve ver a saída abaixo.

Passo a passo: criar um componente C#/WinRT e consumi-lo de C++/WinRT

Pré-requisitos

Criar um componente simples do Windows Runtime usando C#/WinRT

Gerar um pacote NuGet para o componente

Consumir o componente de um aplicativo C++/WinRT

Comentários

Recursos adicionais

Passo a passo: criar um componente C#/WinRT e consumi-lo de C++/WinRT

Pré-requisitos

Criar um componente simples do Windows Runtime usando C#/WinRT

Gerar um pacote NuGet para o componente

Consumir o componente de um aplicativo C++/WinRT

Tópicos relacionados

Comentários

Recursos adicionais