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

C#/WinRT permite que desenvolvedores usando .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 Windows App SDK, consulte o artigo Walkthrough: Criar um componente C# com controles WinUI e consumir de um aplicativo Windows App SDK C++

Pré-requisitos

Este passo a passo requer as seguintes ferramentas e componentes:

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

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

Comece criando um novo project em 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 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.

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

   a. Em Solution Explorer, clique com o botão direito do mouse no nó do projeto e selecione Gerenciar Pacotes NuGet.

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

3. Adicione um novo PropertyGroup elemento que define a CsWinRTComponent propriedade. Isso especifica que o seu projeto é um componente Windows Runtime para que um arquivo .winmd seja gerado quando você 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 Solution Explorer 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 AuthoringDemo project no Solution Explorer 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 Solution Explorer, 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 Aplicativo de Console C++/WinRT. 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. To do isso, 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, pesquise por AuthoringDemo e clique em Instalar.

     

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

     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 em seu arquivo de manifesto do pacote Package.appxmanifest, conforme explicado em Passo a passo: criar um componente C# com controles WinUI e consumir de um aplicativo Windows App SDK 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 Solution Explorer 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