Integrare controlli WinUI con XAML Islands

Le isole XAML WinUI consentono di ospitare i controlli dal SDK per app di Windows all'interno di un'app desktop esistente. Puoi aggiungere un'esperienza WinUI a una parte di un'app macchine virtuali Windows, Windows Forms o Win32 mantenendo al suo posto il resto dell'interfaccia utente e dell'architettura dell'applicazione.

Le isole XAML supportano la modernizzazione incrementale. Funzionano bene quando una migrazione completa dell'interfaccia utente non è pratica, ma un flusso di lavoro specifico trarrà vantaggio dai controlli WinUI, dallo stile Fluent o da un'altra funzionalità dell'interfaccia utente SDK per app di Windows.

Importante

XAML Islands di WinUI usano le API Microsoft.UI.Xaml di SDK per app di Windows. Non sono uguali alle isole XAML di sistema legacy, che usano Windows.UI.Xaml per ospitare i controlli UWP. Non combinare le API o le istruzioni di configurazione delle due implementazioni.

Decidere se usare XAML Islands

Usa WinUI XAML Islands quando:

  • È necessario mantenere un macchine virtuali Windows sostanziale, Windows Forms o interfaccia utente Win32 durante la modernizzazione di un'area alla volta.
  • Una superficie nuova o riprogettata richiede controlli WinUI.
  • È possibile gestire una finestra figlia nativa, l'inizializzazione del thread dell'interfaccia utente, l'input, il focus e i requisiti di distribuzione nell'applicazione host.

Valutare la possibilità di eseguire la migrazione dell'interfaccia utente completa a WinUI quando la maggior parte delle schermate deve cambiare o quando la gestione di due framework dell'interfaccia utente aggiungerebbe maggiore complessità rispetto a quella rimossa. Per le opzioni di migrazione, vedere Scegliere il percorso di migrazione.

Informazioni sul modello di hosting

La DesktopWindowXamlSource classe è l'API di hosting XAML SDK per app di Windows primaria. Collega un albero di Microsoft.UI.Xaml contenuti a una finestra figlia nativa all'interno della tua app desktop.

Un'integrazione tipica include queste parti:

  1. Applicazione host: il processo di macchine virtuali Windows, Windows Forms o Win32 esistente è proprietario del ciclo di messaggi e della finestra di primo livello.
  2. SDK per app di Windows runtime: l'host inizializza il runtime in base al relativo modello di creazione di pacchetti e distribuzione.
  3. Ambiente XAML: l'host inizializza WinUI nel thread dell'interfaccia utente. Crea anche una coda dispatcher su tale thread, se non ne esiste già una.
  4. Origine dell'isola: DesktopWindowXamlSource possiede la finestra figlia nativa che visualizza il contenuto WinUI.
  5. Contenuto WinUI: UIElement, spesso fornito da una libreria di classi WinUI separata, diventa il contenuto dell'isola.

L'API di hosting XAML di SDK per app di Windows supporta gli host macchine virtuali Windows, Windows Forms e Win32. I dettagli per ottenere l'handle della finestra host e l'integrazione con il relativo ciclo di messaggi differiscono per framework. L'esempio SDK per app di Windows Islands gestito illustra un host .NET 8 Windows Forms non compresso.

Per un host gestito, specificare una versione .NET supportata dalla versione SDK per app di Windows selezionata. I requisiti del framework indicati nella documentazione del sistema legacy relativa a XAML Islands non descrivono WinUI XAML Islands.

Configurare l'host

Prima di creare un'isola:

  1. Aggiungere il pacchetto SDK per app di Windows e configurarne l'inizializzazione in fase di esecuzione. Per un progetto esistente, vedere Usare il SDK per app di Windows in un progetto esistente.
  2. Inserire i controlli XAML che si desidera ospitare in un progetto WinUI, ad esempio una libreria di classi WinUI, e fare riferimento a tale progetto dall'host.
  3. Configurare il thread dell'interfaccia utente host come single-threaded apartment (STA), creare una coda di dispatcher su tale thread e quindi creare un Microsoft.UI.Xaml.Application.
  4. Configurare l'applicazione per fornire metadati e risorse XAML. Per un host C#, implementa IXamlMetadataProvider, aggiungi XamlControlsXamlMetaDataProvider e il provider di metadati generato da ogni libreria di classi WinUI e incorpora XamlControlsResources nelle risorse dell'applicazione. Senza il provider generato dalla libreria, la creazione dei relativi controlli XAML può generare XamlParseException. Vedi l'implementazione XamlApp e la registrazione del provider dell'esempio.
  5. Chiamare WindowsXamlManager.InitializeForCurrentThread sullo stesso thread dell'interfaccia utente prima di creare l'isola.
  6. Mantieni tutti gli oggetti XAML nel thread in cui hai inizializzato XAML. Gli oggetti WinUI hanno affinità di thread.

L'estratto seguente illustra il nucleo di un controllo host Windows Forms personalizzato. Si presuppone che l'app abbia già inizializzato il runtime di SDK per app di Windows, la coda del dispatcher e l'ambiente XAML e che IslandView sia un elemento WinUI UserControl proveniente da una libreria di classi WinUI a cui viene fatto riferimento.

#nullable enable

using System;
using System.ComponentModel;
using System.Windows.Forms;
using Microsoft.UI;
using Microsoft.UI.Xaml.Hosting;
using Windows.Graphics;

internal sealed class WinUIIslandHost : Control
{
    private DesktopWindowXamlSource? _xamlSource;

    protected override void OnHandleCreated(EventArgs e)
    {
        base.OnHandleCreated(e);

        if (DesignMode ||
            LicenseManager.UsageMode == LicenseUsageMode.Designtime)
        {
            return;
        }

        _xamlSource = new DesktopWindowXamlSource();
        _xamlSource.Initialize(Win32Interop.GetWindowIdFromWindow(Handle));
        _xamlSource.Content = new MyWinUILibrary.IslandView();
        ResizeIsland();
    }

    protected override void OnSizeChanged(EventArgs e)
    {
        base.OnSizeChanged(e);
        ResizeIsland();
    }

    private void ResizeIsland()
    {
        _xamlSource?.SiteBridge.MoveAndResize(
            new RectInt32(0, 0, ClientSize.Width, ClientSize.Height));
    }

    protected override void OnHandleDestroyed(EventArgs e)
    {
        ReleaseIsland();
        base.OnHandleDestroyed(e);
    }

    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            ReleaseIsland();
        }

        base.Dispose(disposing);
    }

    private void ReleaseIsland()
    {
        _xamlSource?.Dispose();
        _xamlSource = null;
    }
}

Questo codice illustra la creazione del contenuto, l'elemento padre nativo, il ridimensionamento e la pulizia. Un'integrazione di produzione deve anche connettere il comportamento di input e messa a fuoco dei due framework.

Note

WinUIIslandHost in questo esempio e DesktopWindowXamlSourceControl nell'esempio ufficiale sono controlli helper definiti dall'applicazione. Non sono controlli SDK per app di Windows.

Integrare input e focus

L'host e l'isola condividono un thread, ma usano sistemi di interfaccia utente diversi. Considera il loro confine come un confine di interoperabilità:

  • Chiamare la funzione nativa ContentPreTranslateMessage per i messaggi prima che l'host li invii. Questo passaggio è necessario per un host che usa lo stack dell'interfaccia utente SDK per app di Windows. La funzione non ha una proiezione gestita. L'esempio di Windows Forms P/Richiama da Microsoft.UI.Windowing.Core.dll e registra un oggetto IMessageFilter.
  • Utilizza DesktopWindowXamlSource.NavigateFocus quando la navigazione tramite tastiera accede all'isola.
  • Gestisci DesktopWindowXamlSource.TakeFocusRequested quando la navigazione tramite tastiera deve tornare all'host.
  • Verificare l'ordine di tabulazione in entrambe le direzioni, i tasti di scelta rapida, i tasti di accesso, l'input tramite puntatore, l'immissione di testo e gli editor IME.
  • Verificare i nomi accessibili, le relazioni e l'ordine del focus tra l'host e l'isola con uno strumento di ispezione dell'accessibilità.

L'integrazione dell'input è necessaria anche quando l'interazione del puntatore sembra funzionare senza di essa. La gestione incompleta dei messaggi o del focus può impedire agli utenti che usano la tastiera di entrare o uscire dall'isola.

Gestire il layout e visualizzare le modifiche

DesktopWindowXamlSource.SiteBridge espone il sito figlio nativo utilizzato dall'isola. Ridimensionarlo ogni volta che cambia l'area client dell'host, come illustrato nell'esempio.

Testare anche:

  • Modifiche DPI per monitor e ridimensionamento della visualizzazione.
  • Ridimensionamento della finestra host, riduzione al minimo, ripristino e comportamento di replica.
  • Contrasto elevato, ridimensionamento del testo e temi chiari e scuri.
  • Interazioni di ritaglio, scorrimento e ordine z con contenuto host nativo.

Non presupporre che il motore di layout del framework host ridimensiona automaticamente il contenuto winUI. L'host rimane responsabile dei limiti nativi dell'isola.

Eseguire la pulizia nell'ordine corretto

Chiudere o eliminare ogni DesktopWindowXamlSource volta che il controllo host o la finestra vengono eliminati definitivamente. Quando il processo termina, rilasciare le isole prima di chiudere il manager XAML o arrestare la coda del dispatcher.

Mantenere i riferimenti al controller di coda del dispatcher e al gestore XAML per tutto il tempo in cui le isole le usano. L'arresto anticipato di uno dei componenti può causare errori durante la distruzione della finestra o l'elaborazione finale dei messaggi.

Creare un pacchetto e distribuire l'app

Le XAML Islands non richiedono di per sé un'identità del pacchetto, ma l'host deve distribuire correttamente il runtime di SDK per app di Windows ed eventuali altre dipendenze. In un'app senza pacchetti dipendente dal framework inizializzare il runtime prima di inizializzare XAML. Un tipico host .NET imposta <WindowsPackageType>None</WindowsPackageType> per abilitare l'inizializzazione automatica del runtime; usa il bootstrapper quando è necessario un controllo esplicito.

Per i requisiti di distribuzione e i compromessi, vedere SDK per app di Windows panoramica della distribuzione. Testare l'installazione, l'assistenza e l'inizializzazione in fase di esecuzione usando lo stesso modello di distribuzione che si prevede di distribuire.

Confronto tra le XAML Islands correnti e precedenti

Caratteristica WinUI XAML Islands Isole XAML di sistema legacy
Framework XAML SDK per app di Windows WinUI UWP XAML
Namespace Microsoft.UI.Xaml Windows.UI.Xaml
Host di basso livello primario Microsoft.UI.Xaml.Hosting.DesktopWindowXamlSource Windows.UI.Xaml.Hosting.DesktopWindowXamlSource
Contenuto da usare per il nuovo lavoro di modernizzazione Controlli attuali di SDK per app di Windows Controlli legacy di UWP

Se un'app esistente usa già le isole XAML di sistema, considera il passaggio alle isole XAML WinUI come migrazione tra tecnologie, non come sostituzione di pacchetti o spazi dei nomi. Rivaluta l'inizializzazione, le librerie di contenuto, l'integrazione di input e la distribuzione. Consulta XAML Islands (UWP) solo durante la manutenzione dell'implementazione esistente.