Migration von Fensterfunktionen
Dieses Thema enthält Anleitungen zur Fensterverwaltung, u. a. zur Migration der UWP-Klasse ApplicationView/CoreWindow oder AppWindow zur Klasse Microsoft.UI.Windowing.AppWindow des Windows App SDK.
Wichtige APIs
- Microsoft.UI.Windowing.AppWindow
- Eigenschaft Windows.UI.Core.CoreWindow.Dispatcher
- Eigenschaft Microsoft.UI.Window.DispatcherQueue
Zusammenfassung der API- und/oder Funktionsunterschiede
Das Windows App SDK stellt die Klasse Microsoft.UI.Windowing.AppWindow bereit, die auf dem Win32-HWND-Modell basiert. Diese AppWindow-Klasse ist die Windows App SDK-Version von ApplicationView/CoreWindow und AppWindow der UWP.
Um die Vorteile der Windows App SDK-Fenster-APIs nutzen zu können, müssen Sie Ihren UWP-Code auf das Win32-Modell umstellen. Weitere Informationen zur AppWindow-Klasse des Windows App SDK finden Sie unter Verwalten von App-Fenstern (Windows App SDK).
Tipp
Das Thema Verwalten von App-Fenstern (Windows App SDK) enthält ein Codebeispiel, das veranschaulicht, wie eine AppWindow-Klasse aus einem WinUI 3-Fenster abgerufen wird. Verwenden Sie in Ihrer WinUI 3-App dieses Codemuster, damit Sie die AppWindow-APIs aufrufen können, die im weiteren Verlauf dieses Themas erwähnt werden.
Fenstertypen der UWP und des Windows App SDK im Vergleich
In einer UWP-App können Sie Fensterinhalte mithilfe von ApplicationView/CoreWindow oder AppWindow hosten. Die Schritte für die Migration dieses Codes zum Windows App SDK hängen davon ab, welches dieser beiden Fenstermodelle Ihre UWP-App verwendet. Wenn Sie mit der UWP-Klasse Windows.UI.WindowManagement.AppWindow vertraut sind, erkennen Sie möglicherweise Ähnlichkeiten zwischen dieser Klasse und Microsoft.UI.Windowing.AppWindow.
UWP-Fenstertypen
- Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
- Windows.UI.WindowManagement.AppWindow. AppWindow konsolidiert den UI-Thread und das Fenster, das die App zum Anzeigen von Inhalten verwendet. Für UWP-Apps, die AppWindow verwenden, müssen weniger Schritte ausgeführt werden als für ApplicationView-/CoreWindow-Apps, um zu Windows App SDK AppWindow zu migrieren.
Windows App SDK-Fenstertyp
- Microsoft.UI.Windowing.AppWindow ist die allgemeine Abstraktion eines systemseitig verwalteten Containers für den Inhalt einer App.
Beachten Sie, dass die Unterschiede in den Fenstermodellen zwischen UWP und Win32 dazu führen, dass es keine direkte 1:1-Zuordnung zwischen der UWP-API-Oberfläche und der Windows App SDK-API-Oberfläche gibt. Selbst bei Klassen- und Membernamen, die von UWP übernommen werden (was sich in den Zuordnungstabellen dieses Themas widerspiegelt), kann sich das Verhalten ebenfalls unterscheiden.
Begrüßungsbildschirme
Im Gegensatz zu UWP-Apps wird bei Win32-Apps beim Start standardmäßig kein Begrüßungsbildschirm angezeigt. UWP-Apps, die dieses Feature für ihre Starterfahrung nutzen, können einen benutzerdefinierten Übergang zu ihrem ersten App-Fenster implementieren.
Erstellen, Anzeigen, Schließen und Löschen eines Fensters
Die Lebensdauer eines Microsoft.UI.Windowing.AppWindow-Objekts ist identisch mit der für ein HWND. Das bedeutet, dass das AppWindow-Objekt unmittelbar nach dem Erstellen des Fensters verfügbar ist und beim Schließen des Fensters gelöscht wird.
Erstellen und Anzeigen
AppWindow.Create erstellt ein App-Fenster mit der Standardkonfiguration. Das Erstellen und Anzeigen eines Fensters ist nur für Szenarien erforderlich, in denen kein Benutzeroberflächenframework verwendet wird. Wenn Sie Ihre UWP-App zu einem Win32-kompatiblen Benutzeroberflächenframework migrieren, können Sie das AppWindow-Objekt dennoch über ein bereits erstelltes Fenster erreichen, indem Sie die Interop-Methoden für Fenster verwenden.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| CoreApplication.CreateNewView oder CoreWindow.GetForCurrentThread |
AppWindow.TryCreateAsync | AppWindow.Create |
| CoreWindow.Activate | AppWindow.TryShowAsync | AppWindow.Show |
Schließen
Auf der UWP ist ApplicationView.TryConsolidateAsync die programmgesteuerte Entsprechung zu einer von Benutzer*innen initiierten Geste zum Schließen. Dieses Konsolidierungskonzept (im ApplicationView-/CoreWindow-Fenstermodell der UWP) ist in Win32 nicht vorhanden. Win32 erfordert nicht, dass Fenster in separaten Threads vorhanden sind. Zum Replizieren des ApplicationView-/CoreWindow-Fenstermodells der UWP müssen Entwickler*innen einen neuen Thread und dort ein neues Fenster erstellen. Im Win32-Modell ist das Standardsystemverhalten Schließen>Ausblenden>Löschen.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| ApplicationView.TryConsolidateAsync | AppWindow.CloseAsync | AppWindow.Destroy |
Grundlegende Fensteranpassung
Wenn Sie von der UWP zum Windows App SDK migrieren, können Sie die gleiche Umgebung wie bei der AppWindow-Standardklasse erwarten. Bei Bedarf können Sie jedoch die Standardklasse Microsoft.UI.Windowing.AppWindow für angepasste Fensterumgebungen ändern. Weitere Informationen zum Anpassen Ihrer Fenster finden Sie unter Microsoft.UI.Windowing.AppWindow.
Ändern der Fenstergröße
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| ApplicationView.TryResizeView | AppWindow.RequestSize | AppWindow.Resize |
CoreWindow.Bounds (wird in C# häufig als CoreWindow.GetForCurrentThread.Bounds angezeigt) |
AppWindowPlacement.Size | AppWindow.Size |
Positionieren eines Fensters
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| Nicht möglich | AppWindow.GetPlacement | AppWindow.Position |
| Nicht möglich | Appwindow.RequestMoveXxx | AppWindow.Move |
Fenstertitel
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| ApplicationView.Title | AppWindow.Title | AppWindow.Title |
Kompakte Überlagerung und Vollbild
Apps, die in die kompakte Überlagerung oder in den Vollbildmodus wechseln, sollten AppWindowPresenter des Windows App SDK nutzen. Wenn Sie mit der UWP-Klasse AppWindow vertraut sind, kennen Sie möglicherweise bereits das Konzept von Referenten.
Es gibt keine 1:1-Zuordnung von Funktionen und Verhalten der Referenten für UWP-App-Fenster zu Referenten für Windows App SDK-App-Fenster. Wenn Sie über eine UWP-App für ApplicationView/CoreWindow verfügen, können Sie weiterhin Fensterumgebungen mit kompakter Überlagerung (Bild im Bild) oder Vollbildmodus in Ihrer App verwenden, aber das Konzept von Referenten ist möglicherweise neu für Sie. Weitere Informationen zu App-Fenster-Referenten finden Sie unter Verwalten von App-Fenstern (Windows App SDK). Bei der Erstellung wird standardmäßig ein überlappender Referent auf AppWindow angewendet. CompactOverlay und FullScreen sind neben der Standardeinstellung die einzigen verfügbaren Referenten.
Kompakte Überlagerung
Wenn Sie die UWP-Klasse ApplicationViewMode oder AppWindowPresentionKind zum Darstellen eines Fensters mit kompakter Überlagerung verwendet haben, sollten Sie das AppWindowPresenterKind-Element für die kompakte Überlagerung nutzen. Microsoft.UI.Windowing.CompactOverlayPresenter unterstützt nur drei feste Fenstergrößen mit dem Seitenverhältnis 16:9, und die Größe kann von Benutzer*innen nicht geändert werden. Anstelle von ApplicationViewMode.TryEnterViewModeAsync oder AppWindowPresenterKind.RequestPresentation sollten Sie AppWindow.SetPresenter verwenden, um die Darstellung von AppWindow zu ändern.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| ApplicationViewMode.CompactOverlay | AppWindowPresentationKind.CompactOverlay | AppWindowPresenterKind.CompactOverlay |
| ApplicationView.TryEnterViewModeAsync mit ApplicationViewMode.CompactOverlay | AppWindowPresenter.RequestPresentation mit AppWindowPresenterKind.CompactOverlay | AppWindow.SetPresenter mit AppWindowPresenterKind.CompactOverlay |
Vollbild
Wenn Sie die UWP-Klasse ApplicationViewWindowingMode oder AppWindowPresentionKind verwendet haben, um ein Vollbildfenster anzuzeigen, sollten Sie das Element AppWindowPresenterKind für den Vollbildmodus nutzen. Das Windows App SDK unterstützt nur die restriktivste Vollbilddarstellung (d. h. FullScreen ist IsExclusive). Für ApplicationView/CoreWindow können Sie ApplicationView.ExitFullScreenMode verwenden, um den Vollbildmodus für die App zu beenden. Wenn Sie Referenten verwenden, können Sie den Vollbildmodus für eine App beenden, indem Sie den Referenten mithilfe von AppWindow.SetPresenter wieder auf „overlapped“ (Überlappung) oder auf die Standardeinstellung festlegen.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| ApplicationViewWindowingMode.FullScreen | AppWindowPresentationKind.FullScreen | AppWindowPresenterKind.FullScreen |
| ApplicationView.TryEnterFullScreenMode | AppWindowPresenter.RequestPresentation mit AppWindowPresenterKind.FullScreen | AppWindow.SetPresenter mit AppWindowPresenterKind.FullScreen |
Weitere Informationen zum Arbeiten mit Referenten für App-Fenster finden Sie im Fensterkatalogbeispiel. Es veranschaulicht, wie verschiedene Zustände von App-Fensterreferenten umgeschaltet werden.
Benutzerdefinierte Titelleiste
Hinweis
Titelleistenanpassungs-APIs können derzeit nur unter Windows 11 verwendet werden. Es wird empfohlen, AppWindowTitleBar.IsCustomizationSupported in Ihrem Code zu prüfen, bevor Sie diese APIs aufrufen.
Wenn Ihre App eine Standardtitelleiste verwendet, sind bei der Migration zu Win32 keine zusätzlichen Schritte für die Titelleiste erforderlich. Wenn Ihre UWP-App hingegen über eine benutzerdefinierte Titelleiste verfügt, können Sie die folgenden Szenarien in Ihrer Windows App SDK-App nachstellen:
- Anpassen der vom System gezeichneten Titelleiste
- Von der App gezeichnete benutzerdefinierte Titelleiste
Code, der die UWP-Klassen ApplicationViewTitleBar, CoreApplicationViewTitleBar und AppWindowTitleBar verwendet, wird auf die Verwendung der Windows App SDK-Klasse Microsoft.UI.Windowing.AppWindowTitleBar umgestellt.
Anpassen der vom System gezeichneten Titelleiste
Im Anschluss finden Sie eine Tabelle mit den Farbanpassungs-APIs.
Hinweis
Wenn true für AppWindowTitleBar.ExtendsContentIntoTitleBar festgelegt ist, wird Transparenz nur für die folgenden Eigenschaften unterstützt: AppWindowTitleBar.ButtonBackgroundColor, AppWindowTitleBar.ButtonInactiveBackgroundColor, AppWindowTitleBar.ButtonPressedBackgroundColor, AppWindowTitleBar.ButtonHoverBackgroundColor und AppWindowTitleBar.BackgroundColor (implizit festgelegt).
Diese Windows App SDK-APIs dienen neben der AppWindow.Title-API zur weiteren Anpassung der vom System gezeichneten Titelleiste.
- AppWindow.SetIcon. Legt die Titelleiste und das Symbolbild der Taskleiste mithilfe eines hicon-Handles oder eines Zeichenfolgenpfads zu einer Ressource oder einer Datei fest.
- AppWindowTitleBar.IconShowOptions. Ruft einen Wert ab, der angibt, wie das Fenstersymbol auf der Titelleiste angezeigt wird, oder legt diesen fest. Unterstützt derzeit zwei Werte: HideIconAndSystemMenu und ShowIconAndSystemMenu.
- AppWindowTitleBar.ResetToDefault. Setzt die aktuelle Titelleiste wieder auf die Standardeinstellungen für das Fenster zurück.
Vom App gezeichnete benutzerdefinierte Titelleiste (vollständige Anpassung)
Wenn Sie zu AppWindowTitleBar migrieren, empfiehlt es sich, AppWindowTitleBar.IsCustomizationSupported in Ihrem Code zu prüfen, bevor Sie die folgenden benutzerdefinierten Titelleisten-APIs aufrufen:
| UWP ApplicationView/CoreWindow | Windows App SDK AppWindow |
|---|---|
| CoreApplicationViewTitleBar.ExtendViewIntoTitleBar | AppWindowTitleBar.ExtendsContentIntoTitleBar Die Plattform zeichnet weiterhin die Schaltflächen Minimieren/Maximieren/Schließen für Sie und meldet die Informationen zur Verdeckung. |
| CoreApplicationViewTitleBar.SystemOverlayLeftInset | AppWindowTitleBar.LeftInset |
| CoreApplicationViewTitleBar.SystemOverlayRightInset | AppWindowTitleBar.RightInset |
| CoreApplicationViewTitleBar.Height | AppWindowTitleBar.Height |
| AppWindowTitleBarOcclusion AppWindowTitleBar.GetTitleBarOcclusions |
Stellt die vom System reservierten Bereiche des App-Fensters dar, die App-Inhalte verdecken, wenn ExtendsContentIntoTitleBar auf „true“ festgelegt ist. Die Angaben zur linken und rechten Einblendung von Windows App SDK AppWindow in Verbindung mit der Titelleistenhöhe bieten die gleichen Informationen. AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height |
Diese Windows App SDK-APIs dienen zur vollständigen Anpassung der Titelleiste.
- AppWindowTitleBar.SetDragRectangles. Legt die Ziehbereiche für das Fenster fest.
- AppWindowTitleBar.ResetToDefault. Setzt die aktuelle Titelleiste wieder auf die Standardeinstellungen für das Fenster zurück.
Diese UWP-AppWindow-APIs verfügen über keine direkte 1:1-Zuordnung zu einer Windows App SDK-API.
- AppWindowTitleBarVisibility. Definiert Konstanten, die die bevorzugte Sichtbarkeit von AppWindowTitleBar angeben.
- AppWindowTitleBar.GetPreferredVisibility. Ruft den bevorzugten Sichtbarkeitsmodus für die Titelleiste ab.
- AppWindowTitleBar.SetPreferredVisibility. Legt den bevorzugten Sichtbarkeitsmodus für die Titelleiste fest.
Weitere Informationen zum Arbeiten mit AppWindowTitleBar finden Sie im Fensterkatalogbeispiel. Es veranschaulicht, wie Sie eine Titelleiste mit benutzerdefinierter Farbe erstellen und eine benutzerdefinierte Titelleiste zeichnen.
Ereignisbehandlung
Wenn Ihre UWP-App das Ereignis AppWindow.Changed verwendet, können Sie diesen Code zum Ereignis Microsoft.UI.Windowing.AppWindow.Changed migrieren.
Ereignis vom Typ „Größe geändert“
Beim Migrieren von Code zur Behandlung von Ereignissen des Typs „Größe geändert“ sollten Sie zur Verwendung der Windows App SDK-Eigenschaft AppWindowChangedEventArgs.DidSizeChange wechseln. Der Wert ist true, wenn sich die Größe des App-Fensters geändert hat, andernfalls false.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows-App-SDK |
|---|---|---|
| CoreWindow.SizeChanged | AppWindowChangedEventArgs.DidSizeChange | AppWindowChangedEventArgs.DidSizeChange |
MainPage und MainWindow
Wenn Sie ein neues UWP-Projekt in Visual Studio erstellen, stellt Ihnen die Projektvorlage eine MainPage-Klasse zur Verfügung. Für Ihre App haben Sie diese Klasse möglicherweise umbenannt (und/oder weitere Seiten und Benutzersteuerelemente hinzugefügt). Die Projektvorlage stellt darüber hinaus Navigationscode in den Methoden der App-Klasse bereit.
Wenn Sie ein neues Windows App SDK-Projekt in Visual Studio erstellen, stellt Ihnen die Projektvorlage eine MainWindow-Klasse (vom Typ Microsoft.UI.Xaml.Window) aber keine Page-Klasse zur Verfügung. Darüber hinaus enthält die Projektvorlage keinen Navigationscode.
Sie haben jedoch die Möglichkeit, Ihrem Windows App SDK-Projekt Seiten und Benutzersteuerelemente hinzuzufügen. Beispielsweise können Sie dem Projekt ein neues Seitenelement (WinUI>Leere Seite (WinUI 3)) hinzufügen und ihm den Namen MainPage.xaml oder einen anderen Namen geben. Dadurch wird Ihrem Projekt eine neue Klasse vom Typ Microsoft.UI.Xaml.Controls.Page hinzugefügt. Informationen zum Hinzufügen von Navigationscode zum Projekt finden Sie unter Muss ich die Seitennavigation implementieren?.
Für Windows App SDK-Apps, die einfach genug sind, müssen Sie keine Seiten oder Benutzersteuerelemente erstellen, und Sie können XAML-Markup und CodeBehind in MainWindow kopieren. Weitere Informationen zu Ausnahmen für diesen Workflow finden Sie unter Visual State Manager und Page.Resources.
Ändern sie CoreWindow.Dispatcher in Window.DispatcherQueue
Einige Anwendungsfälle für die UWP-Klasse Windows.UI.Core.CoreWindow werden zur Windows App SDK-Klasse Microsoft.UI.Xaml.Window-Klasse migriert.
Wenn Sie beispielsweise die Eigenschaft Windows.UI.Core.CoreWindow.Dispatcher in Ihrer UWP-App verwenden, besteht die Lösung nicht darin, zur Eigenschaft Microsoft.UI.Xaml.Window.Dispatcher zu migrieren. (Dabei wird immer NULL zurückgegeben.) Migrieren Sie stattdessen zur Eigenschaft Microsoft.UI.Xaml.Window.DispatcherQueue, die Microsoft.UI.Dispatching.DispatcherQueue zurückgibt.
Weitere Informationen und Codebeispiele finden Sie unter Change Windows.UI.Core.CoreDispatcher to Microsoft.UI.Dispatching.DispatcherQueue (Ändern von Windows.UI.Core.CoreDispatcher in Microsoft.UI.Dispatching.DispatcherQueue.
Zugehörige Themen
Windows developer