Passo a passo — criar um componente C#/WinRT e consumi-lo do C++/WinRT

O C#/WinRT permite que os desenvolvedores que usam .NET criem seus próprios componentes Windows Runtime em C# usando um projeto de biblioteca de classes. Os componentes criados podem ser consumidos em aplicativos nativos de desktop como uma referência de pacote ou como uma referência de projeto, com algumas modificações.

Este passo a passo demonstra como criar um componente Windows Runtime simples usando C#/WinRT, distribuir o componente como um pacote NuGet e consumir o componente de um aplicativo de console C++/WinRT. Para obter o exemplo completo que fornece o código deste artigo, consulte o exemplo de criação C#/WinRT. Para obter mais detalhes sobre a autoria, consulte Authoring components.

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

Pré-requisitos

Este passo a passo requer as seguintes ferramentas e componentes:

• Visual Studio 2022 ou posterior
• .NET LTS (SDK 8.0) ou posterior
• C++/WinRT VSIX para modelos de projeto C++/WinRT

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

Comece criando um novo projeto no Visual Studio. Selecione o modelo Class Library project e nomeie o project AuthoringDemo. Você precisará fazer as seguintes adições e modificações no projeto:

1. Atualize o no arquivo AuthoringDemo.csproj do e adicione os seguintes elementos ao :

   <PropertyGroup>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
       <Platforms>x64</Platforms>
   </PropertyGroup>
   

   Para acessar tipos de Runtime do Windows, 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.

2. Instale o Microsoft.Windows. CsWinRT pacote NuGet em seu projeto.

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

   b. Pesquise o Microsoft.Windows. CsWinRT pacote NuGet e instale a versão mais recente.

3. Adicione um novo PropertyGroup elemento que define a CsWinRTComponent propriedade. Isso especifica que seu projeto é um componente Windows Runtime para que um arquivo .winmd seja gerado ao compilar o projeto.

   <PropertyGroup>   
       <CsWinRTComponent>true</CsWinRTComponent>
   </PropertyGroup>
   

   Para obter uma lista completa das propriedades do project C#/WinRT, consulte a documentação C#/WinRT NuGet.

4. Você pode criar suas classes de tempo de execução utilizando os arquivos de classe da biblioteca .cs. Clique com o botão direito do mouse no arquivo e renomeie-o Class1.cs para Example.cs. Adicione o código a seguir a este 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";
           }
       }
   }
   

5. Agora você pode compilar o projeto para gerar o arquivo .winmd para seu componente. Clique com o botão direito do mouse no projeto em Gerenciador de Soluções e clique em Build. Você verá o arquivo AuthoringDemo.winmd gerado na pasta de saída da compilação.

Gerar um pacote NuGet para o componente

A maioria dos desenvolvedores desejará distribuir e compartilhar seu componente 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, C#/WinRT configura o componente e hospeda os assemblies no pacote para habilitar o consumo por aplicativos nativos.

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

• Se você quiser gerar um pacote NuGet sempre que criar o project, adicione a propriedade a seguir ao arquivo AuthoringDemo project e recompile o project.

  <PropertyGroup>
      <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
  

• Como alternativa, você pode gerar um pacote NuGet clicando com o botão direito do mouse no projeto AuthoringDemo em Gerenciador de Soluções e selecionando Pack.

Quando você compila o pacote, a janela Build deve indicar que o pacote AuthoringDemo.1.0.0.nupkg NuGet foi criado com êxito. Consulte Criar um pacote usando a CLI do dotnet para obter mais detalhes sobre as propriedades do pacote NuGet com a CLI .NET.

Consumir o componente de um aplicativo C++/WinRT

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

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

   a. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó da solução e clique em Add ->New Project.

   b. Na caixa de diálogo Adicionar Novo Projeto, pesquise o modelo de projeto C++/WinRT Console Application. Selecione o template e clique em Próximo.

   c. Nomeie o novo project CppConsoleApp e clique em Create.

2. Adicione uma referência ao componente AuthoringDemo, seja como um pacote NuGet ou uma referência de projeto.

   • Opção 1 (referência de pacote):

     a. Clique com o botão direito do mouse no projeto CppConsoleApp e selecione Gerenciar pacotes NuGet. Talvez seja necessário configurar suas fontes de pacotes para adicionar uma referência ao pacote NuGet AuthoringDemo. Para fazer isso, clique no ícone Settings no NuGet Gerenciador de Pacotes e adicione uma fonte de pacote ao caminho apropriado.

     

     b. Depois de configurar as fontes do pacote, pesquise por AuthoringDemo e clique em Instalar.

     

   • Option 2 (referência de projeto):

     a. Clique com o botão direito do mouse no CppConsoleApp project e selecione Add ->Reference. No nó Projects, adicione uma referência ao projeto AuthoringDemo.

3. Para hospedar o componente, você precisará adicionar um arquivo de manifesto para registros de classe ativáveis. Para obter mais detalhes sobre a hospedagem de componentes gerenciados, consulte A hospedagem de componentes gerenciados.

   a. Para adicionar o arquivo de manifesto, clique novamente com o botão direito do mouse no project e escolha Add -> 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 precisa registrar as classes ativáveis no arquivo de manifesto do pacote Package.appxmanifest, conforme explicado em Walkthrough: Criar um componente C# com controles WinUI e consumir pelo aplicativo SDK do Aplicativo Windows C++.

   b. Modifique o projeto para incluir o arquivo de manifesto na saída ao realizar a implantação do projeto. Clique no arquivo CppConsoleApp.exe.manifest no Gerenciador de Soluções e defina a propriedade Content como True. Aqui está um exemplo de como isso se parece.

   

4. Abra pch.h nos Arquivos de Cabeçalho do project e adicione a seguinte linha de código para incluir o componente.

   #include <winrt/AuthoringDemo.h>
   

5. Abra main.cpp nos Arquivos de Origem do project 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;
   }
   

6. Crie e execute o CppConsoleApp project. Agora você deve ver a saída abaixo.

   

Tópicos relacionados

• Código de exemplo
• Componentes de criação
• Hospedagem de componentes gerenciados