Benutzeroberflächenmigration (einschließlich WinUI 3)

Artikel
06/13/2024

In diesem Thema wird gezeigt, wie Sie Ihren Benutzeroberflächencode migrieren, einschließlich der Migration zu WinUI 3.

Zusammenfassung der API- und/oder Funktionsunterschiede

Die Window.Current-Eigenschaft wird zu App.Window migriert. Und die CoreDispatcher.RunAsync-Methode wird zu DispatcherQueue.TryEnqueue migriert.

Sie müssen den Handle Ihres Fensters (HWND) in einem MessageDialog und in Pickers festlegen.

Um DataTransferManager-APIs zu verwenden, müssen Sie sie ihrem Fenster zuordnen.

Für ContentDialog und Popup müssen Sie deren XamlRoot-Eigenschaft festlegen.

Möglicherweise müssen Sie Ihren Visual State-Manager und das Page.Resources-XAML-Markup umgestalten.

Im Windows App SDK werden vom AcrylicBrush immer Beispiele aus dem App-Inhalt verwendet.

Ändern von Windows.UI.Xaml.Window.Current in App.Window

Dieser Abschnitt trifft zu, wenn Sie die Windows.UI.Xaml.Window.Current-Eigenschaft in Ihrer UWP-App verwenden. Diese Eigenschaft wird im Windows App SDK nicht unterstützt. In diesem Abschnitt wird beschrieben, wie Sie UWP-Code portieren, der Window.Current verwendet.

// MainPage.xaml.cs in a UWP app
var width = Window.Current.Bounds.Width;

// MainPage.xaml.cpp in a UWP app
auto width{ Window::Current().Bounds().Width };

Ihre Windows App SDK-App kann einen eigenen Begriff eines aktuellen oder Haupt-Fensters hinzufügen, indem Sie eine öffentliche statische Eigenschaft in Ihrer App-Klasse verwenden.

// App.xaml.cs in a Windows App SDK app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a Windows App SDK app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

Anschließend können Sie innerhalb der App-Klasse Window.Current ganz einfach in window ändern. Ändern Sie außerhalb der App-Klasse Window.Current in App.Window, wie im Folgenden dargestellt:

// MainPage.xaml.cs in a UWP app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a UWP app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

MessageDialog und Auswahl-Elemente

Wenn Sie in Ihrer UWP-App bestimmte Typen aus den Namespaces Windows.UI.Popups oder Windows.Storage.Pickers verwenden, enthält dieser Abschnitt Informationen zum Migrieren dieses Codes. Die folgenden Codebeispiele verwenden MessageDialog, aber Sie können genau die gleichen Techniken anwenden, um eine Auswahl anzuzeigen (z. B. einen FileOpenPicker, einen FileSavePicker oder einen FolderPicker).

Die Schritte, die Sie in einer Desktop-App ausführen müssen, werden in Anzeigen von WinRT-UI-Objekte, die von CoreWindow abhängig sind beschrieben.

Hinweis

Für neue Apps empfehlen wir die Verwendung des ContentDialog-Steuerelements anstelle von MessageDialog. Weitere Informationen finden Sie im Abschnitt ContentDialog und Popup weiter unten.

Im Folgenden finden Sie einen typischen UWP-Code zum Anzeigen eines MessageDialog.

// In a UWP app
var showDialog = new Windows.UI.Popups.MessageDialog("Message here");
await showDialog.ShowAsync();

// In a UWP app
auto showDialog{ Windows::UI::Popups::MessageDialog(L"Message here") };
co_await showDialog.ShowAsync();

Und hier sehen Sie den entsprechenden Code in einer Windows App SDK-App.

// MainWindow.xaml.cs in a WinUI 3 app
var showDialog = new Windows.UI.Popups.MessageDialog("Message here");
WinRT.Interop.InitializeWithWindow.Initialize(showDialog,
    WinRT.Interop.WindowNative.GetWindowHandle(this));
await showDialog.ShowAsync();

// pch.h in a WinUI 3 app
...
#include <Shobjidl.h>
#include <microsoft.ui.xaml.window.h>
#include <winrt/Windows.UI.Popups.h>
...

// MainWindow.xaml.cpp
...
auto showDialog{ Windows::UI::Popups::MessageDialog(L"Message here") };

auto windowNative{ this->m_inner.as<::IWindowNative>() };
HWND hWnd{ 0 };
windowNative->get_WindowHandle(&hWnd);
showDialog.as<::IInitializeWithWindow>()->Initialize(hWnd);

