Bagikan melalui

Menghosting kontrol WinRT XAML kustom di aplikasi WPF menggunakan Kepulauan XAML

  • Artikel

Penting

Topik ini menggunakan atau menyebutkan jenis dari repositori GitHub CommunityToolkit/Microsoft.Toolkit.Win32 . Untuk informasi penting tentang dukungan Kepulauan XAML, silakan lihat Pemberitahuan Kepulauan XAML di repositori tersebut.

Artikel ini menunjukkan cara menggunakan kontrol WindowsXamlHost di Windows Community Toolkit untuk menghosting kontrol WinRT XAML kustom di aplikasi WPF yang menargetkan .NET Core 3.1. Kontrol kustom berisi beberapa kontrol pihak pertama dari Windows SDK dan mengikat properti di salah satu kontrol WinRT XAML ke string di aplikasi WPF. Artikel ini juga menunjukkan cara juga menghosting kontrol dari pustaka WinUI.

Meskipun artikel ini menunjukkan cara melakukan ini di aplikasi WPF, prosesnya mirip untuk aplikasi Formulir Windows. Untuk gambaran umum tentang menghosting kontrol WinRT XAML di WPF dan aplikasi Formulir Windows, lihat artikel ini.

Catatan

Menggunakan Kepulauan XAML untuk menghosting kontrol WinRT XAML di WPF dan aplikasi Formulir Windows saat ini hanya didukung di aplikasi yang menargetkan .NET Core 3.x. Kepulauan XAML belum didukung di aplikasi yang menargetkan .NET, atau di aplikasi yang versi .NET Framework apa pun.

Komponen yang Diperlukan

Untuk menghosting kontrol WinRT XAML kustom di aplikasi WPF (atau Formulir Windows), Anda memerlukan komponen berikut dalam solusi Anda. Artikel ini menyediakan instruksi untuk membuat masing-masing komponen ini.

  • Proyek dan kode sumber untuk aplikasi Anda. Menggunakan kontrol WindowsXamlHost untuk menghosting kontrol kustom hanya didukung di aplikasi yang menargetkan .NET Core 3.x.

  • Kontrol WinRT XAML kustom. Anda akan memerlukan kode sumber untuk kontrol kustom yang ingin Anda host sehingga Anda dapat mengkompilasinya dengan aplikasi Anda. Biasanya, kontrol kustom ditentukan dalam proyek pustaka kelas UWP yang Anda referensikan dalam solusi yang sama dengan proyek WPF atau Formulir Windows Anda.

  • Proyek aplikasi UWP yang mendefinisikan kelas Aplikasi akar yang berasal dari XamlApplication. Proyek WPF atau Formulir Windows Anda harus memiliki akses ke instans kelas Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication yang disediakan oleh Windows Community Toolkit sehingga dapat menemukan dan memuat kontrol UWP XAML kustom. Cara yang disarankan untuk melakukan ini adalah dengan menentukan objek ini dalam proyek aplikasi UWP terpisah yang merupakan bagian dari solusi untuk WPF atau aplikasi Formulir Windows Anda.

    Catatan

    Solusi Anda hanya dapat berisi satu proyek yang menentukan XamlApplication objek. Semua kontrol WinRT XAML kustom di aplikasi Anda memiliki objek yang sama XamlApplication . Proyek yang mendefinisikan XamlApplication objek harus menyertakan referensi ke semua pustaka WinRT lainnya dan proyek yang digunakan host untuk mengontrol di Pulau XAML.

Membuat proyek WPF

Sebelum memulai, ikuti instruksi ini untuk membuat proyek WPF dan mengonfigurasinya untuk menghosting Kepulauan XAML. Jika Anda memiliki proyek WPF yang sudah ada, Anda dapat menyesuaikan langkah-langkah dan contoh kode ini untuk proyek Anda.

Catatan

