Migrieren von WPF App-Mustern zu WinUI 3

WPF und WinUI 3 teilen einige XAML-Konzepte, verwenden jedoch unterschiedliche Steuerelementsätze, App-Modelle, Fenster-APIs, Ressourcensysteme und Tools. Ein vertrauter Name oder ein bekanntes Muster garantiert kein gleichwertiges Verhalten, und einige WPF-Features haben kein WinUI 3-Gegenstück von Microsoft.

Verwenden Sie diesen Abschnitt, um Ausgangspunkte und Lücken zu identifizieren, bevor Sie eine Migration schätzen oder implementieren. Überprüfen Sie jede Zuordnung anhand des Verhaltens, der Barrierefreiheitsanforderungen, abhängigkeiten und des Bereitstellungsmodells Ihrer App.

Tipp

Allgemeine WPF + Windows App SDK Anleitungen finden Sie unter Use the Windows App SDK in an existing project.

Bedienelemente

Einige gängige Steuerelemente weisen ähnliche Namen auf, aber ihre APIs, Das Formatieren, das Barrierefreiheitsverhalten und das Layout können unterschiedlich sein. In der folgenden Tabelle werden Zuordnungen hervorgehoben, die eine Designentscheidung erfordern oder nicht über ein Erstanbieter-Äquivalent verfügen.

WPF-Steuerelement WinUI 3-Entsprechung Hinweise
DataGrid Kein Erstanbieter-Äquivalent WinUI 3 enthält kein integriertes DataGrid. Die von der Community verwaltete WinUI.TableView ist eine Option. Bewerten Sie Communityprojekte basierend auf Ihren Support- und Wartungsanforderungen.
Ribbon CommandBar / Community Toolkit Labs Erwägen Sie CommandBar und CommandBarFlyout für Szenarien im Symbolleistenstil. Ein Ribbon-Steuerelement ist auch in Community Toolkit Labs (experimentell) verfügbar.
StatusBar InfoBar + benutzerdefiniertes Layout Verwenden Sie die Infoleiste für Statusnachrichten, oder fügen Sie Ihrem Layout einen dedizierten Fußzeilenbereich hinzu.
FlowDocumentReader / FlowDocumentScrollViewer RichTextBlock Verwenden Sie RichTextBlock für die schreibgeschützte Rich-Text-Anzeige. WinUI 3 implementiert das WPF FlowDocument Modell nicht, sodass für die Dokumentnavigation, paginierung und Bearbeitung separate Entwurfsarbeiten erforderlich sind.
PasswordBox durch SecureString PasswordBox WinUI 3's PasswordBox bietet Kennwortmasken. SecureString ist in .NET 5+ veraltet. Der empfohlene Ansatz besteht darin, zu minimieren, wie lange Anmeldeinformationen im Arbeitsspeicher mit ReadOnlySpan<char>Mustern gespeichert werden.
WebBrowser WebView2 WebView2 verwendet die moderne Microsoft Edge (Chromium) Engine und ist der empfohlene Ansatz zum Einbetten von Webinhalten für alle Desktop-App-Typen.

XAML-Features

WinUI 3 XAML enthält Ressourcenwörterbücher, Stile, Datenbindung und Markuperweiterungen, die unterstützten Features und das Laufzeitverhalten unterscheiden sich jedoch von WPF. Einige WPF-spezifische Muster erfordern angefügte Verhaltensweisen, Konverter, Ansichtsmodelleigenschaften oder benutzerdefinierte Steuerelemente.