co_await showDialog.ShowAsync();

DataTransferManager

Wenn Sie in Ihrer UWP-App die DataTransferManager.ShowShareUI-Methode aufrufen, enthält dieser Abschnitt Informationen, mit denen Sie diesen Code migrieren können.

Hier ist ein typischer UWP-Code angegeben, der ShowShareUI aufruft.

// In a UWP app
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.GetForCurrentView();

dataTransferManager.DataRequested += (sender, args) =>
{
    args.Request.Data.Properties.Title = "In a UWP app...";
    args.Request.Data.SetText("...display the user interface for sharing content with another app.");
    args.Request.Data.RequestedOperation =
        Windows.ApplicationModel.DataTransfer.DataPackageOperation.Copy;
};

Windows.ApplicationModel.DataTransfer.DataTransferManager.ShowShareUI();

// In a UWP app
#include <winrt/Windows.ApplicationModel.DataTransfer.h>
...
auto dataTransferManager{ Windows::ApplicationModel::DataTransfer::DataTransferManager::GetForCurrentView() };

dataTransferManager.DataRequested([](Windows::ApplicationModel::DataTransfer::DataTransferManager const& /* sender */,
    Windows::ApplicationModel::DataTransfer::DataRequestedEventArgs const& args)
    {
        args.Request().Data().Properties().Title(L"In a UWP app...");
        args.Request().Data().SetText(L"...display the user interface for sharing content with another app.");
        args.Request().Data().RequestedOperation(Windows::ApplicationModel::DataTransfer::DataPackageOperation::Copy);
    });

Windows::ApplicationModel::DataTransfer::DataTransferManager::ShowShareUI();

Um DataTransferManager.ShowShareUI in Ihrer Windows App SDK-App zu verwenden, müssen Sie die Benutzeroberfläche „Freigeben“ Ihrem Fenster zuordnen. Und das muss manuell durchgeführt werden. Weitere Informationen und Codebeispiele finden Sie unter Anzeigen von WinRT-UI-Objekten, die von CoreWindow abhängen.

Wenn Sie in Ihrer UWP-App die Windows.UI.Xaml.Controls.ContentDialog- oder Windows.UI.Xaml.Controls.Primitives.Popup-Klassen verwenden, enthält dieser Abschnitt Informationen zum Migrieren dieses Codes. In den folgenden Codebeispielen wird ContentDialog verwendet, aber Sie können jedoch genau die gleichen Techniken anwenden, um ein Popup-Objekt anzuwenden.

Im Folgenden finden Sie einen typischen UWP-Code zum Anzeigen eines ContentDialog.

// MainPage.xaml.cs in a UWP app
var unsupportedFilesDialog = new ContentDialog();
// Set Title, Content, etc.
await unsupportedFilesDialog.ShowAsync();

// MainPage.xaml.cpp in a UWP app
ContentDialog unsupportedFilesDialog{};
// Set Title, Content, etc.
co_await unsupportedFilesDialog.ShowAsync();

In Ihrer Windows App SDK-App müssen Sie lediglich auch die XamlRoot-Eigenschaft festlegen. Gehen Sie dazu wie folgt vor:

// MainPage.xaml.cs in a Windows App SDK app
var unsupportedFilesDialog = new ContentDialog();
// Set Title, Content, etc.
unsupportedFilesDialog.XamlRoot = this.Content.XamlRoot;
await unsupportedFilesDialog.ShowAsync();

// MainPage.xaml.cpp in a Windows App SDK app
ContentDialog unsupportedFilesDialog{};
// Set Title, Content, etc.
unsupportedFilesDialog.XamlRoot(this->Content().XamlRoot());
co_await unsupportedFilesDialog.ShowAsync();

In einem UWP-Projekt gibt es standardmäßig Navigationscode in den Methoden der App-Klasse, auch wenn Ihre App einfach genug ist, dass sie nur eine Seite enthält.

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.

Für eine Windows App SDK-App, die einfach genug ist (eine Einzelseiten-App), können Sie sie möglicherweise vereinfachen. Möglicherweise müssen Sie keine Seiten oder Benutzersteuerelemente in Ihrem Windows App SDK-Projekt erstellen, sondern stattdessen das XAML-Markup und CodeBehind dieser einzelnen Seite in MainWindow kopieren. Es gibt jedoch einige Dinge, die MainWindow nicht unterstützt. Window ist kein DependencyObject, sodass Funktionen wie Resources und DataContext nicht vorhanden sind. Ereignisse wie Load und Unload sind ebenfalls nicht vorhanden. Weitere Informationen und Problemumgehungen finden Sie unter Visual State-Manager und Page.Resources.

Wenn Sie andererseits die Navigation zwischen Seiten in Ihrer Windows App SDK-App wünschen oder benötigen, können Sie dies tun, indem Sie die App.OnLaunched- und App::OnNavigationFailed-Methoden aus Ihrer UWP-App migrieren. Suchen Sie in App.OnLaunched den Navigationscode (der Code, der rootFrame erstellt und zur ersten Seite Ihrer App navigiert), und fügen Sie ihn direkt zwischen den beiden vorhandenen Codezeilen ein (die Zeilen, die ein Fenster erstellen und es dann aktivieren). Sie müssen auch den Code migrieren, den Sie kopiert haben. Ein einfaches Codebeispiel finden Sie unter Page-Klasse.

Visual State-Manager und Page.Resources

Siehe auch Muss ich die Seitennavigation implementieren?. Wenn Sie über eine UWP-App verfügen, die einfach genug ist, sodass Sie Ihre XAML-Markups und CodeBehind in MainWindow kopieren können, dann beachten Sie diese Ausnahmen.

Ihre MainWindow-Klasse (vom Typ Microsoft.UI.Xaml.Window) ist kein Steuerelement, sodass sie kein XAML-Markup und CodeBehind von Visual State-Manager unterstützt (siehe Tutorial: Erstellen adaptiver Layouts). Sie haben jedoch diese beiden Möglichkeiten:

Fügen Sie dem Projekt ein UserControl-Element hinzu, und migrieren Sie Ihr Markup und CodeBehind zu diesem Element. Platzieren Sie dann eine Instanz dieses Benutzersteuerelements in MainWindow.
Fügen Sie dem Projekt ein Page-Element hinzu, und migrieren Sie Ihr Markup und CodeBehind zu diesem Element. Fügen Sie Ihrer App-Klasse dann Code zu, um beim Start zu dieser Page zu navigieren, wie in Muss ich die Seitennavigation implementieren? beschreiben.

Darüber hinaus können Sie ein <Page.Resources>-Element nicht in MainWindow kopieren und einfach in <Window.Resources> umbenennen. Ordnen Sie stattdessen das Resources-Element dem Stammlayoutcontainer als übergeordnetes Element (z. B. einem Grid) im XAML-Markup für MainWindow zu. Dies sieht folgendermaßen aus:

<Window ...>
    <Grid>
        <Grid.Resources>...</Grid.Resources>
        ...
    </Grid>
</Window>

AcrylicBrush.BackgroundSource property

Die AcrylicBrush.BackgroundSource-Eigenschaft ist in UWP vorhanden, jedoch nicht im Windows App SDK. Im Windows App SDK werden vom AcrylicBrush immer Beispiele aus dem App-Inhalt verwendet.

Wenn Sie also auf die AcrylicBrush.BackgroundSource-Eigenschaft im Quellcode Ihrer UWP-App (ob im XAML-Markup oder im imperativen Code) zugreifen, entfernen Sie diesen Code, wenn Sie Ihre App zum Windows App SDK migrieren. Verwenden Sie stattdessen die DesktopAcrylicController-Klasse.

Freigeben über

Benutzeroberflächenmigration (einschließlich WinUI 3)

Zusammenfassung der API- und/oder Funktionsunterschiede

Ändern von Windows.UI.Xaml.Window.Current in App.Window

MessageDialog und Auswahl-Elemente

DataTransferManager

Muss ich die Seitennavigation implementieren?

Visual State-Manager und Page.Resources

AcrylicBrush.BackgroundSource property

Zusätzliche Ressourcen

Freigeben über

Benutzeroberflächenmigration (einschließlich WinUI 3)

Zusammenfassung der API- und/oder Funktionsunterschiede

Ändern von Windows.UI.Xaml.Window.Current in App.Window

MessageDialog und Auswahl-Elemente

DataTransferManager

ContentDialog und Popup

Muss ich die Seitennavigation implementieren?

Visual State-Manager und Page.Resources

AcrylicBrush.BackgroundSource property

Zugehörige Themen

Zusätzliche Ressourcen