Verwenden des Windows App SDK in einer WPF-App

Die Windows App SDK ist die nächste Entwicklung in der Windows App-Entwicklungsplattform. In diesem Thema wird jedoch gezeigt, wie Sie Windows App SDK APIs (und Windows-Runtime-APIs) in einer Windows Presentation Foundation (WPF)-App verwenden können!

• In vielen Fällen möchten Sie Ihre WPF App in Form einer WinUI 3-App neu erstellen. Einer der Vorteile der Umstellung auf WinUI besteht darin, Zugriff auf das Fluent Design System zu haben (siehe auch Design und Code Windows Apps). Und WinUI ist Teil der Windows App SDK – natürlich kann eine WinUI-App auch die anderen Windows App SDK Features und APIs verwenden. In diesem Thema wird der Prozess der Migration Ihrer WPF-App zu WinUI nicht behandelt.
• Wenn Sie jedoch feststellen, dass Sie Features von WPF verwenden, die noch nicht in WinUI verfügbar sind, können Sie weiterhin Windows App SDK Features (z. B. App-Lebenszyklus, MRT Core, DWriteCore und andere) in Ihrer WPF-App verwenden. In diesem Thema wird gezeigt, wie es geht.

Und falls Sie noch nicht über ein WPF Projekt verfügen oder den Prozess üben möchten, enthält dieses Thema Schritte zum Erstellen eines WPF Projekts, damit Sie es befolgen und konfigurieren können, um Windows App SDK APIs aufzurufen.

Voraussetzungen

1. Installieren Sie Tools für die Windows App SDK.
2. In diesem Thema werden sowohl entpackte als auch verpackte WPF-Apps behandelt. Wenn Ihre WPF-App entpackt ist (was WPF-Apps standardmäßig sind), stellen Sie sicher, dass alle Abhängigkeiten für entpackte Apps installiert sind (siehe Windows App SDK Bereitstellungshandbuch für frameworkabhängige Apps, die mit externem Speicherort verpackt sind oder entpackt werden). Eine schnelle Möglichkeit hierfür ist, Latest-Downloads für die Windows App SDK zu besuchen und dann eine der stabilen Versionen Runtime downloads herunterzuladen und auszuführen.

Weitere Informationen zu den Begriffen entpackt und gepackt erhalten Sie unter Vorteile und Nachteile des Verpackens Ihrer App.

Erstellen eines WPF Projekts, wenn Sie noch kein Projekt haben

Wenn Sie bereits über ein WPF Projekt verfügen, können Sie zum nächsten Abschnitt wechseln.

1. Erstellen Sie in Visual Studio ein neues C#-WPF Application-Projekt (ein .NET Projekt). Achten Sie darauf, dass Sie die Projektvorlage mit dem genauen Namen WPF Application und nicht der WPF App (.NET Framework) auswählen.
2. Geben Sie dem project einen Namen, und akzeptieren Sie alle Standardoptionen.

Sie verfügen jetzt über ein Projekt, das eine entpackte WPF App erstellt.

Konfigurieren Ihres WPF Projekts für Windows App SDK Support

Zuerst bearbeiten wir die project Datei.

1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf Ihren project, und wählen Sie Edit Project File aus.

2. In diesem Schritt können Sie Windows-Runtime (WinRT)-APIs aufrufen (einschließlich Windows App SDK-APIs). Innerhalb des PropertyGroup-Elements befindet sich das TargetFramework-Element, das auf einen Wert wie net6.0 festgelegt ist. Fügen Sie an diesen Zielframeworkwert einen Moniker an (insbesondere einen Zielframework-Moniker). Verwenden Sie beispielsweise Folgendes, wenn Ihre App auf Windows 10, Version 2004, ausgerichtet ist:

   <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
   

3. Fügen Sie auch im PropertyGroup-Element ein RuntimeIdentifiers-Element hinzu, wie unten dargestellt. Wenn Sie auf .NET 8 oder höher abzielen, verwenden Sie stattdessen den Wert win-x86;win-x64;win-arm64.

   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   

4. Standardmäßig wird eine WPF-App entpackt (d. h., sie wird nicht mit MSIX installiert). Eine entpackte App muss die Windows App SDK Laufzeit initialisieren, bevor sie ein anderes Feature des Windows App SDK verwenden. Sie können dies automatisch durchführen, wenn Ihre App über die automatische Initialisierung gestartet wird. Sie legen einfach (auch innerhalb des PropertyGroup-Elements) die Projekteigenschaft WindowsPackageType entsprechend fest, wie folgt:

   <WindowsPackageType>None</WindowsPackageType>
   

   Wenn Sie erweiterte Anforderungen haben (z. B. eine benutzerdefinierte Fehlerbehandlung oder um eine spezifische Version des Windows App SDK zu laden), können Sie die Bootstrapper-API explizit aufrufen, statt Auto-Initialisierung zu verwenden – weitere Informationen finden Sie unter Verwenden Sie die Windows App SDK-Laufzeit für Apps, die mit externer Standortverpackung oder unverpackt sind.

5. Speichern und schließen Sie die project Datei.

Als Nächstes installieren wir das Windows App SDK NuGet-Paket im Projekt.

6. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf die Dependencies Knoten Ihres Projekts, und wählen Sie Manage Nuget Packages... .
7. Wählen Sie im Fenster NuGet Paket-Manager die Registerkarte Browse aus, und installieren Sie Latest stableMicrosoft. WindowsAppSDK-Paket.

Verwenden einiger Windows App SDK Features in Ihrer WPF-App