WPF-Funktion WinUI 3-Ansatz Hinweise
DataTrigger / MultiTrigger Behaviors (Community Toolkit) WinUI 3 unterstützt keine WPF Daten und Multitrigger. Das XAML Behaviors-Paket enthält DataTriggerBehavior, EventTriggerBehavior und verwandte Bausteine, aber Sie müssen die Triggerlogik überarbeiten und das Verhalten überprüfen.
DynamicResource ThemeResource ThemeResource stellt die Laufzeitressourcensuche bereit und reagiert automatisch auf Designänderungen (hell, dunkel, hoher Kontrast). Verwenden Sie StaticResource, um Werte zu definieren, die sich zur Laufzeit nie ändern.
MultiBinding / PriorityBinding Funktionen in x:Bind WinUI 3 stellt die WPF PriorityBinding oder MultiBinding Typen nicht bereit, und ein WinUI-Wertkonverter empfängt nur einen Quellwert. Verwenden Sie zum Kombinieren von Werten eine x:Bind Funktionsbindung mit mehreren Argumenten und Mode=OneWay, oder stellen Sie eine berechnete Viewmodel-Eigenschaft bereit. PriorityBinding Fallback erfolgt nicht automatisch, implementieren Sie sie daher explizit, zum Beispiel in dieser Funktion oder im View-Model.
Style durch BasedOn ✅ Unterstützt Formatvererbung mit BasedOn funktioniert in WinUI 3.
Implizite Formatvorlagen ✅ Unterstützt Implizite Stile im Ressourcenwörterbuch (Stile ohne x:Key) funktionieren wie erwartet.
AdornerLayer Benutzerdefinierter Überlagerungsansatz WinUI 3 hat keine Entsprechung für die Adorner-Schicht. Verwenden Sie ein Canvas- oder Grid-Overlay, wenn dies dem Szenario entspricht, und berücksichtigen Sie Eingabe, Fokus, Clipping, Bildlauf und Barrierefreiheit.

Threading und Dispatching

WPF Muster WinUI 3-Entsprechung Hinweise
Dispatcher.Invoke / BeginInvoke DispatcherQueue.TryEnqueue WinUI 3 verwendet DispatcherQueue. Das asynchrone Muster wird mit Hilfe der await DispatcherQueue.EnqueueAsync(...)-Community Toolkit-Erweiterung verwendet.
Application.Current.Dispatcher DispatcherQueue.GetForCurrentThread() Erfassen Sie DispatcherQueue zum Zeitpunkt der Erstellung im Benutzeroberflächen-Thread und speichern Sie es für die spätere Verwendung in Hintergrundthreads.
BackgroundWorker Task / async-await Verwenden Sie Task, CancellationToken und IProgress<T>, wo sie zur Workload passen. Überprüfen Sie den Abbruch, die Ausnahmebehandlung, die Fortschrittsmeldung und den UI-Threadzugriff, anstatt eine mechanische Ersetzung anzuwenden.

App-Modell und Lebenszyklus

WPF Konzept WinUI 3-Entsprechung Hinweise
Application.Startup / Exit Ereignisse App.OnLaunched / Window.Closed WinUI 3 verwendet OnLaunched in App.xaml.cs als Einstiegspunkt. Das Aufräumen auf Fensterebene wird in Window.Closed behandelt.
Application.Current.MainWindow Ihre Window Instanz Behalten Sie einen Verweis auf Ihre Fensterinstanz in App.xaml.cs und exponieren Sie ihn als Eigenschaft.
Window-Unterklassen AppWindow-Anpassung WinUI 3-Fenster werden durch AppWindow (Titelleiste, Presenter, überlappende/Vollbild-/kompakte Überlagerungsmodi) anstatt durch Subklassifizierung angepasst. Siehe Verwalten von App-Fenstern.
SystemParameters DisplayArea / UISettings Systemanzeigeeigenschaften sind über DisplayArea und UISettings verfügbar.

Ressourcen und Lokalisierung

