Ospitare controlli XAML WinRT nelle app desktop (isole XAML)

  • Articolo

Importante

Questo argomento usa o menziona tipi del repository GitHub CommunityToolkit/Microsoft.Toolkit.Win32. Per informazioni importanti sul supporto per le isole XAML, vedere l'avviso sulle isole XAML nel repository citato.

A partire da Windows 10, versione 1903, è possibile ospitare controlli XAML WinRT in applicazioni desktop non UWP usando la funzionalità Isole XAML. Questa funzionalità consente di ottimizzare l'aspetto e le funzionalità delle applicazioni WPF, Windows Form e desktop C++ (Win32) esistenti con le più recenti funzionalità dell'interfaccia utente di Windows 10 disponibili solo tramite i controlli XAML WinRT. In altre parole, è possibile usare le funzionalità UWP come Windows Ink e i controlli che supportano Fluent Design System nelle applicazioni WPF, Windows Form e desktop C++ esistenti.

È possibile ospitare qualsiasi controllo XAML WinRT derivante da Windows.UI.Xaml.UIElement, tra cui:

  • La maggior parte dei controlli XAML WinRT del produttore forniti da Windows SDK o dalla libreria WinUI 2.x (vedere le eccezioni).
  • Qualsiasi controllo XAML WinRT personalizzato, ad esempio un controllo utente costituito da diversi controlli XAML WinRT che interagiscono tra loro. Devi avere a disposizione il codice sorgente del controllo personalizzato per poterlo compilare con la tua applicazione.

Fondamentalmente, le isole XAML vengono create usando l'API di hosting XAML WinRT. Questa API è costituita da diverse classi di Windows Runtime e interfacce COM introdotte nell'SDK di Windows 10, versione 1903. In Windows Community Toolkit forniamo anche un set di controlli .NET delle isole XAML che usano l'API di hosting XAML WinRT internamente offrendo un'esperienza di sviluppo più vantaggiosa per le app Windows Form e WPF.

Il modo di usare le isole XAML dipende dal tipo di applicazione e dai tipi di controlli XAML WinRT che si vogliono ospitare.

Nota

Se hai raccolto feedback sulle isole XAML, crea un nuovo problema nel repository Microsoft.Toolkit.Win32 e inserisci i tuoi commenti.

Requisiti

I requisiti di esecuzione per le isole XAML sono i seguenti:

  • Windows 10, versione 1903 o una versione successiva.
  • Se la tu applicazione non è compressa in un pacchetto MSIXper la distribuzione, sul computer deve essere installato il runtime di Visual C++.

Applicazioni Windows Form e WPF

Nota

L'uso delle isole XAML per ospitare controlli XAML WinRT è supportato solo nelle app WPF e Windows Forms con destinazione .NET Core 3x. Le isole XAML non sono ancora supportate nelle app destinate a .NET o in quelle destinate a qualsiasi versione di .NET Framework.

Per le applicazioni Windows Form e WPF consigliamo di usare i controlli .NET dell'isola XAML disponibili in Windows Community Toolkit. Questi controlli forniscono un modello a oggetti che simula (o consente di usare) le proprietà, i metodi e gli eventi dei corrispondenti controlli XAML WinRT. Gestiscono anche il comportamento, ad esempio lo spostamento tramite tastiera e le modifiche del layout.

Esistono due set di controlli dell'isola XAML per le applicazioni Windows Form e WPF: controlli incapsulati e controlli host.

Controlli incapsulati

Le applicazioni Windows Form e WPF possono usare una serie di controlli dell'isola XAML che incapsulano l'interfaccia e le funzionalità di uno specifico controllo XAML WinRT. Puoi aggiungere questi controlli direttamente nell'area di progettazione del tuo progetto WPF o Windows Form e quindi usarli nella finestra di progettazione come qualsiasi altro controllo Windows Form o WPF.

In Windows Community Toolkit sono attualmente disponibili i controlli XAML WinRT incapsulati seguenti.

CTRL Sistema operativo minimo supportato Descrizione
InkCanvas
InkToolbar		 Windows 10, versione 1903 Forniscono una superficie e le relative barre degli strumenti per l'interazione utente basata su Windows Ink nella tua applicazione desktop Windows Form o WPF.
MediaPlayerElement Windows 10, versione 1903 Incorpora una visualizzazione che esegue lo streaming e il rendering di contenuto multimediale, ad esempio video, nella tua applicazione desktop Windows Form o WPF.
MapControl Windows 10, versione 1903 Ti consente di visualizzare un mappa simbolica o fotorealistica nell'applicazione desktop Windows Form o WPF.

Per una procedura dettagliata che illustra come usare i controlli XAML WinRT incapsulati, vedere Usare le isole XAML per ospitare un controllo XAML UWP in un'app WPF C#.

Controlli host

Per i controlli personalizzati e ulteriori scenari rispetto a quelli trattati dai controlli incapsulati disponibili, le applicazioni WPF e Windows Form possono usare anche il controllo WindowsXamlHost, disponibile in Windows Community Toolkit.

CTRL Sistema operativo minimo supportato Descrizione
WindowsXamlHost Windows 10, versione 1903 Può ospitare qualsiasi controllo XAML WinRT derivante da Windows.UI.Xaml.UIElement, inclusi tutti i controlli XAML WinRT del produttore forniti in Windows SDK e i controlli personalizzati.

Per le procedure dettagliate che illustrano come usare il controllo WindowsXamlHost, vedere Usare le isole XAML per ospitare un controllo XAML UWP in un'app WPF C# e Ospitare un controllo XAML WinRT personalizzato in un'app WPF usando le isole XAML.

Configurare il progetto per l'uso dei controlli .NET dell'isola XAML

Per i controlli .NET dell'isola XAML è necessario Windows 10, versione 1903, o una versione successiva. Per usare questi controlli, installa uno dei pacchetti NuGet elencati di seguito. Questi pacchetti forniscono tutti gli elementi necessari per usare i controlli incapsulati e i controlli host dell'isola XAML e includono altri pacchetti NuGet correlati ugualmente necessari.

Tipo di controllo Pacchetto NuGet Articoli correlati
Controlli incapsulati Versione 6.0.0 o successiva di questi pacchetti: Usare le isole XAML per ospitare un controllo XAML UWP in un'app WPF C#
Controllo host Versione 6.0.0 o successiva di questi pacchetti: Usare le isole XAML per ospitare un controllo XAML UWP in un'app WPF C#
Ospitare un controllo XAML WinRT personalizzato in un'app WPF

Tenere presenti i dettagli seguenti:

  • I pacchetti di controllo host sono inclusi anche nei pacchetti di controllo incapsulati. Se vuoi usare entrambi i set di controlli, puoi installare i pacchetti di controllo incapsulati.

  • Se si ospita un controllo XAML WinRT personalizzato, per fare riferimento al controllo personalizzato, è necessario anche eseguire alcuni passaggi aggiuntivi. Per altre informazioni, vedere Ospitare un controllo XAML WinRT personalizzato in un'app WPF usando le isole XAML.

Controlli della visualizzazione Web

Windows Community Toolkit fornisce anche i controlli .NET seguenti per l'hosting di contenuto Web nelle applicazioni WPF e Windows Form. Questi controlli sono spesso utilizzati in scenari di modernizzazione delle app desktop simili a quelli dei controlli di isola XAML e sono mantenuti nello stesso repo Microsoft.Toolkit.Win32 dei controlli di isola XAML.

CTRL Sistema operativo minimo supportato Descrizione
WebView Windows 10 versione 1803 Usa il motore di rendering Microsoft Edge per visualizzare il contenuto Web.
WebViewCompatible Windows 7 Fornisce una versione di WebView compatibile con altre versioni del sistema operativo. Questo controllo usa il motore di rendering Microsoft Edge per visualizzare il contenuto Web in Windows 10 versione 1803 e versioni successive e il motore di rendering di Internet Explorer per visualizzare il contenuto Web in versioni precedenti di Windows 10, Windows 8.x e Windows 7.

Per usare questi controlli, installa uno di questi pacchetti NuGet:

Applicazioni desktop C++ (Win32)

I controlli .NET delle isole XAML non sono supportati nelle applicazioni desktop C++. Queste applicazioni devono invece usare l'API di hosting XAML WinRT fornita nell'SDK di Windows 10 (versione 1903 e successive).

L'API di hosting XAML WinRT è costituita da diverse classi di Windows Runtime e interfacce COM che possono essere usate dall'applicazione desktop C++ per ospitare qualsiasi controllo XAML WinRT derivante da Windows.UI.Xaml.UIElement. È possibile ospitare i controlli XAML WinRT in qualsiasi elemento dell'interfaccia utente dell'applicazione a cui è associato un handle di finestra (HWND). Per altre informazioni su questa API, vedi i seguenti articoli:

Nota

I controlli incapsulati e i controlli host presenti in Windows Community Toolkit usano l'API di hosting XAML WinRT internamente e implementano tutto il comportamento, inclusi lo spostamento tramite tastiera e le modifiche del layout, che altrimenti sarebbe necessario gestire se si usasse l'API direttamente. Per le applicazioni WPF e Windows Form è fortemente consigliabile usare questi controlli anziché direttamente l'API di hosting XAML he altrimenti sarebbe necessario gestire se si usasse l'API direttamente, perché eliminano molti dei dettagli di implementazione previsti dall'uso dell'API.

Architettura delle isole XAML

Ecco una breve sintesi di come sono organizzati, dal punto di vista dell'architettura, i diversi tipi di controlli dell'isola XAML sull'API di hosting XAML WinRT.

Host control Architecture

Le API visualizzate nella parte inferiore del diagramma vengono fornite con Windows SDK. I controlli incapsulati e i controlli host sono disponibili attraverso i pacchetti NuGet in Windows Community Toolkit.

Limitazioni e soluzioni alternative

Le sezioni seguenti illustrano le limitazioni e le soluzioni alternative per determinati scenari di sviluppo di UWP nelle app desktop che usano le isole XAML.

Funzionalità supportate solo con soluzioni alternative

✔️ L'hosting di controlli della libreria WinUI 2 in un'isola XAML è supportato con condizioni nella versione corrente delle isole XAML. Se l'app desktop usa un pacchetto MSIX per la distribuzione, è possibile ospitare i controlli WinUI dalle versioni provvisorie o definitive del pacchetto NuGet Microsoft.UI.XAML. Se l'app desktop non è assemblata in un pacchetto con MSIX, è possibile ospitare i controlli WinUI solo installando una versione preliminare del pacchetto NuGet Microsoft.UI.Xaml oppure l'API delle dipendenze dinamiche. Il supporto per l'hosting dei controlli della libreria WinUI 3.0 sarà disponibile in una versione successiva.

✔️ Per accedere all'elemento radice di un albero di contenuto XAML in un'isola XAML e ottenere informazioni correlate sul contesto in cui è ospitato, non usare le classi CoreWindow, ApplicationView e Window. Usare invece la classe XamlRoot. Per altre informazioni, vedere questa sezione.

✔️ Per supportare il contratto Condivisione da un'app WPF, Windows Forms o desktop C++ (Win32), l'app deve usare l'interfaccia IDataTransferManagerInterop per ottenere l'oggetto DataTransferManager per avviare l'operazione di condivisione per una finestra specifica. Per un esempio in cui viene illustrato come usare questa interfaccia in un'app WPF, vedi l'esempio lShareSource.

✔️ L'uso di x:Bind con controlli ospitati in isole XAML non è supportato. Dovrai dichiarare il modello di dati in una libreria .NET Standard.

Non supportato

 L'uso delle isole XAML nelle app WPF e Windows Forms destinate a .NET Framework. Le isole XAML sono supportate solo nelle app destinate a .NET Core 3.x.

 Il contenuto XAML UWP nelle isole XAML non risponde alle modifiche del tema di Windows da scuro a chiaro o viceversa in fase di esecuzione. Il contenuto risponde a modifiche a contrasto elevato in fase di esecuzione.

 Aggiunta di un controllo Windows.UI.Xaml.WebView. Per le app WPF e WinForms, vedere queste alternative.

 Il controllo MediaPlayer e il controllo host MediaPlayerelement non sono supportati in modalità schermo intero.

 Input di testo con la visualizzazione scrittura manuale. Per altre informazioni su questa funzionalità, vedi questo articolo.

 Controlli di testo che usano i collegamenti al contenuto @Places e @People. Per altre informazioni su questa funzionalità, vedi questo articolo.

 Le isole XAML non supportano l'hosting di un oggetto ContentDialog contenente un controllo che accetta input di testo, ad esempio TextBox, RichEditBox o AutoSuggestBox. In tal caso, il controllo di input non risponderà correttamente alle pressioni dei tasti. Per ottenere una funzionalità simile usando un'isola XAML, è consigliabile ospitare un oggetto Popup contenente il controllo di input.

 Le isole XAML attualmente non supportano la visualizzazione di file SVG in un controllo ospitato Windows.UI.Xaml.Controls.Image o tramite un oggetto Windows.UI.XAML.Media.Imaging.SvgImageSource. Come soluzione alternativa, converti i file di immagine che vuoi visualizzare in formati basati su raster, ad esempio JPG o PNG.

Contesto host Windows per le isole XAML

Quando ospiti le isole XAML in un'app desktop, possono essere in esecuzione più alberi di contenuto XAML nello stesso thread contemporaneamente. Per accedere all'elemento radice di un albero di contenuto XAML in un'isola XAML e ottenere informazioni correlate sul contesto in cui è ospitato, usa la classe XamlRoot. Le classi CoreWindow, ApplicationView e Window non forniscono le informazioni corrette per le isole XAML. Gli oggetti CoreWindow e Window esistono nel thread e sono accessibili all'app, ma non restituiscono visibilità o limiti significativi (sono sempre invisibili e hanno una dimensione di 1x1). Per altre informazioni, vedi Host di windowing.

Per ottenere, ad esempio, il rettangolo delimitatore della finestra contenente un controllo XAML WinRT ospitato in un'isola XAML, usare la proprietà XamlRoot.Size del controllo. Poiché ogni controllo XAML WinRT che può essere ospitato in un'isola XAML deriva da Windows.UI.Xaml.UIElement, è possibile usare la proprietà XamlRoot del controllo per accedere all'oggetto XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

Non usare la proprietà CoreWindows.Bounds per ottenere il rettangolo delimitatore.

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

Per una tabella delle API comuni correlate al windowing da evitare nel contesto delle isole XAML e delle sostituzioni XamlRoot consigliate, vedi la tabella riportata in questa sezione.

Per un esempio in cui viene illustrato come usare questa interfaccia in un'app WPF, vedi l'esempio lShareSource.

Risorse aggiuntive

Per altre informazioni generali ed esercitazioni sull'uso delle isole XAML, vedi gli articoli e le risorse seguenti:

  • Esercitazione Modernizzare un'app WPF: questa esercitazione fornisce istruzioni dettagliate per usare i controlli incapsulati e i controlli host di Windows Community Toolkit per aggiungere controlli XAML WinRT a un'applicazione line-of-business WPF esistente. Questa esercitazione include il codice completo dell'applicazione WPF, oltre a istruzioni dettagliate per ogni passaggio della procedura.
  • Esempi di codice delle isole XAML: questo repository contiene esempi di Windows Form, WPF e desktop C++ (Win32) che illustrano come usare le isole XAML.
  • Isole XAML v1 - Aggiornamenti e roadmap: questo post di blog include molte domande comuni sulle isole XAML e fornisce una roadmap dettagliata per lo sviluppo.