Erstellen Ihres ersten WinUI 3-Projekts (Windows App SDK) - Windows apps (2023)

In diesem Thema erfahren Sie, wie Sie Visual Studio verwenden, um ein neues Projekt für ein neuesWindows-App-SDKfür eine C# .NET- oder C++-App zu erstellen, die über eineWindows-UI-Bibliothek (WinUI) 3-Benutzeroberfläche (UI) verfügt. Wir sehen uns auch einen Teil des Codes im resultierenden Projekt an, was dieser bewirkt und wie er funktioniert.

Links zu vollständigen Installationsdetails finden Sie in den folgenden Schritten. Es wird empfohlen, die neueste Stable-Version des Windows App SDK zu installieren und darauf abzuzielen (sieheAnmerkungen zur Version des Stable-Kanals).

Gepackt, nicht gepackt und gepackt mit externem Speicherort

Paketerstellungen sind ein wichtiger Aspekt eines Windows App SDK-Projekts. Weitere Informationen zu Ihren Packoptionen finden Sie unterVorteile und Nachteile des Verpackens Ihrer App.

Gepackt: Erstellen eines neuen Projekts für eine gepackte C#- oder C++-WinUI 3-Desktop-App

1. Informationen zum Einrichten Ihres Entwicklungscomputers finden Sie unterInstallieren von Tools für das Windows App SDK.

2. Klicken Sie in Visual Studio aufDatei>Neu>Projekt.

3. Wählen Sie in den Dropdownfiltern für das DialogfeldNeues Projektdie OptionC#/C++,Windowsbzw.WinUIaus.

4. Wählen Sie die ProjektvorlageLeere App, Gepackt (WinUI3 in Desktop)aus, und klicken Sie aufWeiter. Diese Vorlage erstellt eine Desktop-App mit einer WinUI 3-basierten Benutzeroberfläche. Das generierte Projekt wird mit dem Paketmanifest und anderer Unterstützung konfiguriert, die erforderlich ist, um die App als MSIX-Paket zu erstellen (sieheWas ist MSIX?). Weitere Informationen zu dieser Projektvorlage finden Sie unterPacken Ihrer App mithilfe von MSIX für einzelne Projekte.

5. Gib einen Projektnamen ein, wähle alle anderen Optionen wie gewünscht aus, und klicke aufErstellen.

6. Das Projekt, das Visual Studio generiert, enthält den Code Ihrer App. Die DateiApp.xamlund die CodeBehind-Datei(en) definieren eine vonAnwendungabgeleitete Klasse, die Ihre ausgeführte App darstellt. Die DateiMainWindow.xamlund die CodeBehind-Datei(en) definieren eineHauptfenster-Klasse, die das von Ihrer App angezeigte Hauptfenster darstellt. Diese Klassen leiten sich von Typen im NamespaceMicrosoft.UI.Xamlab, der von WinUI3 bereitgestellt wird.

   Das Projekt enthält auch das Paketmanifest zum Erstellen der App in einMSIX-Paket.

   

7. Um Ihrer App ein neues Element hinzuzufügen, klicken Sie imProjektordner-Explorermit der rechten Maustaste auf den Projektknoten, und wählen SieHinzufügen>Neues Elementaus. Wähle im DialogfeldNeues Element hinzufügendie RegisterkarteWinUIaus. Wähle das Element, das du hinzufügen möchtest, und klicke dann aufHinzufügen. Weitere Informationen zu den verfügbaren Elementen finden Sie unterWinUI 3-Vorlagen in Visual Studio.

   

8. Sie müssen Ihre Projektmappe auf Ihrem Computer erstellen und ausführen, um zu überprüfen, ob die App fehlerfrei ausgeführt wird.

Nicht gepackt: Erstellen eines neuen Projekts für eine nicht gepackte C#- oder C++-WinUI 3-Desktop-App

1. Informationen zum Einrichten Ihres Entwicklungscomputers finden Sie unterInstallieren von Tools für das Windows App SDK.

2. Laden Sie unterDownloads für das Windows AppSDKdas neuesteInstallationsprogrammfür das Windows AppSDK herunter, und führen Sie es aus. Dadurch werden die Runtimepaketabhängigkeiten installiert, die erforderlich sind, um eine mit externem Speicherort gepackte App oder eine nicht gepackte App auf dem Zielgerät auszuführen und bereitzustellen. (Weitere Informationen finden Sie imWindowsAppSDK-Bereitstellungsleitfaden für frameworkabhängige gepackte Apps mit externem Speicherort oder nicht gepackte Apps.)

3. C++. Installieren SieMicrosoft Visual C++ Redistributable (VCRedist)für die Architektur des jeweiligen Zielgeräts.

   • Die neueste Version von VCRedist ist mit dem neuesten allgemein verfügbaren Release (GA) von Visual Studio (also nicht der Vorschauversion) sowie mit allen Versionen von Visual Studio kompatibel, die zum Erstellen von Windows App SDK-Binärdateien verwendet werden können.
   • Bei Insider-Builds von Visual Studio ist möglicherweise eine neuere Version von VCRedist installiert, und die Ausführung der öffentlichen Version schlägt dann mit diesem Fehler fehl, der ignoriert werden kann:Fehler 0x80070666: Ein Produkt kann nicht installiert werden, wenn eine neuere Version installiert ist.

   Hinweis

   Wenn VCRedist nicht auf dem Zielgerät installiert ist, tritt bei dynamischen Links zuc:\windows\system32\vcruntime140.dllein Fehler auf. Dieser Fehler kann sich für Endbenutzer auf verschiedene Weise manifestieren.

4. Klicken Sie in Visual Studio aufDatei>Neu>Projekt.

5. Wählen Sie in den Dropdownfiltern für das Dialogfeld „Neues Projekt“C#/C++,Windowsbzw.WinUIaus.

6. Sie müssen mit einem gepackten Projekt beginnen, um die XAML-Diagnose verwenden zu können. Wählen Sie daher die ProjektvorlageLeere App, Gepackt (WinUI3 in Desktop)aus, und klicken Sie aufWeiter.

   Wichtig

   Stellen Sie sicher, dass das soeben erstellte Projekt auf die Version des Windows AppSDK ausgerichtet ist, die Sie in Schritt2 mithilfe desInstallationsprogrammsinstalliert haben. Klicken Sie dazu in Visual Studio aufWerkzeug>NuGet-Paket-Manager>NuGet-Pakete für Projektmappe verwalten...>Aktualisierung. Aktualisieren Sie ggf. den Verweis auf das NuGet-PaketMicrosoft.WindowsAppSDK. Die installierte Version wird auf der RegisterkarteInstalliertangezeigt.

