Menggunakan Kepulauan XAML untuk menghosting kontrol UWP XAML di aplikasi C# WPF

Artikel
08/25/2023

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.

Topik ini menunjukkan cara membangun aplikasi C# Windows Presentation Foundation (WPF) (menargetkan .NET Core 3.1) yang menggunakan Kepulauan XAML untuk menghosting kontrol XAML Platform Windows Universal (UWP) (yaitu, kontrol pihak pertama yang disediakan oleh Windows SDK). Kami menunjukkan cara melakukannya dengan dua cara:

Kami menunjukkan cara menghosting kontrol UWP InkCanvas dan InkToolbar dengan menggunakan kontrol yang dibungkus (tersedia di Toolkit Komunitas Windows). Kontrol yang dibungkus membungkus antarmuka dan fungsionalitas sekumpulan kecil kontrol UWP XAML yang berguna. Anda dapat menambahkan kontrol yang dibungkus langsung ke permukaan desain proyek WPF atau Formulir Windows Anda, lalu menggunakannya di perancang seperti kontrol WPF atau Formulir Windows lainnya.
Kami juga menunjukkan cara menghosting kontrol UWP CalendarView dengan menggunakan kontrol WindowsXamlHost (tersedia di Toolkit Komunitas Windows). Karena hanya sekumpulan kecil kontrol UWP XAML yang tersedia sebagai kontrol yang dibungkus, Anda dapat menggunakan WindowsXamlHost untuk menghosting kontrol UWP XAML apa pun.

Proses untuk menghosting kontrol XAML UWP di aplikasi WPF mirip untuk aplikasi Formulir Windows.

Penting

Menggunakan Kepulauan XAML (kontrol yang dibungkus atau WindowsXamlHost) untuk menghosting kontrol XAML UWP hanya didukung di aplikasi yang menargetkan .NET Core 3.x. Kepulauan XAML tidak didukung di aplikasi yang menargetkan .NET, atau di aplikasi yang menargetkan versi .NET Framework apa pun.

Komponen yang direkomendasikan

Untuk menghosting kontrol UWP XAML di WPF atau aplikasi Formulir Windows, kami sarankan Anda memiliki komponen berikut dalam solusi Anda. Topik ini menyediakan instruksi untuk membuat masing-masing komponen ini:

Proyek dan kode sumber untuk aplikasi WPF atau Formulir Windows Anda.
Proyek UWP yang mendefinisikan kelas Aplikasi akar yang berasal dari XamlApplication. Kelas Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication tersedia di Windows Community Toolkit). Kami menyarankan agar Anda menentukan kelas Aplikasi turunan XamlApplication Anda proyek aplikasi UWP terpisah yang merupakan bagian dari solusi WPF atau Formulir Windows Visual Studio Anda.

Catatan

Membuat objek turunan XamlApplication tersedia untuk proyek WPF atau Formulir Windows Anda sebenarnya tidak diperlukan untuk menghosting kontrol XAML UWP pihak pertama. Tetapi perlu untuk menemukan, memuat, dan menghosting kontrol XAML UWP kustom. Jadi—untuk mendukung berbagai skenario XAML Island—kami sarankan Anda selalu menentukan objek turunan XamlApplication dalam solusi apa pun di mana Anda menggunakan Kepulauan XAML.

Catatan

Solusi Anda hanya dapat berisi satu proyek yang menentukan objek turunan XamlApplication. Bahwa satu proyek harus mereferensikan pustaka dan proyek lain yang menghosting kontrol XAML UWP melalui Kepulauan XAML.

Membuat proyek WPF

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

Jika Anda belum melakukannya, instal versi terbaru .NET Core 3.1.
Di Visual Studio, buat proyek C# baru dari templat proyek Aplikasi WPF. Atur Nama proyek ke MyWPFApp sehingga Anda tidak perlu mengedit salah satu langkah atau kode sumber dalam topik ini. Atur Framework ke .NET Core 3.1*, dan klik Buat.

Penting

Pastikan untuk tidak menggunakan templat proyek Aplikasi WPF (.NET Framework).

Mengonfigurasi proyek WPF Anda

Langkah-langkah ini mengaktifkan referensi paket:
1. Di Visual Studio, klik Alat>Manajer Paket NuGet Package Manager>Pengaturan.
2. Di sebelah kanan, temukan pengaturan format manajemen paket Default Manajemen>Paket, dan atur ke PackageReference.
Gunakan langkah-langkah ini untuk menginstal Paket NuGet Microsoft.Toolkit.Wpf.UI.Controls:
1. Klik kanan simpul proyek MyWPFApp di Penjelajah Solusi, dan pilih Kelola Paket NuGet....
2. Pada tab Telusuri , ketik atau tempelkan Microsoft.Toolkit.Wpf.UI.Controls ke dalam kotak pencarian. Pilih versi stabil terbaru, dan klik Instal. Paket itu menyediakan semua yang Anda butuhkan untuk menggunakan kontrol UWP XAML yang dibungkus untuk WPF (termasuk InkCanvas, InkToolbar, dan kontrol WindowsXamlHost).
Catatan

Untuk aplikasi Formulir Windows, referensikan paket Microsoft.Toolkit.Forms.UI.Controls sebagai gantinya.
Sebagian besar skenario Kepulauan XAML tidak didukung dalam proyek yang menargetkan CPU Apa pun. Jadi untuk menargetkan arsitektur tertentu (seperti x86 atau x64), lakukan hal berikut:
1. Klik kanan simpul solusi (bukan simpul proyek) di Penjelajah Solusi, dan pilih Properti.
2. Pilih Properti Konfigurasi di sebelah kiri.
3. Klik tombol Configuration Manager... .
4. Di bawah Platform solusi aktif, pilih Baru.
5. Dalam dialog Platform Solusi Baru, pilih x64 atau x86, dan tekan OK.
6. Tutup kotak dialog yang terbuka.

Menentukan kelas XamlApplication dalam proyek UWP baru

Di bagian ini kita akan menambahkan proyek UWP ke solusi, dan merevisi kelas Aplikasi default dalam proyek tersebut untuk berasal dari kelas Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication yang disediakan oleh Windows Community Toolkit. Kelas tersebut 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 itu juga menginisialisasi kerangka kerja UWP XAML untuk utas saat ini.

Di Penjelajah Solusi, klik kanan simpul solusi, dan pilih Tambahkan>Proyek Baru....
Pilih templat proyek C# Blank App (Universal Windows). Atur Nama proyek ke MyUWPApp sehingga Anda tidak perlu mengedit salah satu langkah atau kode sumber dalam topik ini. Atur Versi target dan Versi minimum ke Windows 10, versi 1903 (Build 18362) atau yang lebih baru.

Catatan

Pastikan untuk tidak membuat MyUWPApp di subfolder MyWPFApp. Jika Anda melakukan itu, maka MyWPFApp akan mencoba membangun markup UWP XAML seolah-olah itu WPF XAML.
Di MyUWPApp, instal paket NuGet Microsoft.Toolkit.Win32.UI.XamlApplication (versi stabil terbaru). Proses untuk menginstal paket NuGet dijelaskan di bagian sebelumnya.

Di MyUWPApp, buka App.xaml file, dan ganti kontennya dengan XAML berikut:

<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>

Demikian pula, buka App.xaml.cs, dan ganti kontennya dengan kode berikut:

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

MainPage.xaml Hapus file dan MainPage.xaml.cs .
Bangun proyek MyUWPApp.

Di MyWPFApp, tambahkan referensi ke proyek MyUWPApp

Tentukan versi kerangka kerja yang kompatibel dalam file proyek MyWPFApp seperti ini:
1. Di Penjelajah Solusi, klik simpul proyek MyWPFApp untuk membuka file proyek di editor.
2. Di dalam elemen PropertyGroup pertama, tambahkan elemen turunan berikut. 19041 Ubah bagian nilai seperlunya agar sesuai dengan target dan build OS minimum proyek MyWPFApp.
```
<AssetTargetFallback>uap10.0.19041</AssetTargetFallback>
```
Di Penjelajah Solusi, klik kanan Dependensi MyWPFApp>, pilih Tambahkan Referensi Proyek..., dan tambahkan referensi ke proyek MyUWPApp.

