Ospitare controlli XAML UWP nelle app desktop (UWP XAML Islands)

A partire da Windows 10 versione 1903, puoi ospitare controlli XAML UWP in applicazioni desktop non UWP usando una funzionalità denominata isole XAML UWP. Questa funzionalità consente di migliorare l'aspetto, l'aspetto e le funzionalità delle applicazioni esistenti macchine virtuali Windows, Windows Forms e desktop C++ (Win32) con funzionalità dell'interfaccia utente Windows disponibili solo tramite i controlli XAML UWP. Ciò significa che puoi usare funzionalità UWP come Windows Ink e controlli che supportano il sistema di progettazione Fluent Design System nelle applicazioni desktop macchine virtuali Windows, Windows Forms e C++ esistenti.

Puoi ospitare qualsiasi controllo XAML UWP che deriva da Windows. UI. Xaml.UIElement, tra cui:

• La maggior parte dei controlli XAML UWP di prima parte forniti dall'SDK di Windows o dalla libreria WinUI per UWP (vedi exceptions).
• Qualsiasi controllo XAML UWP personalizzato ,ad esempio un controllo utente costituito da diversi controlli XAML UWP che interagiscono. Devi avere a disposizione il codice sorgente del controllo personalizzato per poterlo compilare con la tua applicazione.

Fondamentalmente, le isole XAML UWP vengono create usando l'API di hosting XAML UWP. Questa API è costituita da diverse classi Windows Runtime e interfacce COM introdotte nell'SDK Windows 10 versione 1903. Forniamo anche un set di controlli .NET XAML Island nel Windows Community Toolkit che usano internamente l'API di hosting XAML UWP e offrono un'esperienza di sviluppo più conveniente per le applicazioni macchine virtuali Windows e Windows Forms.

Il modo in cui usi le isole XAML UWP dipende dal tipo di applicazione e dai tipi di controlli XAML UWP che vuoi ospitare.

Requisiti

Le isole XAML UWP hanno questi requisiti di runtime:

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

applicazioni macchine virtuali Windows e Windows Forms

È consigliabile che le applicazioni macchine virtuali Windows e Windows Forms usino i controlli .NET XAML Island disponibili nel Windows Community Toolkit. Questi controlli forniscono un modello a oggetti che simula (o fornisce l'accesso a) le proprietà, i metodi e gli eventi dei controlli XAML UWP corrispondenti. Gestiscono anche il comportamento, ad esempio lo spostamento tramite tastiera e le modifiche del layout.

Sono disponibili due set di controlli isola XAML per macchine virtuali Windows e applicazioni Windows Forms: controlli wrapped e host.

Controlli incapsulati

applicazioni macchine virtuali Windows e Windows Forms possono usare una selezione di controlli XAML Island che eseguono l'interfaccia e la funzionalità di un controllo specifico XAML UWP. È possibile aggiungere questi controlli direttamente alla superficie di progettazione del progetto macchine virtuali Windows o Windows Forms e utilizzarli come qualsiasi altro controllo macchine virtuali Windows o Windows Forms nella finestra di progettazione.

I controlli XAML UWP avvolti seguenti sono attualmente disponibili nel Windows Community Toolkit.

Per una procedura dettagliata che illustra come usare i controlli XAML UWP incapsulati, consultare Usa le isole XAML per ospitare un controllo XAML UWP in un'app macchine virtuali Windows C#.

Controlli dell'host

Per i controlli personalizzati e altri scenari oltre a quelli coperti dai controlli incapsulati disponibili, macchine virtuali Windows e Windows Forms applicazioni possono usare anche il controllo WindowsXamlHost disponibile in Windows Community Toolkit.

Per le procedure dettagliate che illustrano come usare il controllo WindowsXamlHost, vedi Usa XAML Islands per ospitare un controllo UWP XAML in un'app C# macchine virtuali Windows e Ospita un controllo UWP XAML personalizzato in un'app macchine virtuali Windows usando XAML Islands.

Configurare il progetto per usare i controlli .NET XAML Island

I controlli .NET XAML Island richiedono Windows 10, versione 1903 o 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.

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 stai ospitando un controllo XAML UWP personalizzato, dovrai anche eseguire alcuni passaggi aggiuntivi per fare riferimento al controllo personalizzato. Per ulteriori informazioni, vedere Ospitare un controllo XAML UWP personalizzato in un'app macchine virtuali Windows usando le isole XAML.

Controlli della visualizzazione Web

Windows Community Toolkit fornisce anche i controlli di .NET seguenti per l'hosting di contenuto Web nelle applicazioni macchine virtuali Windows e Windows Forms. Questi controlli vengono spesso usati in scenari di modernizzazione di app desktop simili ai controlli isola XAML e vengono mantenuti nello stesso repository Microsoft.Toolkit.Win32 come controlli dell'isola XAML.

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

• macchine virtuali Windows: Microsoft.Toolkit. Wpf. UI. Controls.WebView
• Windows Forms: Microsoft. Toolkit.Forms.UI.Controls.WebView

Applicazioni desktop C++ (Win32)

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

L'API di hosting XAML UWP è costituita da diverse classi Windows Runtime e interfacce COM che l'applicazione desktop C++ può usare per ospitare qualsiasi controllo XAML UWP che deriva da Windows. UI. Xaml.UIElement. Puoi ospitare controlli XAML UWP in qualsiasi elemento dell'interfaccia utente nell'applicazione con un handle di finestra associato (HWND). Per altre informazioni su questa API, vedi i seguenti articoli:

• Uso dell'API di hosting XAML UWP in un'app desktop C++
• Inserire un controllo XAML UWP standard in un'app desktop C++
• Hostare un controllo XAML UWP personalizzato in un'applicazione desktop in C++

Architettura delle isole XAML UWP

Ecco un rapido sguardo a come i diversi tipi di controlli XAML Island sono organizzati architettonicamente al di sopra dell'API di hosting XAML UWP.

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 UWP nelle app desktop che usano isole XAML UWP.

Supportate solo con soluzioni alternative

✔️ L'hosting di controlli dalla libreria WinUI per UWP in un'XAML Island è supportato in modo condizionale nell'attuale release delle XAML Islands UWP. 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.

✔️ 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 Share da applicazioni macchine virtuali Windows, Windows Forms o da app 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 che illustra come usare questa interfaccia in un'app macchine virtuali Windows, vedi l'esempio ShareSource.

✔️ L'uso di x:Bind con controlli ospitati nelle isole XAML UWP non è supportato. Sarà necessario dichiarare il modello di dati in una libreria standard di .NET.

Non supportato

🚫 Uso delle isole XAML UWP nelle app macchine virtuali Windows e Windows Forms che hanno come target il .NET Framework. Le isole XAML UWP sono supportate solo nelle app che mirano a .NET Core 3.x.

🚫 Il contenuto XAML UWP in XAML Islands UWP non risponde ai cambi di tema di Windows da scuro a chiaro o viceversa durante l'esecuzione. Il contenuto risponde a modifiche a contrasto elevato in fase di esecuzione.

🚫 Aggiunta di un controllo Windows.UI.Xaml.WebView. Per le app macchine virtuali Windows e WinForms, vedi alternative ese.

🚫 Il controllo MediaPlayer e MediaPlayerElement non sono supportati in modalità schermo intero.

🚫 Inserimento di testo con la vista 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.

🚫 isole XAML UWP non supportano l'hosting di un ContentDialog che contiene 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 UWP attualmente non supportano la visualizzazione di file SVG in un controllo Windows.UI.Xaml.Controls.Image ospitato 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 si ospitano isole XAML UWP in un'app desktop, è possibile avere più alberi di contenuto XAML in esecuzione nello stesso thread contemporaneamente. Per accedere all'elemento radice di un albero di contenuti XAML in una XAML Island e ottenere informazioni relative al contesto in cui è ospitata, usare la classe XamlRoot. Le classi CoreWindow, ApplicationView e Window non forniscono le informazioni corrette per le isole XAML UWP. 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 gestione delle finestre.

Ad esempio, per ottenere il rettangolo di delimitazione della finestra che contiene un controllo XAML UWP ospitato in un'isola XAML, usa la proprietà XamlRoot.Size del controllo. Poiché ogni controllo XAML UWP che può essere ospitato in un'isola XAML deriva da Windows. UI. Xaml.UIElement, puoi 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 UWP XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

Per una tabella delle API comuni correlate alle finestre che dovresti evitare nel contesto delle isole XAML UWP e delle sostituzioni XamlRoot consigliate, vedi la tabella in questa sezione.

Per un esempio che illustra come usare questa interfaccia in un'app macchine virtuali Windows, vedi l'esempio ShareSource.

Risorse aggiuntive

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

• Esempi di codice delle isole XAML UWP: questo repository contiene esempi per Windows Forms, macchine virtuali Windows e app desktop C++ (Win32) che dimostrano come usare le isole XAML UWP.
• Isole XAML UWP v1 - Aggiornamenti e roadmap: questo post di blog illustra molte domande comuni sulle isole XAML UWP e fornisce una roadmap dettagliata per lo sviluppo.