Passo a passo—Crie um componente C#/WinRT e consuma-o a partir de C++/WinRT

O C#/WinRT permite que programadores que usam .NET criem os seus próprios componentes do Windows Runtime em C# através de um projeto de biblioteca de classes. Os componentes criados podem ser utilizados em aplicações nativas de desktop como referência de pacote ou de projeto, com algumas modificações.

Esta guia demonstra como criar um componente simples do Windows Runtime usando C#/WinRT, distribuir o componente como um pacote NuGet e consumir o componente de uma aplicação de consola C++/WinRT. Para o exemplo completo que fornece o código deste artigo, consulte o exemplo de autoria C#/WinRT. Para mais detalhes sobre a autoria, consulte Componentes de autoria.

Para um guia sobre como criar controlos WinUI 3 com C#/WinRT especificamente para uso em aplicações Windows App SDK, consulte o artigo Walkthrough: Criar um componente C# com controlos WinUI e consumir a partir de uma aplicação Windows App SDK C++

Pré-requisitos

Este passo a passo requer as seguintes ferramentas e componentes:

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

Crie um Componente Windows Runtime simples usando C#/WinRT

Comece por criar um novo projeto no Visual Studio. Selecione o modelo Class Library project e nomeie o project AuthoringDemo. Terá de fazer as seguintes adições e modificações ao projecto:

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

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

   Para aceder aos tipos Windows Runtime, é preciso definir uma versão específica do SDK do Windows no TFM. Para mais detalhes sobre a versão suportada, veja .NET 6 e posteriores: Use a opção TFM.

2. Instala o pacote NuGet Microsoft.Windows.CsWinRT no seu projeto.

   a) No Solution Explorer, clique com o botão direito no nó do projeto e selecione Gerir Pacotes NuGet.

   b) Pesquise o pacote Microsoft.Windows.CsWinRT NuGet e instale a versão mais recente. Este passo a passo usa C#/WinRT versão 1.4.1.

3. Adicione um novo elemento PropertyGroup que defina a propriedade CsWinRTComponent. Isto especifica que o seu projeto é um componente Windows Runtime para que um ficheiro .winmd seja gerado quando constróis o projeto.

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

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

4. Você pode criar suas classes em tempo de execução usando arquivos de classe-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 este arquivo, que adiciona uma propriedade pública e um método à classe de tempo de execução. Lembre-se de marcar todas as classes que você deseja expor no componente de tempo de execução 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 pode compilar o projeto para gerar o ficheiro .winmd para o seu componente. Clique com o botão direito no projeto em Solution Explorer e clique em Compilar. Você verá o arquivo de AuthoringDemo.winmd gerado em sua pasta de saída de compilação.

Gerar um pacote NuGet para o componente

A maioria dos programadores vai querer distribuir e partilhar o seu componente Windows Runtime como um pacote NuGet. Outra opção é consumir o componente como 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 permitir o consumo de aplicativos nativos.

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

• Se quiser gerar um pacote NuGet sempre que compila o projeto, adicione a seguinte propriedade ao ficheiro de projeto AuthoringDemo e depois reconstrua o projeto.

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

• Em alternativa, pode gerar um pacote NuGet clicando com o botão direito no AuthoringDemo project em Solution Explorer e selecionando Pack.

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

Consumir o componente de uma aplicação C++/WinRT

Componentes Windows Runtime criados por C#/WinRT podem ser consumidos a partir 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 Aplicação de Consola C++/WinRT à sua solução. Note que este projeto também pode integrar uma solução diferente, caso o deseje.

   a) Em Solution Explorer, clique com o botão direito no nó da solução e clique em Add ->New Project.

   b) Na caixa de diálogo Add New Project, procure o modelo de projeto C++/WinRT Console Application. Selecione o modelo e clique em Avançar.

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

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

   • Opção 1 (Referência do pacote):

     a) Clique com o botão direito em CppConsoleApp project e selecione Gerir pacotes NuGet. Talvez seja necessário configurar as fontes do pacote para adicionar uma referência ao pacote NuGet AuthoringDemo. To do isto, clique no ícone Settings no NuGet Package Manager e adicione uma fonte de pacote ao caminho apropriado.

     

     b) Depois de configurar as fontes do pacote, procure o pacote AuthoringDemo e clique em Instalar.

     

   • Opção 2 (referência ao Project):

     a) Clique com o botão direito em 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 mais detalhes sobre alojamento de componentes geridos, veja Alojamento de componentes geridos.

   a) Para adicionar o ficheiro do manifesto, volte a clicar com o botão direito no project e escolher Adicionar -> Novo Item. Procure o modelo de Arquivo de Texto e atribua-lhe o nome CppConsoleApp.exe.manifest. Insira o seguinte conteúdo, que especifica as classes de execução usando entradas de registo de classes ativáveis:

   <?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 aplicações empacotadas, o consumidor da aplicação precisa de registar as classes ativáveis no ficheiro de manifesto do seu pacote Package.appxmanifest, conforme explicado em Walkthrough: Crie um componente C# com controlos WinUI e consuma a partir de uma aplicação Windows App SDK C++.

   b) Modificar o projeto para incluir o ficheiro de manifestação no resultado ao implantar o projeto. Clique no ficheiro CppConsoleApp.exe.manifest em Solution Explorer e defina a propriedade Content para True. Aqui está um exemplo de como isso se parece.

   

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

   #include <winrt/AuthoringDemo.h>
   

5. Abra main.cpp nos Ficheiros Fonte do project e substitua-o pelo seguinte conteúdo.

   #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. Constrói e executa a CppConsoleApp project. Agora você deve ver a saída abaixo.

   

Tópicos relacionados

• Componentes de autoria
• Alojamento de componentes gerido