Membuat instans objek XamlApplication di titik masuk MyWPFApp

Selanjutnya, tambahkan kode ke titik masuk MyWPFApp untuk membuat instans kelas Aplikasi yang baru saja Anda tentukan di MyUWPApp (kelas yang berasal dari XamlApplication).

Klik kanan simpul proyek MyWPFApp, pilih Tambahkan>Item Baru... , lalu pilih Kelas. Atur Nama ke Program.cs, dan klik Tambahkan.

Ganti konten Program.cs dengan XAML berikut (lalu simpan file dan bangun proyek MyWPFApp ):

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

Klik kanan simpul proyek MyWPFApp , dan pilih Properti.
Di Umum Aplikasi>, klik menu drop-down objek Startup, dan pilih MyWPFApp.Program (yang merupakan nama kelas Program yang sepenuhnya memenuhi syarat yang baru saja Anda tambahkan). Jika Anda tidak melihatnya, coba tutup dan buka kembali Visual Studio.

Catatan

Secara default, proyek WPF mendefinisikan fungsi Titik entri utama dalam file kode yang dihasilkan yang tidak dimaksudkan untuk dimodifikasi. Langkah di atas mengubah titik masuk untuk proyek Anda ke metode Utama kelas Program baru, yang memungkinkan Anda menambahkan kode yang berjalan sedini mungkin dalam proses startup aplikasi.
Simpan perubahan Anda ke properti proyek.

Gunakan kontrol yang dibungkus untuk menghosting InkCanvas dan InkToolbar

Setelah mengonfigurasi proyek untuk menggunakan UWP XAML Islands, Anda siap untuk menambahkan kontrol InkCanvas dan InkToolbar yang dibungkus UWP XAML ke aplikasi.

Di MyWPFApp, buka MainWindow.xaml file .
Di elemen Window di dekat bagian atas file XAML, tambahkan atribut berikut. Atribut ini mereferensikan namespace XAML untuk kontrol UWP XAML yang dibungkus InkCanvas dan InkToolbar , dan memetakannya ke namespace XML kontrol .
```
xmlns:controls="clr-namespace:Microsoft.Toolkit.Wpf.UI.Controls;assembly=Microsoft.Toolkit.Wpf.UI.Controls"
```

Masih dalam MainWindow.xaml, edit elemen Grid yang ada sehingga terlihat seperti XAML di bawah ini. XAML ini menambahkan ke Grid inkCanvas dan kontrol InkToolbar (diawali oleh namespace xml kontrol yang Anda tentukan di langkah sebelumnya).

<Grid Margin="10,50,10,10">
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="Auto"/>
    </Grid.RowDefinitions>
    <controls:InkToolbar x:Name="myInkToolbar" TargetInkCanvas="{x:Reference myInkCanvas}" Grid.Row="0" Width="300"
        Height="50" Margin="10,10,10,10" HorizontalAlignment="Left" VerticalAlignment="Top" />
    <controls:InkCanvas x:Name="myInkCanvas" Grid.Row="1" HorizontalAlignment="Left" Width="600" Height="400"
        Margin="10,10,10,10" VerticalAlignment="Top" />
</Grid>

Catatan

Anda juga dapat menambahkan kontrol yang dibungkus ini dan lainnya ke Jendela dengan menyeretnya ke perancang dari bagian Toolkit Komunitas Windows di Kotak Alat.

Simpan MainWindow.xaml.

Jika Anda memiliki perangkat yang mendukung pena digital (seperti Surface), dan Anda mengikuti komputer fisik, maka Anda sekarang dapat membangun dan menjalankan aplikasi, dan menggambar tinta digital di layar dengan pena. Tetapi jika Anda mencoba menulis dengan mouse Anda, maka tidak ada yang akan terjadi, karena secara default InkCanvas diaktifkan hanya untuk pena digital. Berikut cara mengaktifkan InkCanvas untuk mouse.
Masih di MyWPFApp, buka MainWindow.xaml.cs.