Jika Anda memiliki proyek yang sudah ada yang menargetkan .NET Framework, Anda harus memigrasikan proyek Anda ke .NET Core 3.1. Untuk informasi selengkapnya, lihat seri blog ini.

  1. Jika Anda belum melakukannya, instal versi terbaru .NET Core 3.1 SDK.

  2. Di Visual Studio 2019, buat proyek WPF App (.NET Core) baru.

  3. Pastikan referensi paket diaktifkan:

    1. Di Visual Studio, klik Alat -> Pengelola Paket NuGet -> Pengaturan Manajer Paket.
    2. Pastikan PackageReference dipilih untuk Format manajemen paket default.

  4. Klik kanan proyek WPF Anda di Penjelajah Solusi dan pilih Kelola Paket NuGet.

  5. Pilih tab Telusuri , cari paket Microsoft.Toolkit.Wpf.UI.XamlHost dan instal versi stabil terbaru. Paket ini menyediakan semua yang Anda butuhkan untuk menggunakan kontrol WindowsXamlHost untuk menghosting kontrol WinRT XAML, termasuk paket NuGet terkait lainnya.

    Catatan

    aplikasi Formulir Windows harus menggunakan Paket Microsoft.Toolkit.Forms.UI.XamlHost.

  6. Konfigurasikan solusi Anda untuk menargetkan platform tertentu seperti x86 atau x64. Kontrol WinRT XAML kustom tidak didukung dalam proyek yang menargetkan CPU Apa pun.

    1. Di Penjelajah Solusi, klik kanan simpul solusi dan pilih Properti ->Konfigurasi Properti ->Configuration Manager.
    2. Di bawah Platform solusi aktif, pilih Baru.
    3. Dalam dialog Platform Solusi Baru, pilih x64 atau x86 dan tekan OK.
    4. Tutup kotak dialog yang terbuka.

Menentukan kelas XamlApplication dalam proyek aplikasi UWP

Selanjutnya, tambahkan proyek aplikasi UWP ke solusi Anda dan revisi kelas default App dalam proyek ini untuk berasal dari kelas Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication yang disediakan oleh Windows Community Toolkit. Kelas ini mendukung antarmuka IXamlMetadataProvider , yang memungkinkan aplikasi Anda menemukan dan memuat metadata untuk kontrol XAML UWP kustom dalam rakitan di direktori aplikasi Anda saat ini pada waktu proses. Kelas ini juga menginisialisasi kerangka kerja UWP XAML untuk utas saat ini.

  1. Di Penjelajah Solusi, klik kanan simpul solusi dan pilih Tambahkan ->Proyek Baru.

  2. Tambahkan proyek Aplikasi Kosong (Universal Windows) ke solusi Anda. Pastikan versi target dan versi minimum keduanya diatur ke Windows 10, versi 1903 (Build 18362) atau rilis yang lebih baru.

  3. Dalam proyek aplikasi UWP, instal paket NuGet Microsoft.Toolkit.Win32.UI.XamlApplication (versi stabil terbaru).

  4. Buka file App.xaml dan ganti konten file ini dengan XAML berikut. Ganti MyUWPApp dengan namespace proyek aplikasi UWP Anda.

    <xaml:XamlApplication
    x:Class="MyUWPApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:xaml="using:Microsoft.Toolkit.Win32.UI.XamlHost"
    xmlns:local="using:MyUWPApp">
</xaml:XamlApplication>

  5. Buka file App.xaml.cs dan ganti isi file ini dengan kode berikut. Ganti MyUWPApp dengan namespace proyek aplikasi UWP Anda.

    namespace MyUWPApp
{
    public sealed partial class App : Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication
    {
        public App()
        {
            this.Initialize();
        }
    }
}

  6. Hapus file MainPage.xaml dari proyek aplikasi UWP.

  7. Bersihkan proyek aplikasi UWP lalu buat.

Menambahkan referensi ke proyek UWP di proyek WPF Anda

  1. Tentukan versi kerangka kerja yang kompatibel dalam file proyek WPF.

    1. Di Penjelajah Solusi, klik dua kali simpul proyek WPF untuk membuka file proyek di editor.

    2. Di elemen PropertyGroup pertama, tambahkan elemen turunan berikut. 19041 Ubah bagian nilai seperlunya agar sesuai dengan target dan build OS minimum proyek UWP.

      <AssetTargetFallback>uap10.0.19041</AssetTargetFallback>

      Setelah selesai, elemen PropertyGroup akan terlihat mirip dengan ini.

      <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <UseWPF>true</UseWPF>
    <Platforms>AnyCPU;x64</Platforms>
    <AssetTargetFallback>uap10.0.19041</AssetTargetFallback>
</PropertyGroup>

  2. Di Penjelajah Solusi, klik kanan simpul Dependensi di bawah proyek WPF dan tambahkan referensi ke proyek aplikasi UWP Anda.

Membuat instans objek XamlApplication di titik masuk aplikasi WPF Anda

Selanjutnya, tambahkan kode ke titik masuk untuk aplikasi WPF Anda untuk membuat instans App kelas yang baru saja Anda tentukan dalam proyek UWP (ini adalah kelas yang sekarang berasal dari XamlApplication).

  1. Di proyek WPF Anda, klik kanan simpul proyek, pilih Tambahkan ->Item Baru, lalu pilih Kelas. Beri nama program kelas dan klik Tambahkan.

  2. Ganti kelas yang dihasilkan Program dengan kode berikut lalu simpan file. Ganti MyUWPApp dengan namespace proyek aplikasi UWP Anda, dan ganti MyWPFApp dengan namespace proyek aplikasi WPF Anda.

    public class Program
{
    [System.STAThreadAttribute()]
    public static void Main()
    {
        using (new MyUWPApp.App())
        {
            MyWPFApp.App app = new MyWPFApp.App();
            app.InitializeComponent();
            app.Run();
        }
    }
}

  3. Klik kanan simpul proyek dan pilih Properti.

  4. Pada tab Aplikasi properti, klik menu drop-down Objek startup dan pilih nama kelas yang sepenuhnya memenuhi syarat yang Program Anda tambahkan di langkah sebelumnya.

    Catatan

    Secara default, proyek WPF menentukan Main fungsi titik masuk dalam file kode yang dihasilkan yang tidak dimaksudkan untuk dimodifikasi. Langkah ini mengubah titik masuk untuk proyek Anda ke Main metode kelas baru Program , yang memungkinkan Anda menambahkan kode yang berjalan sedini mungkin dalam proses startup aplikasi.

  5. Simpan perubahan Anda ke properti proyek.

Membuat kontrol WinRT XAML kustom

Untuk menghosting kontrol WinRT XAML kustom di aplikasi WPF, Anda harus memiliki kode sumber untuk kontrol sehingga Anda dapat mengkompilasinya dengan aplikasi Anda. Biasanya kontrol kustom didefinisikan dalam proyek pustaka kelas UWP untuk portabilitas yang mudah.

Di bagian ini, Anda akan menentukan kontrol kustom sederhana dalam proyek pustaka kelas baru. Anda dapat menentukan kontrol kustom di proyek aplikasi UWP yang Anda buat di bagian sebelumnya. Namun, langkah-langkah ini melakukan ini dalam proyek pustaka kelas terpisah untuk tujuan ilustrasi karena ini biasanya bagaimana kontrol kustom diterapkan untuk portabilitas.

Jika Anda sudah memiliki kontrol kustom, Anda dapat menggunakannya alih-alih kontrol yang diperlihatkan di sini. Namun, Anda masih perlu mengonfigurasi proyek yang berisi kontrol seperti yang ditunjukkan dalam langkah-langkah ini.

  1. Di Penjelajah Solusi, klik kanan simpul solusi dan pilih Tambahkan ->Proyek Baru.

  2. Tambahkan proyek Pustaka Kelas (Universal Windows) ke solusi Anda. Pastikan versi target dan versi minimum diatur ke target yang sama dan build OS minimum sebagai proyek UWP.

  3. Klik kanan file proyek dan pilih Bongkar Proyek. Klik kanan file proyek lagi dan pilih Edit.

  4. Sebelum elemen penutup </Project> , tambahkan XML berikut untuk menonaktifkan beberapa properti lalu simpan file proyek. Properti ini harus diaktifkan untuk menghosting kontrol kustom di aplikasi WPF (atau Formulir Windows).

    <PropertyGroup>
  <EnableTypeInfoReflection>false</EnableTypeInfoReflection>
  <EnableXBindDiagnostics>false</EnableXBindDiagnostics>
</PropertyGroup>

  5. Klik kanan file proyek dan pilih Muat Ulang Proyek.

  6. Hapus file Class1.cs default dan tambahkan item Kontrol Pengguna baru ke proyek.

  7. Dalam file XAML untuk kontrol pengguna, tambahkan yang berikut ini StackPanel sebagai turunan dari default Grid. Contoh ini menambahkan TextBlock kontrol lalu mengikat Text atribut kontrol tersebut ke XamlIslandMessage bidang .

    <StackPanel Background="LightCoral">
    <TextBlock>This is a simple custom WinRT XAML control</TextBlock>
    <Rectangle Fill="Blue" Height="100" Width="100"/>
    <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
</StackPanel>

  8. Dalam file code-behind untuk kontrol pengguna, tambahkan XamlIslandMessage bidang ke kelas kontrol pengguna seperti yang ditunjukkan di bawah ini.

    public sealed partial class MyUserControl : UserControl
{
    public string XamlIslandMessage { get; set; }

    public MyUserControl()
    {
        this.InitializeComponent();
    }
}

  9. Bangun proyek pustaka kelas UWP.

  10. Dalam proyek WPF Anda, klik kanan simpul Dependensi dan tambahkan referensi ke proyek pustaka kelas UWP.

  11. Di proyek aplikasi UWP yang Anda konfigurasi sebelumnya, klik kanan simpul Referensi dan tambahkan referensi ke proyek pustaka kelas UWP.

  12. Bangun kembali seluruh solusi dan pastikan semua proyek berhasil dibangun.

