Masaüstü uygulamalarında (XAML Adaları) WinRT XAML denetimlerini barındırma

Önemli

Bu konu başlığında CommunityToolkit/Microsoft.Toolkit.Win32 GitHub deposundaki türler kullanılmaktadır veya bu türlerden bahsedilmektedir. XAML Adaları desteği hakkında önemli bilgiler için lütfen bu depodaki XAML Adaları Bildirimi bakın.

Windows 10, sürüm 1903'ten başlayarak, XAML Adaları adlı bir özelliği kullanarak UWP olmayan masaüstü uygulamalarında WinRT XAML denetimlerini barındırabilirsiniz. Bu özellik, mevcut WPF, Windows Forms ve C++ masaüstü (Win32) uygulamalarınızın genel görünümünü ve işlevselliğini yalnızca WinRT XAML denetimleri aracılığıyla kullanılabilen en son Windows kullanıcı arabirimi özellikleriyle geliştirmenizi sağlar. Bu, Windows Ink gibi UWP özelliklerini ve mevcut WPF, Windows Forms ve C++ masaüstü uygulamalarınızda Fluent Design System'i destekleyen denetimleri kullanabileceğiniz anlamına gelir.

Windows.UI.Xaml.UIElement'dan türetilen herhangi bir WinRT XAML denetimini barındırabilirsiniz:

• Windows SDK veya WinUI 2 kitaplığı tarafından sağlanan çoğu birinci parti WinRT XAML denetimi (bkz. istisnalar).
• Herhangi bir özel WinRT XAML denetimi (örneğin, birlikte çalışan birkaç WinRT XAML denetiminden oluşan bir kullanıcı denetimi). Özel denetimi uygulamanızla derleyebileceğiniz kaynak koduna sahip olmanız gerekir.

Temel olarak, XAML Adaları WinRT XAML barındırma API'sini kullanarak oluşturulur. Bu API, Windows 10, sürüm 1903 SDK'sında tanıtılan çeşitli Windows Çalışma Zamanı sınıflarından ve COM arabirimlerinden oluşur. Ayrıca Windows Topluluk Araç Seti'nde WinRT XAML barındırma API'sini dahili olarak kullanan ve WPF ve Windows Forms uygulamaları için daha kullanışlı bir geliştirme deneyimi sağlayan bir dizi XAML Adası .NET denetimi de sağlıyoruz.

XAML Adaları'nı kullanma şekliniz, uygulama türünüz ve barındırmak istediğiniz WinRT XAML denetim türlerine bağlıdır.

Uyarı

XAML Adaları hakkında geri bildiriminiz varsa Microsoft.Toolkit.Win32 deposunda yeni bir sorun oluşturun ve yorumlarınızı orada bırakın.

Gereksinimler

XAML Adaları şu çalışma süresi gereksinimlerine sahiptir:

• Windows 10, sürüm 1903 veya sonraki bir sürüm.
• Uygulamanız dağıtım için bir MSIX paketinde paketlenmemişse, bilgisayarda Visual C++ Çalışma Zamanı yüklü olmalıdır.

WPF ve Windows Forms uygulamaları

Uyarı

WPF ve Windows Forms uygulamalarında WinRT XAML denetimlerini barındırmak için XAML Adaları'nın kullanılması şu anda yalnızca .NET Core 3.x'i hedefleyen uygulamalarda desteklenmektedir. XAML Adaları henüz .NET'i hedefleyen uygulamalarda veya .NET Framework'ün herhangi bir sürümündeki uygulamalarda desteklenmez.

WPF ve Windows Forms uygulamalarının Windows Topluluk Araç Seti'nde bulunan XAML Adası .NET denetimlerini kullanmasını öneririz. Bu denetimler, ilgili WinRT XAML denetimlerinin özelliklerini, yöntemlerini ve olaylarını taklit eden (veya erişim sağlayan) bir nesne modeli sağlar. Ayrıca klavye gezintisi ve yerleşim değişiklikleri gibi davranışları da işler.

WPF ve Windows Forms uygulamaları için iki XAML Adası denetimi kümesi vardır: sarmalanmış denetimler ve konak denetimleri.

Sarmalanmış denetimler

WPF ve Windows Forms uygulamaları, belirli bir WinRT XAML denetiminin arabirimini ve işlevselliğini sarmalayan bir dizi XAML Adası denetimi kullanabilir. Bu denetimleri doğrudan WPF veya Windows Forms projenizin tasarım yüzeyine ekleyebilir ve ardından bunları tasarımcıdaki diğer WPF veya Windows Forms denetimleri gibi kullanabilirsiniz.

Aşağıdaki sarmalanmış WinRT XAML denetimleri şu anda Windows Topluluk Araç Seti'nde kullanılabilir.

Yönetim	Desteklenen en düşük işletim sistemi	Açıklama
InkCanvas Mürekkep Araç Çubuğu	Windows 10, sürüm 1903	Windows Forms veya WPF masaüstü uygulamanızda Windows Ink tabanlı kullanıcı etkileşimi için bir yüzey ve ilgili araç çubukları sağlayın.
MediaPlayerElement	Windows 10, sürüm 1903	Windows Forms veya WPF masaüstü uygulamanızda video gibi medya içeriğini akışla aktaran ve işleyen bir görünüm ekler.
MapControl	Windows 10, sürüm 1903	Windows Forms veya WPF masaüstü uygulamanızda sembolik veya fotorealistik bir harita görüntülemenizi sağlar.

Sarmalanmış WinRT XAML denetimlerinin nasıl kullanılacağını gösteren bir izlenecek yol için bkz. C# WPF uygulamasında UWP XAML denetimini barındırmak için XAML Adaları kullanma.

Sunucu denetimleri

Özel denetimler ve kullanılabilir sarmalanmış denetimlerin kapsamı dışında kalan diğer senaryolar için WPF ve Windows Forms uygulamaları, Windows Topluluk Araç Seti'nde bulunan WindowsXamlHost denetimini de kullanabilir.

Yönetim	Desteklenen en düşük işletim sistemi	Açıklama
WindowsXamlHost	Windows 10, sürüm 1903	Windows SDK tarafından sağlanan birinci taraf WinRT XAML denetiminin yanı sıra özel denetimler de dahil olmak üzere Windows.UI.Xaml.UIElementtüretilen herhangi bir WinRT XAML denetimini barındırabilir.

WindowsXamlHost denetiminin nasıl kullanılacağını gösteren uygulamalı rehberler için, Bir C# WPF uygulamasında UWP XAML kontrolünü barındırmak için XAML Adaları'nı kullanın ve XAML Adalarıkullanarak bir WPF uygulamasında özel bir WinRT XAML kontrolü barındırma başlıklı konulara bakın.

Projenizi XAML Adası .NET denetimlerini kullanacak şekilde yapılandırma

XAML Adası .NET denetimleri Için Windows 10, sürüm 1903 veya sonraki bir sürüm gerekir. Bu denetimleri kullanmak için aşağıda listelenen NuGet paketlerinden birini yükleyin. Bu paketler, XAML Adası sarılmış denetimleri ve barındırma denetimlerini kullanmak için ihtiyacınız olan her şeyi sağlar ve ayrıca gerekli diğer ilgili NuGet paketlerini de içerir.

Denetim türü	NuGet paketi	İlgili makaleler
sarmalanmış denetimler	Bu paketlerin sürüm 6.0.0 veya üzeri: WPF: Microsoft.Toolkit.Wpf.UI.Controls Windows Forms: Microsoft.Toolkit.Forms.UI.Controls	XAML Adaları kullanarak C# WPF uygulamasında bir UWP XAML denetimi barındırma
Ana bilgisayar denetimi	Bu paketlerin sürüm 6.0.0 veya üzeri: WPF: Microsoft.Toolkit.Wpf.UI.XamlHost Windows Forms: Microsoft.Toolkit.Forms.UI.XamlHost	XAML Adaları kullanarak C# WPF uygulamasında bir UWP XAML denetimi barındırma WPF uygulamasında özel bir WinRT XAML denetimi barındırma

Aşağıdaki ayrıntılara dikkat edin:

• Ana bilgisayar denetim paketleri, sarılmış denetim paketlerine de dahildir. Her iki denetim kümesini de kullanmak istiyorsanız sarmalanmış denetim paketlerini yükleyebilirsiniz.

• Özel bir WinRT XAML denetimi barındırlıyorsanız, özel denetime başvurmak için bazı ek adımlar da gerçekleştirmeniz gerekir. Daha fazla bilgi için bkz. XAML Adalarıkullanarak WPF uygulamasında özel bir WinRT XAML denetimi barındırma.

Web görünümü denetimleri

Windows Topluluk Araç Seti, WPF ve Windows Forms uygulamalarında web içeriğini barındırmak için aşağıdaki .NET denetimlerini de sağlar. Bu denetimler genellikle XAML Adası denetimleriyle benzer masaüstü uygulaması modernleştirme senaryolarında kullanılır ve XAML Adası denetimleriyle aynı Microsoft.Toolkit.Win32 deposunda tutulur.

Yönetim	Desteklenen en düşük işletim sistemi	Açıklama
WebView	Windows 10, sürüm 1803	Web içeriğini göstermek için Microsoft Edge işleme altyapısını kullanır.
WebViewCompatible	Windows 7	Daha fazla işletim sistemi sürümüyle uyumlu bir WebView sürümü sağlar. Bu denetim, Windows 10 sürüm 1803 ve sonraki sürümlerde web içeriğini göstermek için Microsoft Edge işleme altyapısını ve Windows 10, Windows 8.x ve Windows 7'nin önceki sürümlerinde web içeriğini göstermek için Internet Explorer işleme altyapısını kullanır.

Bu denetimleri kullanmak için şu NuGet paketlerinden birini yükleyin:

• WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
• Windows Forms: Microsoft.Toolkit.Forms.UI.Controls.WebView

C++ masaüstü (Win32) uygulamaları

XAML Adası .NET denetimleri C++ masaüstü uygulamalarında desteklenmez. Bu uygulamaların bunun yerine Windows 10 SDK (sürüm 1903 ve üzeri) tarafından sağlanan WinRT XAML barındırma API'sini kullanması gerekir.

WinRT XAML barındırma API'si, C++ masaüstü uygulamanızın Windows.UI.Xaml.UIElement'ten türetilen herhangi bir WinRT XAML denetimini barındırmak için kullanabileceği çeşitli Windows Çalışma Zamanı sınıflarından ve COM arabirimlerinden oluşur. WinRT XAML denetimlerini, uygulamanızda ilişkili bir pencere tutamacı (HWND) olan herhangi bir ui öğesinde barındırabilirsiniz. Bu API hakkında daha fazla bilgi için aşağıdaki makalelere bakın.

• C++ masaüstü uygulamasında WinRT XAML barındırma API'sini kullanma
• C++ masaüstü uygulamasında standart bir WinRT XAML denetimi barındırma
• C++ masaüstü uygulamasında özel bir WinRT XAML denetimi barındırma

Uyarı

Windows Topluluk Araç Seti'ndeki sarmalanmış denetimler ve konak denetimleri, WinRT XAML barındırma API'sini dahili olarak kullanır ve klavye gezintisi ve düzen değişiklikleri de dahil olmak üzere Doğrudan WinRT XAML barındırma API'sini kullandıysanız işlemeniz gereken tüm davranışları uygular. WPF ve Windows Forms uygulamaları için, API'yi kullanmanın uygulama ayrıntılarının çoğunu soyutladıklarından, doğrudan WinRT XAML barındırma API'sinin yerine bu denetimleri kullanmanızı kesinlikle öneririz.

XAML Adaları mimarisi

WinRT XAML barındırma API'sinin üzerinde farklı XAML Adası denetim türlerinin mimari olarak nasıl düzenleniyor olduğunu aşağıda bulabilirsiniz.

Bu diyagramın en altında görünen API'ler Windows SDK'sı ile birlikte gönderilir. Sarılmış denetimler ve barındırıcı denetimler, Windows Topluluk Araç Seti'ndeki NuGet paketleri aracılığıyla kullanılabilir.

Sınırlamalar ve geçici çözümler

Aşağıdaki bölümlerde, XAML Adaları kullanan masaüstü uygulamalarında bazı UWP geliştirme senaryolarına yönelik sınırlamalar ve geçici çözümler ele alınmaktadır.

Yalnızca geçici çözümlerle desteklenir

✔️ XAML Adası'nda WinUI 2 Kitaplığı kontrollerini barındırma, XAML Adaları'nın geçerli sürümünde koşullu olarak desteklenir. Masaüstü uygulamanız dağıtım için bir MSIX paketi kullanıyorsa , Microsoft.UI.Xaml NuGet paketinin yayın öncesi veya yayın sürümlerinden WinUI denetimlerini barındırabilirsiniz. Masaüstü uygulamanız MSIX kullanılarak paketlenmediyse, WinUI denetimlerini yalnızca Microsoft.UI.Xaml NuGet paketinin yayın öncesi sürümünü yüklediğinizde veya Dinamik Bağımlılıklar API'sini kullanıyorsanız barındırabilirsiniz. WinUI 3.0 Kitaplığı'ndan barındırma denetimleri desteği sonraki bir sürümde sunulacaktır.

✔️ XAML Adasındaki bir XAML içeriği ağacının kök öğesine erişmek ve barındırıldığı bağlam hakkında ilgili bilgileri almak için CoreWindow, ApplicationView ve Window sınıflarını kullanmayın. Bunun yerine XamlRoot sınıfını kullanın. Daha fazla bilgi için bu bölüme bakın.

✔️ Wpf, Windows Forms veya C++ masaüstü (Win32) uygulamasından Paylaşım sözleşmesini desteklemek için uygulamanızın belirli bir pencere için paylaşım işlemini başlatmak üzere DataTransferManager nesnesini almak için IDataTransferManagerInterop arabirimini kullanması gerekir. Bir WPF uygulamasında bu arabirimin nasıl kullanılacağını gösteren bir örnek için bkz. ShareSource örneği.

✔️ XAML Adaları'nda barındırılan denetimlerle birlikte x:Bind kullanılması desteklenmez. Veri modelini bir .NET Standard kitaplığında bildirmeniz gerekir.

Desteklenmiyor

🚫 .NET Framework'leri hedefleyen WPF ve Windows Forms uygulamalarında XAML Adaları'nı kullanma. XAML Adaları yalnızca .NET Core 3.x'i hedefleyen uygulamalarda desteklenir.

🚫 XAML Adaları'ndaki UWP XAML içeriği, Windows tema değişikliklerine karanlıktan açığa, veya tam tersi çalışma zamanında yanıt vermez. İçerik, çalışma zamanındaki yüksek karşıtlık değişikliklerine yanıt verir.

🚫 Windows.UI.Xaml.WebView denetimi ekleme. WPF ve WinForms uygulamaları için bu alternatifleri bakın.

🚫 MediaPlayer denetimi ve MediaPlayerElement konak denetimi tam ekran modunda desteklenmez.

🚫 el yazısı görünümüyle metin girişi. Bu özellik hakkında daha fazla bilgi için bu makaleye bakın.

🚫 ve @Places ile @People içerik bağlantılarını kullanan Metin denetimleri. Bu özellik hakkında daha fazla bilgi için bu makaleye bakın.

🚫XAML Adaları TextBox, RichEditBox veya AutoSuggestBox gibi metin girişini kabul eden bir denetim içeren bir ContentDialog barındırmayı desteklemez. Bunu yaparsanız, giriş denetimi tuş basmalarına düzgün yanıt vermez. XAML Adası kullanarak benzer işlevler elde etmek için, giriş kontrolünü içeren bir Popup penceresi barındırmanızı öneririz.

🚫 XAML Adaları şu anda barındırılan bir Windows.UI.Xaml.Controls.Image denetiminde veya bir Windows.UI.Xaml.Media.Imaging.SvgImageSource nesnesi kullanılarak SVG dosyalarının görüntülenmesini desteklemez. Geçici bir çözüm olarak, görüntülemek istediğiniz görüntü dosyalarını JPG veya PNG gibi raster tabanlı biçimlere dönüştürün.

XAML Adaları için pencere bağlamı

Bir masaüstü uygulamasında XAML Adaları barındırdığınızda, aynı iş parçacığında aynı anda çalışan birden çok XAML içerik ağaçlarına sahip olabilirsiniz. XAML Adasındaki bir XAML içeriği ağacının kök öğesine erişmek ve barındırıldığı bağlam hakkında ilgili bilgileri almak için XamlRoot sınıfını kullanın. CoreWindow, ApplicationView ve Window sınıfları XAML Adaları için doğru bilgileri sağlamaz. CoreWindow ve Window nesneleri iş parçacığında bulunur ve uygulamanız tarafından erişilebilir, ancak anlamlı sınırlar veya görünürlük döndürmezler (her zaman görünmezler ve 1x1 boyutundadırlar). Daha fazla bilgi için bkz. Pencereleme sunucuları.

Örneğin, bir XAML Adasında barındırılan bir WinRT XAML denetimi içeren pencerenin sınırlayıcı dikdörtgenini almak için denetimin XamlRoot.Size özelliğini kullanın. Bir XAML Adasında barındırılabilen her WinRT XAML denetimi Windows.UI.Xaml.UIElement'ten türetildiğinden, XamlRoot nesnesine erişmek için denetimin XamlRoot özelliğini kullanabilirsiniz.

Size windowSize = myUWPControl.XamlRoot.Size;

Sınırlayıcı dikdörtgeni almak için CoreWindows.Bounds özelliğini kullanmayın.

// This will return incorrect information for a WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

XAML Adaları bağlamında ve önerilen XamlRoot değiştirmeleri bağlamında kaçınmanız gereken pencerelemeyle ilgili yaygın API'lerden oluşan bir tablo için bu bölümündeki tabloya bakın.

Bir WPF uygulamasında bu arabirimin nasıl kullanılacağını gösteren bir örnek için bkz. ShareSource örneği.

Ek kaynaklar

XAML Adaları'nı kullanma hakkında daha fazla arka plan bilgisi ve öğretici için aşağıdaki makalelere ve kaynaklara bakın:

• WPF uygulamasını modernleştirme öğreticisi: Bu öğretici, mevcut bir WPF iş kolu uygulamasına WinRT XAML denetimleri eklemek için Windows Topluluk Araç Seti'deki sarmalanmış denetimleri ve barındırma denetimlerini kullanmaya yönelik adım adım yönergeler sağlar. Bu öğretici, WPF uygulaması için tam kodun yanı sıra işlemdeki her adım için ayrıntılı yönergeleri içerir.
• XAML Adaları kod örnekleri: Bu depo, XAML Adaları'nın nasıl kullanılacağını gösteren Windows Forms, WPF ve C++ masaüstü (Win32) örneklerini içerir.
• XAML Adaları v1 - Güncelleştirmeler ve Yol Haritası: Bu blog gönderisinde XAML Adaları hakkında birçok yaygın soru ele alınmaktadır ve ayrıntılı bir geliştirme yol haritası sağlanmaktadır.