Verwenden des Windows App SDK in einer Windows Forms -App (WinForms)

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 Forms (WinForms)-App verwenden können!

• In vielen Fällen möchten Sie Ihre WinForms-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 WinForms-App zu WinUI nicht behandelt.
• Wenn Sie jedoch feststellen, dass Sie Features von WinForms 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 WinForms-App verwenden. In diesem Thema wird gezeigt, wie es geht.

Und falls Sie noch nicht über eine WinForms-project verfügen oder den Prozess üben möchten, enthält dieses Thema Schritte zum Erstellen einer WinForms-project, damit Sie diese ausführen 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 gepackte WinForms-Apps behandelt. Wenn Ihre WinForms-App entpackt ist (was bei WinForms-Apps standardmäßig der Fall ist), 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 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 WinForms-Projekt, falls Sie noch keines haben.

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

1. Erstellen Sie in Visual Studio eine neue C#-Windows Forms App project (ein .NET project). Achten Sie darauf, dass Sie die project Vorlage mit dem genauen Namen Windows Forms App und nicht der Windows Forms 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 WinForms-App erstellt.

Konfigurieren Sie Ihr WinForms-Projekt für 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 innerhalb des PropertyGroup-Elements ein RuntimeIdentifiers-Element hinzu, wie folgt:

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

4. Standardmäßig wird eine WinForms-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 WinForms-App

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

1. Öffnen Sie Form1.cs (mit dem Befehl Ansichts-Designer), und ziehen Sie eine Schaltfläche und eine Beschriftung aus der Toolbox und in den Designer.

2. Doppelklicken Sie auf button1, um einen Ereignishandler zu generieren.

3. 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. Öffnen Sie Form1.cs (mit dem Befehl Code anzeigen), und bearbeiten Sie den Ereignishandler so, dass er wie folgt aussieht:

   private void button1_Click(object sender, EventArgs 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.
       label1.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
   }
   

4. 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.

Verpacken und Bereitstellen Ihrer WinForms-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 im Verpackungsprojekt (nicht im WinForms-Projekt) 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 WinForms-Projekt aus, und klicken Sie auf OK.
6. Erweitern Sie den Knoten Dependencies>Applications des Verpackungsprojekts, und vergewissern Sie sich, dass auf Ihr WinForms-Projekt verwiesen und es fett hervorgehoben wird. 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 WinForms-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 WinForms-App gepackt haben, können Sie APIs aufrufen, die eine Paketidentität erfordern. Öffnen Sie daher Form1.cs (mit dem Befehl Code anzeigen), und bearbeiten Sie den Ereignishandler so, dass er wie folgt aussieht:

private void button1_Click(object sender, EventArgs 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 Forms (WinForms)
• 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