Menghosting kontrol WinRT XAML kustom di aplikasi WPF Anda

  1. Di Penjelajah Solusi, perluas proyek WPF dan buka file MainWindow.xaml atau beberapa jendela lain tempat Anda ingin menghosting kontrol kustom.

  2. Dalam file XAML, tambahkan deklarasi namespace berikut ke <Window> elemen .

    xmlns:xaml="clr-namespace:Microsoft.Toolkit.Wpf.UI.XamlHost;assembly=Microsoft.Toolkit.Wpf.UI.XamlHost"

  3. Dalam file yang sama, tambahkan kontrol berikut ke <Grid> elemen . InitialTypeName Ubah atribut ke nama kontrol pengguna yang sepenuhnya memenuhi syarat di proyek pustaka kelas UWP Anda.

    <xaml:WindowsXamlHost InitialTypeName="UWPClassLibrary.MyUserControl" ChildChanged="WindowsXamlHost_ChildChanged" />

  4. Buka file code-behind dan tambahkan kode berikut ke Window kelas . Kode ini mendefinisikan ChildChanged penanganan aktivitas yang menetapkan nilai XamlIslandMessage bidang kontrol kustom UWP ke nilai WPFMessage bidang di aplikasi WPF. Ubah UWPClassLibrary.MyUserControl ke nama kontrol pengguna yang sepenuhnya memenuhi syarat di proyek pustaka kelas UWP Anda.

    private void WindowsXamlHost_ChildChanged(object sender, EventArgs e)
{
    // Hook up x:Bind source.
    global::Microsoft.Toolkit.Wpf.UI.XamlHost.WindowsXamlHost windowsXamlHost =
        sender as global::Microsoft.Toolkit.Wpf.UI.XamlHost.WindowsXamlHost;
    global::UWPClassLibrary.MyUserControl userControl =
        windowsXamlHost.GetUwpInternalObject() as global::UWPClassLibrary.MyUserControl;

    if (userControl != null)
    {
        userControl.XamlIslandMessage = this.WPFMessage;
    }
}

public string WPFMessage
{
    get
    {
        return "Binding from WPF to UWP XAML";
    }
}

  5. Buat dan jalankan aplikasi Anda dan konfirmasikan bahwa kontrol pengguna UWP ditampilkan seperti yang diharapkan.

Menambahkan kontrol dari pustaka WinUI 2 ke kontrol kustom

Secara tradisional, kontrol WinRT XAML telah dirilis sebagai bagian dari OS Windows dan tersedia untuk pengembang melalui Windows SDK. Pustaka WinUI adalah pendekatan alternatif, di mana versi kontrol WinRT XAML yang diperbarui dari Windows SDK didistribusikan dalam paket NuGet yang tidak terkait dengan rilis Windows SDK. Pustaka ini juga mencakup kontrol baru yang bukan bagian dari Windows SDK dan platform UWP default.

Bagian ini menunjukkan cara menambahkan kontrol WinRT XAML dari pustaka WinUI 2 ke kontrol pengguna Anda.

Catatan

Saat ini, Kepulauan XAML hanya mendukung kontrol hosting dari pustaka WinUI 2. Dukungan untuk kontrol hosting dari pustaka WinUI 3 akan hadir dalam rilis selanjutnya.

  1. Dalam proyek aplikasi UWP, instal versi rilis atau prarilis terbaru dari paket NuGet Microsoft.UI.Xaml .

    Catatan

    Jika aplikasi desktop Anda dipaketkan dalam paket MSIX, Anda dapat menggunakan versi prarilis atau rilis paket NugGet Microsoft.UI.Xaml . Jika aplikasi desktop Anda tidak dipaketkan menggunakan MSIX, Anda harus menginstal versi prarilis paket NuGet Microsoft.UI.Xaml .

  2. Dalam file App.xaml dalam proyek ini, tambahkan elemen turunan berikut ke <xaml:XamlApplication> elemen .

    <Application.Resources>
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
</Application.Resources>

    Setelah menambahkan elemen ini, konten file ini sekarang akan terlihat mirip dengan ini.

    <xaml:XamlApplication
    x:Class="MyUWPApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:xaml="using:Microsoft.Toolkit.Win32.UI.XamlHost"
    xmlns:local="using:MyUWPApp">
    <Application.Resources>
        <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
    </Application.Resources>
