Partilhar via

Guia—Crie um componente C# com controlos do WinUI 3 e consuma-o a partir de uma aplicação C++/WinRT que utilize o SDK de Aplicações Windows

O C#/WinRT oferece suporte para a autoria de componentes do Windows Runtime, incluindo tipos personalizados WinUI e controlos personalizados. Estes componentes podem ser consumidos tanto a partir de aplicações C# como C++/WinRT que utilizam o SDK de Aplicações Windows. Recomendamos o uso de C#/WinRT v1.6.4 ou posterior para criar componentes de tempo de execução com suporte para empacotamento com NuGet.

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

Esta explicação demonstra como criar um componente C# com um controlo WinUI personalizado e como consumir esse componente a partir de uma aplicação C++/WinRT, usando os modelos de projeto do SDK de Aplicações Windows.

Pré-requisitos

Este passo a passo requer as seguintes ferramentas e componentes:

Crie o seu componente C#/WinRT usando o SDK de Aplicações Windows

  1. Crie um novo projeto de biblioteca C# usando o modelo Class Library (WinUI in Desktop) fornecido pelo SDK de Aplicações Windows. Para este guia passo a passo, nomeámos o projeto da biblioteca WinUIComponentCs e a solução AuthoringWinUI.

    Deixe a caixa Colocar solução e projeto no mesmo diretório desmarcada (caso contrário, a pasta packages da aplicação C++ na seção anterior acabará por interferir com o projeto da biblioteca C#).

    Caixa de diálogo Nova biblioteca

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

  3. Instala a versão mais recente Microsoft.Windows. CsWinRT Pacote NuGet no teu projeto.

    i) No Explorador de Soluções, clique com o botão direito no nó do projeto e selecione Gerir Pacotes NuGet.

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

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

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • A propriedade CsWinRTComponent especifica que o seu projeto é um componente Windows Runtime para que um ficheiro .winmd seja gerado quando constrói o projeto.

  5. Adicione um controle personalizado ou controle de usuário à sua biblioteca. Para isso, clique com o botão direito no seu projeto em Visual Studio, clique em Adicionar>Novo Item e selecione WinUI no painel esquerdo. Para este guia, adicionámos um novo Controlo do Utilizador (WinUI) e chamámo-lo NameReporter.xaml. O controlo de utilizador NameReporter permite que um utilizador insira um nome e apelido na caixa de texto apropriada e clique num 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 pode compilar o WinUIComponentCs project para gerar um ficheiro .winmd para o componente.

Observação

Você também pode empacotar o componente como um pacote NuGet para os consumidores finais do aplicativo consultarem. Para mais detalhes, veja Authoring C#/WinRT components no repositório de GitHub C#/WinRT.

Referenciar o componente a partir de uma aplicação SDK de Aplicações Windows C++/WinRT

Os passos seguintes mostram como consumir o componente criado a partir da secção anterior a partir de uma aplicação SDK de Aplicações Windows C++/WinRT. Consumir um componente C#/WinRT de C++ requer atualmente o uso do template de projeto único WinUI Blank App (Packaged). Observe que os componentes do C# também podem ser referenciados a partir de aplicativos empacotados em C# sem registros de classe.

O consumo de aplicações empacotadas que utilizam um projeto separado Windows Application Packaging (WAP) não é atualmente suportado. Consulte Authoring C#/WinRT components no repositório GitHub C#/WinRT para as últimas atualizações sobre configurações suportadas de projetos.

  1. Adicione um novo projeto de aplicação C++ para SDK de Aplicações Windows à sua solução. Clique com o botão direito na sua solução em Visual Studio e selecione Adicionar>Novo Project. Selecione o modelo C++ WinUI Blank App (Packaged) fornecido pelo SDK de Aplicações Windows. Para este tutorial, nomeamos a aplicação CppApp.

  2. Adicione uma referência de projeto da aplicação C++ ao componente C#. No Visual Studio, clique com o botão direito no projeto C++ e escolha Add>Reference, e selecione o projeto WinUIComponentCs.

    Observação

    O consumo de componentes como uma referência de pacote NuGet é suportado 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 manifesto do pacote, Package.appxmanifest.

    Observação

    Há um problema conhecido em que o ficheiro Package.appxmanifest não aparece no Visual Studio Explorador de Soluções. Para contornar isso, clique com o botão direito no seu project C++, selecione Descarregar Project e clique duas vezes no project para abrir o ficheiro CppApp.vcxproj. Adicione a seguinte entrada ao ficheiro do project e depois recarregue o project:

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

    No Package.appxmanifest, adicione os seguintes registos de classes ativáveis. Você também precisará de uma entrada adicional ActivatableClass para a classe WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider, a fim de 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 editá-lo.

    <!--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 ficheiro 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 projeto de arranque — clique com o botão direito em CppApp e selecione Definir como Projeto de Arranque. Defina a configuração da solução como x86. Antes de compilar, pode também precisar de redirecionar a 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 Redirecionar solução e atualize o conjunto de ferramentas da plataforma para v143.

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

Problemas conhecidos

  • Consumir um componente C# como referência de projeto requer que PublishReadyToRun seja definido para False. Consulte GitHub Edição #1151 para mais detalhes.
  • O consumo de um componente C# criado para AnyCPU a partir de C++ é suportado apenas a partir de x86 aplicações atualmente. x64 e Arm64 aplicações resultam num erro de execução semelhante a: %1 não é uma aplicação válida do Win32. Ver GitHub Edição #1093 para mais detalhes.
  • Last updated on