Tambahkan direktif namespace berikut ke bagian atas file:

using Microsoft.Toolkit.Win32.UI.Controls.Interop.WinRT;

Temukan konstruktor MainWindow. Segera setelah panggilan ke InitializeComponent, tambahkan baris kode berikut:
```
myInkCanvas.InkPresenter.InputDeviceTypes = CoreInputDeviceTypes.Mouse | CoreInputDeviceTypes.Pen;
```
Anda dapat menggunakan objek InkPresenter untuk menyesuaikan pengalaman penintaan default. Kode di atas menggunakan properti InputDeviceTypes untuk mengaktifkan mouse serta input pena.
Simpan, bangun, dan jalankan. Jika Anda menggunakan komputer dengan mouse, konfirmasikan bahwa Anda dapat menggambar sesuatu di ruang kanvas tinta dengan mouse.

Menghosting CalendarView dengan menggunakan kontrol host

Di bagian ini, kita akan menggunakan kontrol WindowsXamlHost untuk menambahkan CalendarView ke aplikasi.

Catatan

Kontrol WindowsXamlHost disediakan oleh paket Microsoft.Toolkit.Wpf.UI.XamlHost. Paket tersebut disertakan dengan paket Microsoft.Toolkit.Wpf.UI.Controls yang Anda instal sebelumnya.

Di Penjelajah Solusi, di MyWPFApp, buka MainWindow.xaml file .
Di elemen Window di dekat bagian atas file XAML, tambahkan atribut berikut. Atribut ini mereferensikan namespace XAML untuk kontrol WindowsXamlHost , dan memetakannya ke namespace XML xamlhost .
```
xmlns:xamlhost="clr-namespace:Microsoft.Toolkit.Wpf.UI.XamlHost;assembly=Microsoft.Toolkit.Wpf.UI.XamlHost"
```
Masih dalam MainWindow.xaml, edit elemen Grid yang ada sehingga terlihat seperti XAML di bawah ini. XAML ini menambahkan ke Gridkontrol WindowsXamlHost (diawali oleh namespace xml xamlhost yang Anda tentukan di langkah sebelumnya). Untuk menghosting kontrol UWP CalendarView, XAML ini mengatur properti InitialTypeName ke nama kontrol yang sepenuhnya memenuhi syarat. XAML juga mendefinisikan penanganan aktivitas untuk peristiwa ChildChanged, yang dinaikkan ketika kontrol yang dihosting telah dirender.
```
<Grid Margin="10,50,10,10">
    <xamlhost:WindowsXamlHost x:Name="myCalendar" InitialTypeName="Windows.UI.Xaml.Controls.CalendarView"
          Margin="10,10,10,10" Width="600" Height="300" ChildChanged="MyCalendar_ChildChanged" />
</Grid>
```
Simpan MainWindow.xaml, dan buka MainWindow.xaml.cs.
Hapus baris kode ini, yang kami tambahkan di bagian sebelumnya: myInkCanvas.InkPresenter.InputDeviceTypes = CoreInputDeviceTypes.Mouse | CoreInputDeviceTypes.Pen;.
Tambahkan direktif namespace berikut ke bagian atas file:
```
using Microsoft.Toolkit.Wpf.UI.XamlHost;
```

Tambahkan metode penanganan aktivitas ChildChanged berikut ke kelas MainWindow. Ketika kontrol host telah dirender, penanganan aktivitas ini berjalan dan membuat penanganan aktivitas sederhana untuk peristiwa SelectedDatesChanged kontrol kalender.

private void MyCalendar_ChildChanged(object sender, EventArgs e)
{
    WindowsXamlHost windowsXamlHost = (WindowsXamlHost)sender;

    var calendarView =
        (Windows.UI.Xaml.Controls.CalendarView)windowsXamlHost.Child;

    if (calendarView != null)
    {
        calendarView.SelectedDatesChanged += (obj, args) =>
        {
            if (args.AddedDates.Count > 0)
            {
                MessageBox.Show("The user selected a new date: " +
                    args.AddedDates[0].DateTime.ToString());
            }
        };
    }
}

Simpan, bangun, dan jalankan. Konfirmasikan bahwa kontrol kalender ditampilkan di jendela, dan bahwa kotak pesan ditampilkan saat Anda memilih tanggal.

Mengemas aplikasi

Anda dapat secara opsional mengemas aplikasi WPF Anda dalam paket MSIX untuk penyebaran. MSIX adalah teknologi kemasan aplikasi modern dan andal untuk Windows.

Instruksi berikut menunjukkan kepada Anda cara mengemas semua komponen dalam solusi ke dalam paket MSIX dengan menggunakan Proyek Pengemasan Aplikasi Windows di Visual Studio (lihat Menyiapkan aplikasi desktop Anda untuk pengemasan MSIX di Visual Studio). 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 .

Tambahkan proyek baru ke solusi Anda yang dibuat dari templat proyek Proyek Kemasan Aplikasi Windows. Saat Anda membuat proyek, pilih versi Target yang sama dan Versi minimum seperti yang Anda pilih untuk proyek UWP.
Dalam proyek pengemasan, klik kanan simpul Dependensi , dan pilih Tambahkan Referensi Proyek.... Dalam daftar proyek, pilih MyWPFApp, dan klik OK.

Catatan

Jika Anda ingin menerbitkan aplikasi di Microsoft Store, maka Anda juga harus menambahkan referensi ke proyek UWP dalam proyek kemasan.
Jika Anda mengikuti langkah-langkah hingga titik ini, maka semua proyek dalam solusi Anda akan menargetkan platform tertentu yang sama (x86 atau x64). Dan itu diperlukan untuk membangun aplikasi WPF ke dalam paket MSIX menggunakan Proyek Kemasan Aplikasi Windows. Untuk mengonfirmasinya, Anda dapat mengikuti langkah-langkah berikut:
1. Klik kanan simpul solusi (bukan simpul proyek) di Penjelajah Solusi, dan pilih Properti.
2. Pilih Properti Konfigurasi di sebelah kiri.
3. Klik tombol Configuration Manager... .
4. Konfirmasikan bahwa semua proyek yang tercantum memiliki nilai yang sama di bawah Platform: x86 atau x64.
Klik kanan simpul proyek untuk proyek pengemasan yang baru saja Anda tambahkan, dan klik Atur sebagai proyek Startup.
Bangun dan jalankan proyek pengemasan. Konfirmasikan bahwa aplikasi WPF berjalan, dan bahwa kontrol UWP ditampilkan seperti yang diharapkan.
Untuk informasi tentang mendistribusikan/menyebarkan paket, lihat Mengelola penyebaran MSIX Anda.

Menggunakan Kepulauan XAML untuk menghosting kontrol UWP XAML di aplikasi C# WPF

Komponen yang direkomendasikan

Membuat proyek WPF

Mengonfigurasi proyek WPF Anda

Menentukan kelas XamlApplication dalam proyek UWP baru

Di MyWPFApp, tambahkan referensi ke proyek MyUWPApp

Membuat instans objek XamlApplication di titik masuk MyWPFApp

Gunakan kontrol yang dibungkus untuk menghosting InkCanvas dan InkToolbar

Menghosting CalendarView dengan menggunakan kontrol host

Mengemas aplikasi

Saran dan Komentar

Sumber Daya Tambahan:

Menggunakan Kepulauan XAML untuk menghosting kontrol UWP XAML di aplikasi C# WPF

Komponen yang direkomendasikan

Membuat proyek WPF

Mengonfigurasi proyek WPF Anda

Menentukan kelas XamlApplication dalam proyek UWP baru

Di MyWPFApp, tambahkan referensi ke proyek MyUWPApp

Membuat instans objek XamlApplication di titik masuk MyWPFApp

Gunakan kontrol yang dibungkus untuk menghosting InkCanvas dan InkToolbar

Menghosting CalendarView dengan menggunakan kontrol host

Mengemas aplikasi

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: