Compartilhar via

Passo a passo : crie um componente C# com controles WinUI 3 e consuma-o de um aplicativo C++/WinRT que usa o SDK do Aplicativo Windows

O C#/WinRT dá suporte à criação de componentes Windows Runtime, incluindo tipos personalizados do WinUI e controles personalizados. Esses componentes podem ser consumidos de aplicativos C# ou C++/WinRT que usam o SDK do Aplicativo Windows. É recomendável usar o C#/WinRT v1.6.4 ou posterior para criar componentes de runtime com suporte ao empacotamento NuGet.

Para obter mais detalhes sobre os cenários com suporte, consulte Authoring C#/WinRT components no repositório de GitHub C#/WinRT.

Este passo a passo demonstra como criar um componente C# com um controle WinUI personalizado e como consumir esse componente de um aplicativo C++/WinRT usando os modelos de projeto SDK do Aplicativo Windows.

Pré-requisitos

Este passo a passo requer as seguintes ferramentas e componentes:

Crie seu componente C#/WinRT usando o SDK do Aplicativo Windows

  1. Crie um novo projeto de biblioteca C# usando o modelo Class Library (WinUI in Desktop) fornecido pelo SDK do Aplicativo Windows. Para este passo a passo, nomeamos o projeto de biblioteca WinUIComponentCs e a solução AuthoringWinUI.

    Deixe desmarcada a opção Colocar solução e projeto no mesmo diretório (caso contrário, a pasta packages do aplicativo C++ na seção anterior acabará interferindo no projeto da biblioteca C#).

    nova de diálogo da biblioteca

  2. Exclua o Class1.cs arquivo incluído por padrão.

  3. Instale o pacote NuGet Microsoft.Windows.CsWinRT mais recente em seu projeto.

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

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

  4. Adicione as seguintes propriedades ao seu projeto de biblioteca:

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • A propriedade CsWinRTComponent especifica que seu projeto é um componente Windows Runtime para que um arquivo .winmd seja gerado ao compilar o projeto.

  5. Adicione um controle personalizado ou controle de usuário à biblioteca. Para fazer isso, clique com o botão direito do mouse em seu projeto em Visual Studio, clique em Add>New Item e selecione WinUI no painel esquerdo. Para este passo a passo, adicionamos um novo Controle de Usuário (WinUI) e o nomeamos NameReporter.xaml. O controle de usuário NameReporter permite que um usuário insira um nome e sobrenome no controle TextBox apropriado e clique em um botão. Em seguida, o controle exibe uma caixa de mensagem com o nome que o usuário inseriu.

  6. Cole o seguinte código no NameReporter.xaml arquivo:

    <UserControl
x:Class="WinUIComponentCs.NameReporter"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:WinUIComponentCs"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">

    <StackPanel HorizontalAlignment="Center">
        <StackPanel.Resources>
            <Style x:Key="BasicTextStyle" TargetType="TextBlock" BasedOn="{StaticResource BodyTextBlockStyle}">
                <Setter Property="Margin" Value="10,10,10,10"/>
            </Style>
        </StackPanel.Resources>

        <TextBlock Text="Enter your name." Margin="0,0,0,10"/>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                First Name:
            </TextBlock>
            <TextBox Name="firstName" />
        </StackPanel>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                Last Name:
            </TextBlock>
            <TextBox Name="lastName" />
        </StackPanel>
        <Button Content="Submit" Click="Button_Click" Margin="0,0,0,10"/>
        <TextBlock Name="result" Style="{StaticResource BasicTextStyle}" Margin="0,0,0,10"/>
    </StackPanel>
</UserControl>

  7. Adicione o seguinte método a NameReporter.xaml.cs:

    using System.Text;
...
private void Button_Click(object sender, RoutedEventArgs e)
{
    StringBuilder displayText = new StringBuilder("Hello, ");
    displayText.AppendFormat("{0} {1}.", firstName.Text, lastName.Text);
    result.Text = displayText.ToString();
}

  8. Agora você pode criar o WinUIComponentCs project para gerar um arquivo .winmd para o componente.

Observação

Você também pode empacotar o componente como um pacote NuGet para que os consumidores do aplicativo final façam referência. Para obter mais detalhes, consulte Authoring C#/WinRT components no repositório de GitHub C#/WinRT.

Referencie o componente a partir de um aplicativo SDK do Aplicativo Windows C++/WinRT

As etapas a seguir mostram como consumir o componente criado da seção anterior de um aplicativo SDK do Aplicativo Windows C++/WinRT. O consumo de um componente C#/WinRT do C++ atualmente requer o uso do modelo de Projeto Único Aplicativo WinUI em Branco (Empacotado). Observe que os componentes C# também podem ser referenciados de aplicativos empacotados em C# sem registros de classe.

Atualmente, não há suporte para o consumo de aplicativos empacotados que usam um projeto separado de Windows Application Packaging (WAP). Consulte Authoring C#/WinRT components no repositório de GitHub C#/WinRT para obter as atualizações mais recentes sobre configurações de projeto com suporte.

  1. Adicione um novo projeto de aplicativo SDK do Aplicativo Windows C++ à sua solução. Clique com o botão direito do mouse na solução no Visual Studio e selecione Add>New Project. Selecione o modelo C++ WinUI Blank App (Empacotado) fornecido pelo SDK do Aplicativo Windows. Para este passo a passo, nomeamos o aplicativo CppApp.

  2. Adicione uma referência de projeto do aplicativo C++ ao componente C#. Em Visual Studio, clique com o botão direito do mouse no projeto C++ e escolha Add>Reference e selecione o projeto WinUIComponentCs.

    Observação

    O consumo de componentes como referência de pacote NuGet é suportado, mas com algumas limitações. Ou seja, componentes com controles de usuário personalizados não podem ser consumidos atualmente como uma referência de pacote NuGet.

  3. No arquivo de cabeçalho do pch.h aplicativo, adicione as seguintes linhas:

    #include <winrt/WinUIComponentCs.h>
#include <winrt/WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.h>

  4. Abra o arquivo de manifest do pacote, Package.appxmanifest.

    Observação

    Há um problema conhecido em que o arquivo Package.appxmanifest não aparece no Visual Studio Gerenciador de Soluções. Para solucionar isso, clique com o botão direito do mouse em sua project do C++, selecione Unload Project e clique duas vezes no project para abrir o arquivo CppApp.vcxproj. Adicione a seguinte entrada ao arquivo do projeto e recarregue o projeto:

    <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
    <SubType>Designer</SubType>
    </AppxManifest>
</ItemGroup>

    Em Package.appxmanifest, adicione os seguintes registros de classe ativáveis. Você também precisará de uma entrada de ActivatableClass adicional para a classe WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider para ativar os tipos WinUI. Clique com o botão direito do Package.appxmanifest mouse no arquivo e selecione Abrir com>XML (Editor de Texto) para editar o arquivo.

    <!--In order to host the C# component from C++, you must add the following Extension group and list the activatable classes-->
<Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
        <InProcessServer>
            <Path>WinRT.Host.dll</Path>
            <ActivatableClass ActivatableClassId="WinUIComponentCs.NameReporter" ThreadingModel="both" />
            <ActivatableClass ActivatableClassId="WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider" ThreadingModel="both" />
        </InProcessServer>
    </Extension>
</Extensions>

  5. Abra o arquivo MainWindow.xaml.

    i. Adicione uma referência ao namespace do componente na parte superior do arquivo.

    xmlns:custom="using:WinUIComponentCs"

    ii. Adicione o controle de usuário ao código XAML existente.

    <StackPanel>
    ...
    <custom:NameReporter/>
</StackPanel>

  6. Defina CppApp como o projeto de inicialização, clique com o botão direito do mouse em CppApp e selecione Definir como Projeto de Inicialização. Defina a configuração da solução como x86. Antes de compilar, talvez você também precise ajustar sua solução para compilar com as ferramentas de build do Visual Studio 2026. Clique com o botão direito do mouse na solução, selecione Retarget solution, e atualize o Platform Toolset para v143.

  7. Crie e execute o aplicativo para ver o controle personalizado NameReporter.

Problemas conhecidos

  • Consumir um componente C# como uma referência de projeto requer que PublishReadyToRun seja definido como False. Consulte GitHub Problema nº 1151 para obter mais detalhes.
  • O consumo de um componente C# criado para AnyCPU a partir do C++ tem suporte apenas por aplicativos x86 atualmente. x64 e aplicativos Arm64 resultam em um erro de runtime semelhante a: %1 não é um aplicativo Win32 válido. Consulte GitHub Problema nº 1093 para obter mais detalhes.
  • Last updated on