</xaml:XamlApplication>

  3. Dalam proyek pustaka kelas UWP, instal versi terbaru paket NuGet Microsoft.UI.Xaml (versi yang sama dengan yang Anda instal di proyek aplikasi UWP).

  4. Dalam proyek yang sama, buka file XAML untuk kontrol pengguna dan tambahkan deklarasi namespace berikut ke <UserControl> elemen .

    xmlns:winui="using:Microsoft.UI.Xaml.Controls"

  5. Dalam file yang sama, tambahkan <winui:RatingControl /> elemen sebagai anak dari <StackPanel>. Elemen ini menambahkan instans kelas RatingControl dari pustaka WinUI. Setelah menambahkan elemen ini, <StackPanel> sekarang akan terlihat mirip dengan ini.

    <StackPanel Background="LightCoral">
    <TextBlock>This is a simple custom WinRT XAML control</TextBlock>
    <Rectangle Fill="Blue" Height="100" Width="100"/>
    <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
    <winui:RatingControl />
</StackPanel>

  6. Buat dan jalankan aplikasi Anda dan konfirmasikan bahwa kontrol peringkat baru ditampilkan seperti yang diharapkan.

Mengemas aplikasi

Anda dapat secara opsional mengemas aplikasi WPF dalam paket MSIX untuk penyebaran. MSIX adalah teknologi pengemasan aplikasi modern untuk Windows, dan didasarkan pada kombinasi teknologi penginstalan MSI, .appx, App-V, dan ClickOnce.

Instruksi berikut menunjukkan kepada Anda cara mengemas semua komponen dalam solusi dalam paket MSIX dengan menggunakan Proyek Pengemasan Aplikasi Windows di Visual Studio 2019. Langkah-langkah ini diperlukan hanya jika Anda ingin mengemas aplikasi WPF dalam paket MSIX.

Catatan

Jika Anda memilih untuk tidak mengemas aplikasi Anda dalam paket MSIX untuk penyebaran, komputer yang menjalankan aplikasi Anda harus menginstal Visual C++ Runtime .

  1. Tambahkan Proyek Pengemasan Aplikasi Windows baru ke solusi Anda. Saat Anda membuat proyek, pilih versi Target yang sama dan Versi minimum seperti yang Anda pilih untuk proyek UWP.

  2. Dalam proyek pengemasan, klik kanan simpul Aplikasi dan pilih Tambahkan referensi. Dalam daftar proyek, pilih proyek WPF dalam solusi Anda dan klik OK.

    Catatan

    Jika Anda ingin menerbitkan aplikasi di Microsoft Store, Anda harus menambahkan referensi ke proyek UWP dalam proyek pengemasan.

  3. Konfigurasikan solusi Anda untuk menargetkan platform tertentu seperti x86 atau x64. Ini diperlukan untuk membangun aplikasi WPF ke dalam paket MSIX menggunakan Proyek Kemasan Aplikasi Windows.

    1. Di Penjelajah Solusi, klik kanan simpul solusi dan pilih Properti ->Konfigurasi Properti ->Configuration Manager.
    2. Di bawah Platform solusi aktif, pilih x64 atau x86.
    3. Di baris untuk proyek WPF Anda, di kolom Platform pilih Baru.
    4. Dalam dialog Platform Solusi Baru, pilih x64 atau x86 (platform yang sama dengan yang Anda pilih untuk platform solusi Aktif) dan klik OK.
    5. Tutup kotak dialog yang terbuka.

  4. Bangun dan jalankan proyek pengemasan. Konfirmasikan bahwa WPF berjalan dan kontrol kustom UWP ditampilkan seperti yang diharapkan.

  5. Untuk informasi tentang mendistribusikan/menyebarkan paket, lihat Mengelola penyebaran MSIX Anda.

Mengatasi kesalahan "Tidak dapat menemukan Sumber Daya" saat menghosting kontrol WinUI

Jika Anda menghosting kontrol kustom yang berisi kontrol dari pustaka WinUI, Anda mungkin mengalami masalah di mana kontrol tidak dapat dimuat dalam aplikasi paket dan men-debug kode menunjukkan kesalahan berikut.

Gagal menghosting kontrol pustaka WinUI

Untuk mengatasi kesalahan ini, salin file App.xbf dari folder output build proyek WPF ke folder output build proyek> \AppX\<WPF dari proyek pengemasan.

Misalnya, jika proyek WPF diberi nama WPFXamlIslandsApp dan menargetkan platform x86, salin App.xbf dari \WPFXamlIslandsApp\bin\x86\Release\netcoreapp3.1 ke \WPFXamlIslandsApp.Pack\bin\x86\Release\AppX\WPFXamlIslandsAPP.