Dieser Abschnitt enthält ein sehr einfaches Beispiel für das Aufrufen Windows App SDK APIs aus einer WPF-App. Es verwendet das MRT Core-Feature (siehe Verwalten von Ressourcen mit MRT Core). Wenn dieses Beispiel für Ihr WPF Projekt funktioniert (und wenn Sie für diese exemplarische Vorgehensweise ein neues erstellt haben, können Sie diese Schritte ausführen.

1. Fügen Sie das folgende Markup zu MainWindow.xaml hinzu (Sie könnten es in das Wurzel-Grid einfügen):

   <StackPanel>
       <Button HorizontalAlignment="Center" Click="Button_Click">Click me!</Button>
       <TextBlock HorizontalAlignment="Center" x:Name="myTextBlock">Hello, World!</TextBlock>
   </StackPanel>
   

2. Nun fügen wir code hinzu, der die klasse ResourceManager im Windows App SDK zum Laden einer Zeichenfolgenressource verwendet.

   1. Fügen Sie ihrem project ein neues Resources File (.resw)element hinzu (lassen Sie es mit dem Standardnamen Resources.resw).

   2. Wenn die Ressourcendatei im Editor geöffnet ist, erstellen Sie eine neue Zeichenfolgenressource mit den folgenden Eigenschaften.

      • Name: Meldung
      • Wert: Hallo, Ressourcen!

   3. Speichern und schließen Sie die Ressourcendatei.

   4. Fügen Sie in MainWindow.xaml.cs den folgenden Ereignishandler hinzu:

   private void Button_Click(object sender, RoutedEventArgs e)
   {
       // Construct a resource manager using the resource index generated during build.
       var manager = 
         new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
   
       // Look up a string in the resources file using the string's name.
       myTextBlock.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
   }
   

3. Erstellen Sie das Projekt, und führen Sie die App aus. Klicken Sie auf die Schaltfläche, um sich die angezeigte Zeichenfolge Hello, resources! anzusehen.

Lesen Sie auch Runtime-Architektur um mehr über die Framework Paketabhängigkeit zu erfahren, die Ihre App benötigt, wenn die Windows App SDK verwendet wird, und die zusätzlichen Komponenten, die für die Arbeit in einer entpackten App erforderlich sind.

Packen und Bereitstellen Ihrer WPF-App mit MSIX

Einige Windows Features und APIs (einschließlich der Windows App SDK notifications-APIs) erfordern, dass Ihre App package identity zur Laufzeit besitzen muss (d. h. Ihre App muss packaged sein). Weitere Informationen finden Sie unter Features, für die Paketidentität benötigt wird.

1. Klicken Sie in Projektmappen-Explorer in Visual Studio mit der rechten Maustaste auf die Lösung, und wählen Sie Add>Neue Project... .
2. Geben Sie im Dialogfeld Neues Projekt hinzufügen ein, suchen Sie nach packaging, wählen Sie die Vorlage "C# Windows Application Packaging Project Projekt" aus, und klicken Sie auf Weiter.
3. Benennen Sie das Projekt, und klicken Sie auf Erstellen.
4. Wir möchten angeben, welche Anwendungen in der Lösung in das Paket aufgenommen werden sollen. Klicken Sie also im Packaging-Projekt (nicht das WPF-Projekt), klicken Sie mit der rechten Maustaste auf den Knoten Dependencies, und wählen Sie Projektverweis hinzufügen....
5. Wählen Sie in der Liste der Projekte in der Projektmappe Ihr WPF Projekt aus, und klicken Sie auf OK.
6. Erweitern Sie den Knoten Dependencies>Applications, und vergewissern Sie sich, dass Ihr WPF-Projekt fett gedruckt und hervorgehoben ist. Dies bedeutet, dass es als Ausgangspunkt für das Paket verwendet wird.
7. Klicken Sie mit der rechten Maustaste auf das Verpackungsprojekt, und wählen Sie Set As Startup Project aus.
8. Klicken Sie mit der rechten Maustaste auf das WPF-Projekt und wählen Sie Projektdatei bearbeiten aus.
9. Löschen Sie <WindowsPackageType>None</WindowsPackageType>, speichern und schließen Sie es.
10. Wählen Sie im Dropdownmenü Lösungsplattformenx64 (anstelle vonBeliebige CPU) aus.
11. Vergewissern Sie sich, dass Sie erstellen und ausführen können.

Nachdem Sie Ihre WPF-App gepackt haben, können Sie APIs aufrufen, die eine Paketidentität erfordern. Bearbeiten Sie also in MainWindow.xaml.cs ihren Ereignishandler so, dass er wie folgt aussieht:

private void Button_Click(object sender, RoutedEventArgs e)
{
    var notification = new AppNotificationBuilder()
        .AddArgument("action", "viewConversation")
        .AddArgument("conversationId", "9813")
        .AddText("Andrew sent you a picture")
        .AddText("Check this out, The Enchantments in Washington!")
        .BuildNotification();

    AppNotificationManager.Default.Show(notification);
}

Erstellen und erneut ausführen. Klicken Sie auf die Schaltfläche, und bestätigen Sie, dass eine Toast-Benachrichtigung angezeigt wird. Wenn ein Prozess aufgerufen wird, der zur Laufzeit keine Paketidentität aufweist, lösen die Benachrichtigungs-APIs eine Ausnahme aus.

Ausführen von Code im Hintergrund

Für WPF Apps, die Code ausführen müssen, wenn die App nicht ausgeführt wird, gibt es drei Ansätze, je nach Paket und Workload:

Bei Windows App SDK-Hintergrund-Aufgaben registriert Ihre WPF-App eine COM-Komponente mit BackgroundTaskBuilder, genau wie eine WinUI 3-App – das Ereignis Application.Startup in WPF entspricht der Rolle von App.OnLaunched in WinUI 3. Die vollständige Schritt-für-Schritt-Anleitung finden Sie unter Verwenden von Hintergrundaufgaben in Windows-Apps.

Zugehörige Themen

• Windows Presentation Foundation (WPF)
• Installieren Sie Tools für die Windows App SDK
• Windows App SDK Bereitstellungshandbuch für frameworkabhängige Apps, die entweder mit externem Standort gepackt oder ungepackt sind
• Neueste Downloads für das Windows App SDK
• Vor- und Nachteile des Packens Ihrer App
• Verwenden Sie die Windows App SDK-Laufzeit für Apps, die mit externer Standortoption gepackt oder ungepackt sind
• Laufzeitarchitektur
• Features, für die Paketidentität benötigt wird