WPF Muster WinUI 3-Entsprechung Hinweise
.resx Ressourcendateien .resw + ResourceLoader WinUI 3 verwendet .resw Dateien und die ResourceLoader-API . Migrieren Sie die Ressourcenzeichenfolgen, und aktualisieren Sie den Ressourcensuchcode im Rahmen der UI-Migration.
x:Static Markuperweiterung x:Bind zu einer statischen Eigenschaft Verwenden Sie x:Bind mit einer statischen Eigenschaft oder einem Singleton-Accessor. Überprüfen Sie die Initialisierungsreihenfolge und die Änderungsbenachrichtigung, wenn sich der Wert ändern kann.
Zusammengeführte Ressourcenverzeichnisse ✅ Unterstützt ResourceDictionary.MergedDictionaries arbeitet in WinUI 3.
Themaspezifische Ressourcenwörterbücher ✅ Unterstützt ResourceDictionary.ThemeDictionaries ist der WinUI 3-Mechanismus für themenbezogene Ressourcen und integriert sich nahtlos in die automatische Umschaltung zwischen den dunklen und hellen Modi.

Druck

WPF-Funktion WinUI 3-Status Hinweise
PrintDialog / PrintDocument PrintManager Das Drucken verwendet eine andere API und einen anderen Workflow. Eine Desktop-App muss PrintManager für ihr Fenster über die Desktop-Interop-API abrufen. Siehe "Drucken aus Ihrer App".

Entwicklertools

WPF-Tools WinUI 3-Status Hinweise
XAML-Designer (Registerkarte "Entwurf") Noch nicht unterstützt Der Visual Studio XAML-Designer unterstützt derzeit keine WinUI 3-Projekte. XAML-Hot Reload wird unterstützt und ist die empfohlene Möglichkeit zum Durchlaufen von Layout und Formatvorlagen, ohne den Debugger zu beenden.
Blend für Visual Studio ⚠| Eingeschränkter Support Blend wird mit Visual Studio ausgeliefert und kann WinUI 3-Projekte öffnen. Die XAML-Dokumentgliederung ist funktionsfähig, aber die Entwurfsansicht ist für WinUI 3 nicht verfügbar.

Lücken vor der Migration bewerten

Überprüfen Sie die Lücken, die sich auf Ihr Produkt auswirken, bevor Sie sich auf eine Benutzeroberflächenmigration festlegen. Beispiele hierfür sind das Fehlen von DataGrid, Ribbon, einer Adorner-Ebene, eines WPF-Dokumentmodells und einer WinUI 3-Entwurfsoberfläche in Visual Studio von Erstanbietern. Steuerelemente von Drittanbietern, benutzerdefinierte Zeichnung, Automatisierungspeers für die Barrierefreiheit, Drucken, mehrere Fenster und Bereitstellung können auch Architektur- oder Produktentscheidungen anstelle von API-Ersetzungen erfordern.

Erstellen Sie Prototypen repräsentativer Bildschirme und risikoreicher Integrationen, bevor Sie die vollständige Migration schätzen. Wenn eine erforderliche Funktion keine akzeptable Entsprechung aufweist, behalten Sie diesen Workflow in WPF, modernisieren Sie ihn an Ort und Stelle, oder verschieben Sie die UI-Migration.

Verwenden Sie einen KI-Assistenten als optionale Prüfhilfe

Ein KI-Codierungs-Assistent kann eine begrenzte WPF-Ansicht überprüfen, Abhängigkeiten von WPF-spezifischen APIs identifizieren, ein Steuerelement oder eine Bindungszuordnung entwerfen und Bearbeitungen zur Überprüfung vorschlagen. Es kann auch helfen, eine Bestandsaufnahme von Kontrollen und Plattformintegrationen von Drittanbietern zu erstellen.

Überprüfen Sie jeden Vorschlag anhand der aktuellen WinUI 3-Dokumentation und des Verhaltens, das Ihre App benötigt. Erstellen und testen Sie generierte Änderungen, einschließlich Datenbindung, Threading, Fensterbesitz, Barrierefreiheit, Lokalisierung, Verpackung und Fehlerbehandlung. Ein Assistent kann keine fehlenden Plattformfeatures bereitstellen, akzeptable Produktkompromisse auswählen oder garantieren, dass ein ähnlich aussehendes Steuerelement den ursprünglichen Workflow beibehält.

Siehe auch