Freigeben über

Verwenden des Windows App SDK in einer WPF-App

  • Artikel

Das 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 WPF-App (Windows Presentation Foundation) verwenden können!

  • In vielen Fällen möchten Sie Ihre WFP-App in Form einer WinUI 3-App neu erstellen. Nur einer der Vorteile der Umstellung auf WinUI 3 besteht darin, Zugriff auf das Fluent Design System zu haben (siehe auch Entwerfen und Codieren von Windows-Apps). Und WinUI 3 ist Teil des Windows App SDK – natürlich kann eine WinUI 3-App auch die anderen Windows App SDK-Features und APIs verwenden. In diesem Thema wird der Prozess der Migration Ihrer WPF-App zu WinUI 3 nicht behandelt.
  • Wenn Sie jedoch feststellen, dass Sie Features von WPF verwenden, die noch nicht in WinUI 3 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 die Vorgehensweise gezeigt.

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 von Tools für das Windows App SDK.
  2. In diesem Thema werden sowohl entpackte als auch gepackte 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 werden (siehe Windows App SDK-Bereitstellungsleitfaden für frameworkabhängige gepackte Apps mit externem Speicherort oder nicht gepackte Apps). Eine schnelle Möglichkeit, dies zu tun, besteht darin, Neueste Downloads für das Windows App SDK aufzurufen, dann einen der stabilen Runtime-Downloads des Release herunterzuladen, zu entpacken und auszuführen.

Wichtig

Die Version der von Ihnen installierten Runtime muss mit der Version des Microsoft.WindowsAppSDK-NuGet-Pakets übereinstimmen, das Sie in einem späteren Schritt installieren.

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

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

Wenn Sie bereits über ein WPF-Projekt verfügen, können Sie mit dem nächsten Abschnitt fortfahren.

  1. Erstellen Sie in Visual Studio ein neues C#-Projekt unter Verwendung des Projekts WPF-Anwendung (wobei es sich um ein .NET-Projekt handelt). Achten Sie darauf, dass Sie die Projektvorlage mit dem exakten Namen WPF-Anwendung und nicht die WPF-App (.NET Framework) auswählen.
  2. Geben Sie dem Projekt einen Namen, und akzeptieren Sie alle Standardoptionen.

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

Konfigurieren des WPF-Projekts für die Unterstützung des Windows App SDK

Zuerst bearbeiten wir die Projektdatei.

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihr Projekt, und wählen Sie Projektdatei bearbeiten aus.

  2. In diesem Schritt können Sie Windows Runtime-APIs (WinRT) (einschließlich Windows App SDK-APIs) aufrufen. 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 Zielframeworkmoniker). Verwenden Sie beispielsweise Folgendes, wenn Ihre App auf Windows 10, Version 2004 ausgerichtet ist:

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

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

    <RuntimeIdentifiers>win10-x86;win10-x64;win10-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 WindowsPackageType-Projekteigenschaft wie folgt fest:

    <WindowsPackageType>None</WindowsPackageType>

    Wenn Sie erweiterte Anforderungen haben (z. B. die benutzerdefinierte Fehlerbehandlung oder das Laden einer bestimmten Version des Windows App SDK), können Sie anstelle der automatischen Initialisierung die Bootstrapper-API explizit aufrufen – weitere Informationen finden Sie unter Verwenden der Windows App SDK-Runtime für gepackte Apps mit externem Speicherort oder nicht gepackte Apps.

  5. Speichere und schließe die Projektdatei.

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

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Abhängigkeiten Ihres Projekts, und wählen Sie Verwalten von NuGet-Paketen... aus.
  2. Wählen Sie im Fenster "NuGet Paket-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 von 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, ist dies der Fall), können Sie diese Schritte ausführen.

  1. Fügen Sie das folgende Markup hinzu MainWindow.xaml (Sie könnten es in das Stammraster 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 ResourceManager-Klasse im Windows App SDK zum Laden einer Zeichenfolgenressource verwendet.

    1. Fügen Sie Ihrem Projekt ein neues Ressourcendateielement (.resw) hinzu (behalten Sie den Standardnamen Resources.resw bei).

    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.

Tipp

Wenn Sie zur Laufzeit ein Meldungsfeld sehen, das darauf hinweist, dass die Anwendung eine bestimmte Version von Windows App Runtime benötigt, und Sie fragt, ob Sie diese jetzt installieren möchten, klicken Sie auf Ja. Dadurch gelangen Sie zu Neueste Downloads für das Windows App SDK. Weitere Informationen finden Sie im Abschnitt Voraussetzungen oben.

Sehen Sie sich auch die Laufzeitarchitektur an, um mehr über die Framework-Paketabhängigkeit zu erfahren, die Ihre App benötigt, wenn sie das Windows App SDK verwendet, und über die zusätzlichen Komponenten, die für die Arbeit in einer entpackten App erforderlich sind.

Verpacken und Bereitstellen Ihrer WPF-App mit MSIX

Einige Windows-Features und APIs (einschließlich der Windows App SDK-Benachrichtigungs-APIs) erfordern, dass Ihre App zur Laufzeit eine Paketentität aufweist (d. h. Ihre App muss verpackt werden). Weitere Informationen finden Sie unter Features, für die Paketidentität benötigt wird.

  1. Klicken Sie im Projektmappen-Explorer in Visual Studio mit der rechten Maustaste auf die Lösung, und wählen Sie Hinzufügen>Neues Projekt... aus.
  2. Suchen Sie im Dialogfeld Neues Projekt hinzufügen nach Packen, wählen Sie die C#-Projektvorlage Paketerstellungsprojekt für Windows-Anwendungen aus, und klicken Sie auf Weiter.
  3. Geben Sie dem Projekt einen Namen, und klicken Sie auf Erstellen.
  4. Wir möchten angeben, welche Anwendungen in der Lösung in das Paket aufgenommen werden sollen. Klicken Sie daher im Paketprojekt (nicht im WPF-Projekt) mit der rechten Maustaste auf den Knoten Abhängigkeiten, und wählen Sie Projektreferenz hinzufügen... aus.
  5. Wählen Sie in der Liste der Projekte in der Lösung das WPF-Projekt aus, und klicken Sie auf OK.
  6. Erweitern Sie den Knoten Abhängigkeiten>Anwendungen, und bestätigen Sie, 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 Paketerstellungsprojekt, 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ösungsplattformen x64 (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 Sie es, und führen Sie es erneut aus. Klicken Sie auf die Schaltfläche, und bestätigen Sie, dass eine Popupbenachrichtigung angezeigt wird. Wenn ein Prozess aufgerufen wird, der zur Laufzeit keine Paketidentität aufweist, lösen die Benachrichtigungs-APIs eine Ausnahme aus.

Hinweis

In den Schritten in diesem Abschnitt wurde gezeigt, wie Sie eine gepackte App erstellen. Eine Alternative besteht darin, eine gepackte App mit externem Speicherort zu erstellen. Eine Erinnerung an all diese Begriffe finden Sie unter Vor- und Nachteile des Verpackens Ihrer App.