Eseguire la migrazione di modelli di app macchine virtuali Windows a WinUI 3

macchine virtuali Windows e WinUI 3 condividono alcuni concetti XAML, ma usano set di controlli diversi, modelli di app, API di windowing, sistemi di risorse e strumenti. Un nome o un modello familiare non garantisce un comportamento equivalente e alcune funzionalità macchine virtuali Windows non hanno una controparte WinUI 3 di prima parte.

Usare questo argomento per identificare i punti di partenza e le lacune prima di stimare o implementare una migrazione. Convalida ogni mapping in base al comportamento dell'app, ai requisiti di accessibilità, alle dipendenze e al modello di distribuzione.

Suggerimento

Per indicazioni generali macchine virtuali Windows + SDK per app di Windows, vedere Usare il SDK per app di Windows in un progetto esistente.

Controlli

Alcuni controlli comuni hanno nomi simili, ma le API, lo stile, il comportamento di accessibilità e il layout possono differire. La tabella seguente evidenzia i mapping che richiedono una decisione di progettazione o che non hanno un equivalente di prima parte.

controllo macchine virtuali Windows Equivalente a WinUI 3 Note
DataGrid Nessun equivalente di prima parte WinUI 3 non includeva un DataGrid predefinito. WinUI.TableView gestito dalla community è un'opzione. Valutare i progetti della community in base ai requisiti di supporto e manutenzione.
Ribbon CommandBar / Community Toolkit Labs Prendere in considerazione CommandBar e CommandBarFlyout per scenari in stile barra degli strumenti. Un controllo Ribbon è disponibile anche in Community Toolkit Labs (sperimentale).
StatusBar InfoBar + layout personalizzato Usa InfoBar per la messaggistica di stato o aggiungi un'area del piè di pagina dedicata al layout.
FlowDocumentReader / FlowDocumentScrollViewer RichTextBlock Usa RichTextBlock per la visualizzazione rtf di sola lettura. WinUI 3 non implementa il modello di macchine virtuali Windows FlowDocument, quindi lo spostamento dei documenti, la paginazione e la modifica richiedono un lavoro di progettazione separato.
PasswordBox con SecureString PasswordBox PasswordBox di WinUI 3 fornisce la maschera password. SecureString è deprecato in .NET 5+; l'approccio consigliato consiste nel ridurre al minimo la durata delle credenziali in memoria usando i modelli ReadOnlySpan<char>.
WebBrowser WebView2 WebView2 usa il motore di Microsoft Edge (Chromium) moderno ed è l'approccio consigliato per incorporare contenuto Web in tutti i tipi di app desktop.

Funzionalità XAML

WinUI 3 XAML include dizionari risorse, stili, data binding ed estensioni di markup, ma le funzionalità e il comportamento di runtime supportati differiscono da macchine virtuali Windows. Alcuni modelli specifici di macchine virtuali Windows richiedono comportamenti associati, convertitori, proprietà del modello di visualizzazione o controlli personalizzati.

macchine virtuali Windows funzionalità Approccio WinUI 3 Note
DataTrigger / MultiTrigger Comportamenti (Community Toolkit) WinUI 3 non supporta i dati macchine virtuali Windows e i trigger multipli. Il pacchetto Comportamenti XAML fornisce DataTriggerBehavior, EventTriggerBehavior e i relativi blocchi predefiniti, ma è necessario rielaborare la logica del trigger e verificare il comportamento.
DynamicResource ThemeResource ThemeResource fornisce la ricerca delle risorse di runtime e risponde automaticamente alle modifiche del tema (chiaro, scuro, contrasto elevato). Usare StaticResource per i valori che non cambiano mai in fase di esecuzione.
MultiBinding / PriorityBinding Funzioni in x:Bind WinUI 3 non fornisce i tipi macchine virtuali Windows MultiBinding o PriorityBinding e un convertitore di valori WinUI riceve un solo valore di origine. Per combinare i valori, usare un'associazione x:Bind di funzioni con più argomenti e Mode=OneWayoppure esporre una proprietà calcolata del modello di visualizzazione. PriorityBinding il fallback non è automatico, quindi va implementato in modo esplicito, ad esempio in tale funzione o nel modello di visualizzazione.
Style con BasedOn ✅ Sostenuto Ereditarietà dello stile con BasedOn funziona in WinUI 3.
Stili impliciti ✅ Sostenuto Gli stili impliciti del dizionario risorse (stili senza x:Key) funzionano come previsto.
AdornerLayer Approccio di sovrapposizione personalizzato WinUI 3 non ha alcun livello decorativo equivalente. Usare una sovrimpressione Canvas o Grid quando appropriato per lo scenario d'uso e tenere conto di input, messa a fuoco, ritaglio, scorrimento e accessibilità.

Threading e invio