7. Fügen Sie Ihrer Projektdatei die folgende Eigenschaft hinzu – entweder Ihre.csproj(C#)- oder.vcxproj(C++)-Datei. Fügen Sie es in das bereits vorhandenePropertyGroup-Element ein (für C++ hat das ElementLabel="Globale"):

    ...  ... None ...  ...

8. C++. Setzen Sie in Ihrer C++-Projektdatei (.vcxproj) innerhalb des bereits vorhandenenPropertyGroup-Elements die EigenschaftAppxPackageaufFALSCH:

    ...  ... false ...  ...

9. C#. Um eine C#-App über Visual Studio (DebuggenoderOhne Debuggen) zu starten, wählen Sie in der DropdownlisteStartdas StartprofilNicht gepacktaus. Wenn das ProfilPaketausgewählt ist, wird in Visual Studio ein Bereitstellungsfehler angezeigt. Dieser Schritt ist nicht erforderlich, wenn Sie die Anwendung (.exe) über die Befehlszeile oder den Windows Datei-Explorer starten.

   

10. Erstellen Sie das Modell dann, und führen Sie es aus.

Die Bootstrapper-API

Das Festlegen derNone-Projekteigenschaft bewirkt, dass derautomatische Initialisierereine Version des Windows App SDK sucht und lädt, die für Ihre App am besten geeignet ist.

Wenn Sie komplexere Anforderungen haben (z.B. benutzerdefinierte Fehlerbehandlung oder das Laden einer bestimmten Version des Windows App SDK), können Sie stattdessen die Bootstrapper-API explizit aufrufen. Weitere Informationen finden Sie unterVerwenden der Windows App SDK-Runtime für gepackte Apps mit externem Speicherort oder nicht gepackte Appssowie unterTutorial: Verwenden der Bootstrapping-API in einer gepackten App mit externem Speicherort oder nicht gepackten App, die Windows AppSDK verwendet.

Weitere Informationen zum Bootstrapper finden Sie unterBereitstellungsarchitektur und Übersicht für frameworkabhängige Apps.

Ein Blick auf den Code in der Projektvorlage

In dieser exemplarischen Vorgehensweise haben wir die ProjektvorlageLeere App, Gepackt (WinUI 3 in Desktop)verwendet, die eine Desktop-App mit einer WinUI 3-basierten Benutzeroberfläche erstellt. Sehen wir uns einen Teil des Codes in dieser Vorlage an, und was er bewirkt. Weitere Informationen zu den verfügbaren WinUI3-Projekt- und -Elementvorlagen finden Sie unterWinUI 3-Vorlagen in Visual Studio.

Einstiegspunkt der App

Wenn das Windows-Betriebssystem eine App ausführt, beginnt das Betriebssystem mit der Ausführung amEinstiegspunktder App. Dieser Einstiegspunkt hat die Form einerHauptsächlich-Funktion (bzw. für C++/WinRT einerwWinMain-Funktion). Normalerweise konfiguriert ein neues Projekt diese Funktion so, dass sie vom Visual Studio-Buildprozess automatisch generiert wird. Und sie ist standardmäßig ausgeblendet, sodass Sie sich nicht darum kümmern müssen. Wenn Sie jedochweitere Informationen wünschen, finden Sie diese unterEinmalige Instanziierung in „Main“ oder „wWinMain“.

Die App-Klasse

Die App als Ganzes wird durch eine Klasse dargestellt, die in der Regel einfach alsAppbezeichnet wird. Diese Klasse wird inApp.xamlund den entsprechenden CodeBehind-Dateien (App.xaml.cs, oderApp.xaml.hund.cpp) definiert.Appwird von der WinUI 3-KlasseMicrosoft.UI.Xaml.Applicationabgeleitet.

Der generierte Code im Einstiegspunkt erstellt eine Instanz vonAppund legt die Ausführung fest.

Im Konstruktor vonAppsehen Sie, dass dieInitialisieren der Komponente-Methode aufgerufen wird. Diese Methode analysiert im Wesentlichen den Inhalt vonApp.xaml, bei dem es sich um XAML-Markup handelt. Dies ist wichtig, daApp.xamlzusammengeführte Ressourcen enthält, die aufgelöst und in ein Wörterbuch geladen werden müssen, um von der ausgeführten App verwendet werden zu können.

Eine weitere interessante Methode vonAppistOnLaunched. Dort wird eine neue Instanz derHauptfenster-Klasse erstellt und aktiviert (die wir uns als Nächstes anschauen werden).

Die MainWindow-Klasse

Das von der App angezeigte Hauptfenster wird natürlich durch dieHauptfenster-Klasse dargestellt. Diese Klasse wird inMainWindow.xamlund den entsprechenden CodeBehind-Dateien (MainWindow.xaml.cs, oderMainWindow.xaml.hund.cpp) definiert.Hauptfensterwird von der WinUI 3-KlasseMicrosoft.UI.Xaml.Windowabgeleitet.

Der Konstruktor vonHauptfensterruft seine eigeneInitialisieren der Komponente-Methode auf. Auch hier besteht die Aufgabe darin, das XAML-Markup inMainWindow.xamlin ein Diagramm von Benutzeroberflächenobjekten (UI) umzuwandeln.

InMainWindow.xamlsehen Sie das grundlegende Layout vonHauptfenster. Im Layoutstamm befindet sich ein dynamischer Bereich namensMicrosoft.UI.Xaml.Controls.StackPanel. Weitere Informationen zu Layoutbereichen finden Sie unterLayoutbereiche.

In diesemStackPanel-Element befindet sich einMicrosoft.UI.Xaml.Controls.Button-Objekt. Und diesesTaste-Objekt verwendet das MarkupClick="myButton_Click", um deklarativ eine Ereignishandlermethode für dasKlicken-Ereignis anzukoppeln.

Diese Methode wirdmyButton_Clickgenannt, und Sie finden die Implementierung dieser Methode inMainWindow.xaml.csoderMainWindow.xaml.cpp. Darin wird der Inhalt der Schaltfläche von der Standardeinstellung „Click Me“ (Klicken) in „Clicked“ (Geklickt) geändert.

C++. Wenn Sie ein C++-Projekt erstellt haben, wird auch eineMainWindow.idl-Datei angezeigt. Weitere Informationen finden Sie in derC++/WinRT- Dokumentation.XAML-Steuerelemente; an eine C++/WinRT-Eigenschaft bindenist ein guter Ausgangspunkt, um sich mit dem Zweck und der Verwendung von.idl-Dateien vertraut zu machen.

Nächste Schritte

In diesem Thema wurde gezeigt, wie Sie ein Visual Studio-Projekt für eine gepackte oder eine nicht gepackte App erstellen. Ein Beispiel für das Hinzufügen von Funktionen zu einer solchen App finden Sie unterTutorial: Erstellen einer einfachen Fotoanzeige mit WinUI 3 (C#). Dieses Thema führt Sie durch den Prozess der Erstellung einer einfachen App zum Anzeigen von Fotos.

Informationen zum Fortsetzen Ihrer Entwicklungsreise mit dem Windows App SDK finden Sie unterEntwickeln von Windows Desktop-Apps.

• Windows-UI-Bibliothek (WinUI)3
• Windows App SDK-Releasekanäle
• Installieren von Tools für das Windows App SDK
• Was ist MSIX?
• Verpacken Ihrer App mithilfe von MSIX mit nur einem Projekt
• WinUI3-Projektvorlagen in Visual Studio
• Windows App SDK-Bereitstellungsleitfaden für frameworkabhängige gepackte Apps mit externem Speicherort oder nicht gepackte Apps
• Microsoft Visual C++ Redistributable (VCRedist)
• Verwenden der Windows App SDK-Runtime für gepackte Apps mit externem Speicherort oder nicht gepackte Apps
• Bereitstellungsarchitektur für das Windows App SDK
• Tutorial: Verwenden der Bootstrapping-API in einer gepackten App mit externem Speicherort oder nicht gepackten App, die Windows App SDK verwendet
• Entwickeln von Windows-Desktop-Apps