Panduan—Membuat komponen C# dengan kontrol WinUI 3, dan menggunakannya dari aplikasi C++/WinRT yang menggunakan SDK Aplikasi Windows

C#/WinRT menyediakan dukungan untuk penulisan komponen Windows Runtime, termasuk jenis kustom WinUI dan kontrol kustom. Komponen ini dapat dikonsumsi dari aplikasi C# atau C++/WinRT yang menggunakan SDK Aplikasi Windows. Sebaiknya gunakan C#/WinRT v1.6.4 atau yang lebih baru untuk menulis komponen runtime dengan dukungan kemasan NuGet.

Untuk detail selengkapnya tentang skenario yang didukung, lihat komponen Authoring C#/WinRT di repositori C#/WinRT GitHub.

Panduan ini menunjukkan cara menulis komponen C# dengan kontrol WinUI kustom, dan cara menggunakan komponen tersebut dari aplikasi C++/WinRT, menggunakan templat proyek SDK Aplikasi Windows.

Prasyarat

Panduan ini memerlukan alat dan komponen berikut:

Menulis komponen C#/WinRT Anda menggunakan SDK Aplikasi Windows

  1. Buat proyek pustaka C# baru menggunakan templat pustaka Class (WinUI di Desktop) yang disediakan oleh SDK Aplikasi Windows. Untuk panduan ini, kami telah menamai proyek pustaka WinUIComponentCs, dan solusinya AuthoringWinUI.

    Biarkan kotak Tempatkan solusi dan proyek di direktori yang sama tidak dicentang (jika tidak, folder packages untuk aplikasi C++ di bagian sebelumnya akan mengganggu proyek pustaka C#).

    Dialog pustaka baru

  2. Class1.cs Hapus file yang disertakan secara default.

  3. Pasang paket NuGet Microsoft.Windows.CsWinRT versi terbaru dalam proyek Anda.

    i. Di Penjelajah Solusi, klik kanan pada simpul proyek, dan pilih Kelola Paket NuGet.

    ii. Cari paket NuGet Microsoft.Windows.CsWinRT dan instal versi terbaru.

  4. Tambahkan properti berikut ke proyek pustaka Anda.

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • Properti menentukan bahwa proyek Anda adalah komponen Windows Runtime sehingga file />

  5. Tambahkan kontrol kustom atau kontrol pengguna ke pustaka Anda. Untuk melakukan ini, klik kanan proyek Anda di Visual Studio, klik Tambahkan> Item Baru, dan pilih WinUI di panel kiri. Untuk panduan ini, kami menambahkan Kontrol Pengguna (WinUI) baru dan menamainyaNameReporter.xaml. Kontrol pengguna NameReporter memungkinkan pengguna memasukkan nama depan dan belakang ke kontrol TextBox yang sesuai, dan mengklik tombol. Kontrol kemudian menampilkan kotak pesan dengan nama yang dimasukkan pengguna.

  6. Tempelkan kode berikut dalam NameReporter.xaml file:

    <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. Tambahkan metode berikut ke 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. Anda sekarang dapat membangun proyek WinUIComponentCs untuk menghasilkan sebuah file .winmd untuk komponen.

Nota

Anda juga dapat mengemas komponen sebagai paket NuGet untuk dirujuk konsumen aplikasi akhir. Untuk detail selengkapnya, lihat komponen Authoring C#/WinRT pada repositori C#/WinRT GitHub.

Membuat referensi komponen dari aplikasi C++/WinRT SDK Aplikasi Windows

Langkah-langkah berikut menunjukkan cara menggunakan komponen yang dibuat dari bagian sebelumnya dari aplikasi SDK Aplikasi Windows C++/WinRT. Mengonsumsi komponen C#/WinRT dari C++ saat ini memerlukan penggunaan templat WinUI Blank App (Packaged) proyek tunggal. Perhatikan bahwa komponen C# juga dapat direferensikan dari aplikasi paket C# tanpa pendaftaran kelas.

Konsumsi dari aplikasi paket yang menggunakan proyek Windows Application Packaging (WAP) terpisah saat ini tidak didukung. Lihat komponen Authoring C#/WinRT di repositori C#/WinRT GitHub untuk pembaruan terbaru tentang konfigurasi proyek yang didukung.

  1. Tambahkan proyek aplikasi C++ SDK Aplikasi Windows baru ke solusi Anda. Klik kanan pada solusi Anda di Visual Studio, dan pilih Tambahkan>Baru Project. Pilih templat C++ WinUI Blank App (Packaged) yang disediakan oleh SDK Aplikasi Windows. Untuk panduan ini, kami menamai aplikasi CppApp.

  2. Tambahkan referensi project dari aplikasi C++ ke komponen C#. Di Visual Studio, klik kanan proyek C++ dan pilih Tambahkan>Reference, dan pilih proyek WinUIComponentCs.

    Nota

    Menggunakan komponen sebagai referensi paket NuGet didukung dengan beberapa batasan. Yaitu, komponen dengan kontrol pengguna kustom saat ini tidak dapat digunakan sebagai referensi paket NuGet.

  3. Dalam file header aplikasi pch.h , tambahkan baris berikut:

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

  4. Buka file manifes paket, Package.appxmanifest.

    Nota

    Ada masalah yang diketahui di mana file Package.appxmanifest tidak muncul di Visual Studio Penjelajah Solusi. Untuk mengatasinya, klik kanan pada proyek C++ Anda, pilih Unload Project, dan double-click pada proyek untuk membuka file CppApp.vcxproj. Tambahkan entri berikut ke file project, lalu muat ulang project:

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

    Di Package.appxmanifest, tambahkan pendaftaran kelas yang dapat diaktifkan berikut. Anda juga memerlukan entri tambahan ActivatableClass untuk kelas WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider untuk mengaktifkan jenis WinUI. Klik kanan pada Package.appxmanifest file dan pilih Buka Dengan>XML (Editor Teks) untuk mengedit file.

    <!--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. Buka file MainWindow.xaml.

    i. Tambahkan referensi ke namespace komponen di bagian atas file.

    xmlns:custom="using:WinUIComponentCs"

    ii. Tambahkan kontrol pengguna ke kode XAML yang ada.

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

  6. Atur CppApp sebagai project startup—klik kanan pada CppApp, dan pilih Set sebagai Startup Project. Atur konfigurasi solusi ke x86. Sebelum membangun, Anda mungkin juga perlu menargetkan ulang solusi Anda untuk membangun dengan alat build Visual Studio 2026. Klik kanan pada solusi, pilih Retarget solution, dan upgrade Platform Toolset ke v143.

  7. Buat dan jalankan aplikasi untuk melihat kontrol NameReporter kustom.

Masalah yang diketahui

  • Menggunakan komponen C# sebagai referensi proyek memerlukan PublishReadyToRun diatur ke False. Lihat masalah GitHub #1151 untuk detail selengkapnya.
  • Menggunakan komponen C# yang dibangun untuk AnyCPU dari C++ saat ini hanya didukung oleh aplikasi x86. aplikasi x64 dan Arm64 mengakibatkan kesalahan runtime yang mirip dengan: %1 bukan aplikasi Win32 yang valid. Lihat masalah GitHub #1093 untuk detail selengkapnya.
  • Last updated on