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. Nur einer der Vorteile des Wechsels zu WinUI besteht darin, Zugriff auf das Fluent Design System zu haben (siehe auch Windows-Anwendungen entwerfen und programmieren). 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 eine WPF project verfügen oder den Prozess üben möchten, enthält dieses Thema Schritte zum Erstellen einer WPF project, sodass Sie sie 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 bei WPF-Apps standardmäßig der Fall ist), stellen Sie sicher, dass alle Abhängigkeiten für entpackte Apps installiert sind (siehe Windows App SDK Leitfaden für die Bereitstellung von frameworkabhängigen Apps, die mit externem Speicherort gepackt oder entpackt sind). Eine schnelle Möglichkeit dazu ist es, die neuesten Downloads für das Windows App SDK zu besuchen, dann eine der stabilen Release-Runtime-Downloads herunterzuladen, zu entpacken und auszuführen.

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

Erstellen Sie ein WPF-Projekt, falls Sie noch keines haben

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

1. Erstellen Sie in Visual Studio ein neues C#-WPF Application project (ein .NET project). Achten Sie darauf, dass Sie die project Vorlage mit dem exakten 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 unverpackte WPF-App erstellt.

Konfigurieren Sie Ihr WPF-Projekt für die Windows App SDK-Unterstützung.

Zuerst bearbeiten wir die project Datei.

1. Klicken Sie in Solution 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 das Laden einer bestimmten Version des Windows App SDK), können Sie die Bootstrapper-API explizit aufrufen, anstatt sich auf die Auto-Initialisierung zu verlassen – weitere Informationen finden Sie unter Die Windows App SDK-Laufzeit für Apps mit externem Speicherort oder ohne Verpackung verwenden.

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

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

6. Klicken Sie in Solution Explorer mit der rechten Maustaste auf den Knoten Dependencies Ihres project, und wählen Sie Manage Nuget Packages... .
7. Wählen Sie im Fenster NuGet Package Manager die Registerkarte Durchsuchen aus, und installieren Sie das neueste stabile Microsoft.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 Projekt erstellt haben, wird es das), können Sie die folgenden 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 Solution Explorer in Visual Studio mit der rechten Maustaste auf die Lösung, und wählen Sie Add>Neue Project... .
2. Im Dialogfeld Neues Projekt hinzufügen suchen Sie nach Packaging, wählen Sie die C# Windows Application Packaging Project Projektvorlage 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 Verpackungsprojekt (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 Lösung Ihr WPF-Projekt aus, und klicken Sie auf OK.
6. Erweitern Sie den Knoten Dependencies>Applications des Verpackungsprojekts, und vergewissern Sie sich, dass Ihr WPF-Projekt referenziert und fett 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 Als Startprojekt festlegen 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.

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 mit einem externen Speicherort verpackt oder entpackt sind
• Aktuelle Downloads für das Windows App SDK
• Vor- und Nachteile des Packens Ihrer App
• Verwenden Sie das Windows App SDK-Laufzeitmodul für Apps, die mit einem externen Speicherort gepackt oder nicht gepackt wurden
• Laufzeitarchitektur
• Features, für die Paketidentität benötigt wird