modello macchine virtuali Windows Equivalente a WinUI 3 Note
Dispatcher.Invoke / BeginInvoke DispatcherQueue.TryEnqueue WinUI 3 usa DispatcherQueue. Il modello asincrono è await DispatcherQueue.EnqueueAsync(...) utilizzando l'estensione Community Toolkit.
Application.Current.Dispatcher DispatcherQueue.GetForCurrentThread() Acquisire l'oggetto DispatcherQueue in fase di costruzione nel thread dell'interfaccia utente e archiviarlo per usarlo in un secondo momento nei thread in background.
BackgroundWorker Task / async-await Usare Task, CancellationToken e IProgress<T> in base al carico di lavoro. Esaminare l'annullamento, la gestione delle eccezioni, la creazione di report sullo stato e l'accesso al thread dell'interfaccia utente anziché applicare una sostituzione meccanica.

Modello di app e ciclo di vita

macchine virtuali Windows concetto Equivalente a WinUI 3 Note
Application.Startup / Exit Eventi App.OnLaunched / Window.Closed WinUI 3 usa OnLaunched in App.xaml.cs come punto di ingresso. L'disinstallazione per finestra viene gestita in Window.Closed.
Application.Current.MainWindow La tua Window istanza Mantieni un riferimento all'istanza della finestra in App.xaml.cs ed esponilo come proprietà.
Window Sottoclassi Personalizzazione di AppWindow Le finestre WinUI 3 vengono personalizzate tramite AppWindow (barra del titolo, presentatore, modalità sovrapposte/schermo intero/sovrimpressione compatta) anziché tramite subclassing. Vedi Gestire le finestre delle app.
SystemParameters DisplayArea / UISettings Le proprietà di visualizzazione del sistema sono disponibili tramite DisplayArea e UISettings.

Risorse e localizzazione

modello macchine virtuali Windows Equivalente a WinUI 3 Note
.resx file di risorse .resw + ResourceLoader WinUI 3 utilizza i file .resw e l'API ResourceLoader. Eseguire la migrazione delle stringhe di risorse e aggiornare il codice di ricerca delle risorse come parte della migrazione dell'interfaccia utente.
x:Static estensione di markup x:Bind a una proprietà statica Utilizzare x:Bind con una proprietà statica o un accessor singleton. Verificare l'ordine di inizializzazione e la notifica di modifica quando il valore può cambiare.
Dizionari di risorse combinati ✅ Sostenuto ResourceDictionary.MergedDictionaries funziona in WinUI 3.
Dizionari di risorse specifici dell'argomento ✅ Sostenuto ResourceDictionary.ThemeDictionaries è il meccanismo WinUI 3 per le risorse per tema e si integra con il cambio automatico in modalità scura/chiara.

Stampa

macchine virtuali Windows funzionalità Stato WinUI 3 Note
PrintDialog / PrintDocument PrintManager La stampa usa un'API e un flusso di lavoro diversi. Un'app desktop deve ottenere PrintManager per la finestra tramite l'API di interoperabilità desktop. Vedi Stampare dall'app.

Strumenti per sviluppatori

strumenti macchine virtuali Windows Stato WinUI 3 Note
Finestra di progettazione XAML (scheda Progettazione) Non ancora supportato La finestra di progettazione XAML Visual Studio attualmente non supporta i progetti WinUI 3. XAML Ricaricamento rapido è supportato ed è il modo consigliato per scorrere il layout e gli stili senza arrestare il debugger.
Blend per Visual Studio ⚠️ Supporto limitato Blend viene fornito con Visual Studio e può aprire progetti WinUI 3. La struttura del documento XAML è funzionale, ma la visualizzazione Progettazione non è disponibile per WinUI 3.

Valutare le lacune prima della migrazione

Esaminare le lacune che influiscono sul prodotto prima di procedere con una migrazione dell'interfaccia utente. Gli esempi includono la mancanza di un livello di progettazione WinUI 3 di prima parte in Visual Studio, di DataGrid, Ribbon, livello Adorner e modello di documento macchine virtuali Windows. I controlli di terze parti, il rendering personalizzato, i peer di automazione dell'accessibilità, la stampa, più finestre e il deployment possono anche richiedere decisioni architetturali o di prodotto anziché semplici sostituzioni di API.

Crea prototipi di schermate rappresentative e integrazioni ad alto rischio prima di stimare la migrazione completa. Se una funzionalità necessaria non ha un equivalente accettabile, mantenere tale flusso di lavoro in macchine virtuali Windows, modernizzarlo sul posto o rinviare la migrazione dell'interfaccia utente.

Usare un assistente di intelligenza artificiale come aiuto facoltativo per la revisione

Un assistente di coding basato sull’IA può esaminare una vista macchine virtuali Windows con binding definiti, identificare le dipendenze da API specifiche di macchine virtuali Windows, creare una bozza di un controllo o una mappatura dei binding e proporre modifiche per la revisione. Può anche aiutare a creare un inventario di controlli di terze parti e integrazioni con la piattaforma.

Verificare ogni suggerimento in base alla documentazione attuale di WinUI 3 e al comportamento richiesto dall'app. Compilazione e test delle modifiche generate, tra cui data binding, threading, proprietà della finestra padre, accessibilità, localizzazione, creazione di pacchetti e gestione degli errori. Un assistente non può fornire funzionalità di piattaforma mancanti, scegliere compromessi di prodotto accettabili o garantire che un controllo simile mantiene il flusso di lavoro originale.

Vedere anche

  • Ultimo aggiornamento: