Skapa ditt första WinUI 3-projekt (Windows App SDK)

I det här avsnittet får vi se hur du använder Visual Studio för att skapa ett nytt Windows App SDK- projekt för en C# .NET- eller C++-app som har en WinUI 3 användargränssnitt (UI). Vi tar också en titt på en del av koden i det resulterande projektet, vad det gör och hur det fungerar.

Länkar till fullständig installationsinformation finns i stegen nedan. Vi rekommenderar att du installerar och riktar in dig på den senaste stabila versionen av Windows App SDK (se Stable channel release notes).

Tips

Oavsett vilken version av Windows App SDK du väljer att installera och målinrikta (eller vilken version av Visual Studio du använder) är det viktigt att kontrollera eventuella begränsningar och kända problem i releaserapporten för den versionen (se Windows App SDK-versionskanaler). Genom att känna till eventuella begränsningar och kända problem för din version av Windows App SDK kan du kringgå dem om du stöter på någon av dem samtidigt som du följer stegen i det här avsnittet.

Om du stöter på andra problem hittar du förmodligen information om dem i GitHub-problem, eller på fliken Diskussioner, för WindowsAppSDK GitHub-lagringsplatsen. eller via en onlinesökning.

Viktigt!

Om du arbetar med en UWP-app kan du läsa Migrera från UWP till Windows App SDK.

Förpackad, oförpackad och förpackad med extern platsangivelse

Paketering är ett viktigt övervägande för alla Windows App SDK-projekt. Mer information om dina paketeringsalternativ finns i Fördelar och nackdelar med att paketera din app.

Paketerad: Skapa ett nytt projekt för en paketerad C#- eller C++ WinUI 3-skrivbordsapp

1. Information om hur du konfigurerar utvecklingsdatorn finns i Installera verktyg för Windows App SDK.

2. I Visual Studio väljer du File>New>Project.

3. Välj i rullgardinsfiltren i dialogrutan New Project, C# eller C++, Windowsoch WinUI.

4. Välj Tom app, Paketerad (WinUI 3 i Desktop) projektmall och klicka på Nästa. Mallen skapar en skrivbordsapp med ett WinUI 3-baserat användargränssnitt. Det genererade projektet konfigureras med paketmanifestet och annat stöd som behövs för att skapa appen i ett MSIX-paket (se Vad är MSIX?). Mer information om den här projektmallen finns i Package your app using single-project MSIX.

   

5. Ange ett projektnamn, välj andra alternativ efter behov och klicka på Skapa.

   Projektet som Visual Studio genererar innehåller appens kod. App.xaml fil och kod bakom fil(er) definierar en Application-derived-klass som representerar din app som körs. MainWindow.xaml fil och kod bakom fil(er) definierar en MainWindow-klass som representerar huvudfönstret som visas av din app. Dessa klasser härleds från typer i Microsoft.UI.Xaml namnområde som tillhandahålls av WinUI 3.

   Projektet innehåller även paketmanifestet för att skapa appen i ett MSIX-paket.

   

6. Tryck på F5 eller använd menyalternativet Felsökning>Starta felsökning för att skapa och köra lösningen på utvecklingsdatorn och bekräfta att appen körs utan fel.

Tom app-mall skapar en enkel app med ett enda fönster för ditt innehåll. Appar är vanligtvis mer komplexa och du vill lägga till element när appen utvecklas, till exempel nya fönster, sidor eller anpassade användarkontroller. Mer information om tillgängliga objekt och instruktioner för hur du lägger till dem finns i WinUI 3-mallar i Visual Studio.

Oanvänd förpackning: Skapa ett nytt projekt för en oanvänd C# eller C++ WinUI 3-skrivbordsapplikation

Viktigt!

Från och med Windows App SDK 1.0 är standardmetoden för att läsa in Windows App SDK från en app som paketeras med extern plats eller en uppackad app att använda automatisk initiering via <WindowsPackageType> projektegenskap (samt att göra ytterligare konfigurationsändringar). Fortsätt att läsa det här avsnittet för de steg som ingår i automatisk initiering i samband med WinUI 3-projektet. Om du har ett befintligt projekt som inte är WinUI 3 kan du läsa Använda Windows App SDK i ett befintligt projekt.

1. Information om hur du konfigurerar utvecklingsdatorn finns i Installera verktyg för Windows App SDK.

2. Ladda ned och kör den senaste installationsprogrammet för Windows App SDK från Downloads for the Windows App SDK. Då installeras de körningspaketberoenden som krävs för att köra och distribuera en app som paketeras med extern plats eller en uppackad app på målenheten (se Distributionsguide för Windows App SDK för ramverksberoende appar som paketeras med extern plats eller packas upp).

3. C++. Installera Microsoft Visual C++ Redistributable (VCRedist) lämpligt för målenhetens arkitektur.

   • Den senaste versionen av VCRedist är kompatibel med den senaste versionen av Visual Studio allmänt tillgänglig (ga) (dvs. inte förhandsversion) samt alla versioner av Visual Studio som kan användas för att skapa Binärfiler för Windows App SDK.
   • Insiderversioner av Visual Studio kan ha installerat en senare version av VCRedist, och körningen av den offentliga versionen misslyckas sedan med det här felet (som du kan ignorera): Fel 0x80070666: Det går inte att installera en produkt när en nyare version installeras.

   Anmärkning

   Om du inte har VCRedist installerat på målenheten misslyckas dynamiska länkar till c:\windows\system32\vcruntime140.dll. Det felet kan visa sig för slutanvändarna på olika sätt.

4. I Visual Studio väljer du File>New>Project.

5. I rullgardinsfiltrena i dialogrutan för Nytt projekt väljer du C# eller C++, Windowsrespektive WinUI.

6. Du måste börja med ett paketerat projekt för att kunna använda XAML-diagnostik. Välj Tom app, Paketerad (WinUI 3 i Desktop) projektmall och klicka på Nästa.

   Viktigt!

   Kontrollera att projektet som du nyss skapade riktar sig mot den version av Windows App SDK som du installerade med installationsprogrammet i steg 2. För att göra det i Visual Studio klickar du på Verktyg>NuGet Package Manager>Hantera NuGet-paket för lösningen...>Uppdateringar. Och vid behov uppdatera referensen till Microsoft.WindowsAppSDK NuGet-paketet. Du kan se vilken version som är installerad på fliken Installerat.

7. Lägg till följande egenskap i projektfilen – antingen din .csproj (C#) eller .vcxproj -fil (C++). Placera den i elementet PropertyGroup som redan finns där (för C++har elementet Label="Globals"):

   <Project ...>
     ...
     <PropertyGroup>
       ...
       <WindowsPackageType>None</WindowsPackageType>
       ...
     </PropertyGroup> 
     ...
   </Project>
   

8. C++. I C++-projektfilen (.vcxproj) i PropertyGroup--elementet som redan finns där anger du egenskapen AppxPackage till false:

   <Project ...>
     ...
     <PropertyGroup Label="Globals">
       ...
       <AppxPackage>false</AppxPackage>
       ...
     </PropertyGroup> 
     ...
   </Project>
   

9. C#. Om du vill starta en C#-app från Visual Studio (antingen Felsöka eller Utan att Felsöka) väljer du startprofilen Oinstallerad från Start-listrutan. Om profilen Package har valts visas ett distributionsfel i Visual Studio. Det här steget är inte nödvändigt om du startar programmet (.exe) från kommandoraden eller från Utforskaren i Windows.

   

10. Bygg och kör.

Bootstrapper-API:et

Genom att ange <WindowsPackageType>None</WindowsPackageType> projektegenskap får autoinitialisator att hitta och läsa in en version av Windows App SDK som passar bäst för din app.

Om du har avancerade behov (till exempel anpassad felhantering eller för att läsa in en specifik version av Windows App SDK) kan du i stället anropa bootstrapper-API:et explicit. För mer information, se Använd Windows App SDK-körning för appar som paketeras med extern plats eller inte packasoch Handledning: Använd bootstrapper-API:et i en app som paketeras med extern plats eller inte packas och som använder Windows App SDK.

Mer information om bootstrapper finns i Distributionsarkitektur och översikt för ramverksberoende appar.

En titt på koden i projektmallen

I den här genomgången använde vi projektmallen Tom App-paket (WinUI 3 i Desktop), som skapar en skrivbordsapp med ett WinUI 3-baserat användargränssnitt. Låt oss ta en titt på en del av koden som medföljer mallen och vad den gör. Mer information om tillgängliga WinUI 3-projekt- och objektmallar finns i WinUI 3-mallar i Visual Studio.

Appens startpunkt

När Windows-operativsystemet (OS) kör en app börjar operativsystemet köras i appens startpunkt. Den startpunkten har formen av en Main (eller wWinMain för C++/WinRT) funktion. Normalt konfigurerar ett nytt projekt den funktionen så att den genereras automatiskt av Visual Studio-byggprocessen. Och det är dolt som standard, så du behöver inte bry dig om det. Men om du är nyfiken på mer information kan du se Single-instancing i Main eller wWinMain.

Appklassen

Appen som helhet representeras av en klass som vanligtvis kallas helt enkelt App. Den här klassen definieras i App.xaml- och i dess bakomliggande filer (App.xaml.cs, eller App.xaml.h och .cpp). App härleds från klassen WinUI 3 Microsoft.UI.Xaml.Application.

Den genererade koden i startpunkten skapar en instans av Appoch sätter igång den.

I konstruktorn för App kommer du att se metoden InitializeComponent som anropas. Den metoden parsar i princip innehållet i App.xaml, som är XAML-markering. Och det är viktigt eftersom App.xaml innehåller sammanfogade resurser som måste lösas och läsas in i ett uppslagsverk för den körande appen.

En annan intressant metod för App är OnLaunched. Där skapar och aktiverar vi en ny instans av klassen MainWindow (som vi ska titta på härnäst).

Klassen MainWindow

Huvudfönstret som visas av appen representeras naturligtvis av klassen MainWindow. Den här klassen definieras i MainWindow.xaml och i dess kod bakom fil(er) (MainWindow.xaml.cs, eller MainWindow.xaml.h och .cpp). MainWindow härleds från klassen WinUI 3 Microsoft.UI.Xaml.Window.

Konstruktorn för MainWindow anropar sin egen InitializeComponent-metod. Återigen är dess jobb att omvandla XAML-markering inuti MainWindow.xaml till ett diagram över användargränssnittsobjekt (UI).

I MainWindow.xaml ser du den grundläggande layouten för MainWindow. I layoutroten finns en dynamisk panel som kallas Microsoft.UI.Xaml.Controls.StackPanel. Mer information om layoutpaneler finns i Layoutpaneler.

Inuti den StackPanel finns det en Microsoft.UI.Xaml.Controls.Button. Och att Button använder markering Click="myButton_Click" för att deklarativt ansluta en händelsehanterarmetod för händelsen Klick.

Metoden heter myButton_Clickoch du hittar implementeringen av metoden i MainWindow.xaml.cseller i MainWindow.xaml.cpp. I den ändras innehållet i knappen från standardvärdet "Klicka på mig" till "Klickade".

C++. Om du har skapat ett C++-projekt visas även en MainWindow.idl fil. Mer information finns i dokumentationen C++/WinRT. XAML-kontroller; bind till en C++/WinRT-egenskap är ett bra ställe att börja lära dig om syftet med och användningen av .idl filer.

Nästa steg

Det här avsnittet visade hur du skapar ett Visual Studio-projekt för en paketerad eller uppackad app. Ett exempel på hur du lägger till funktioner i en sådan app finns i Självstudie: Skapa ett enkelt fotovisningsprogram med WinUI 3. Det ämnet går igenom processen med att skapa en enkel app för att visa foton.

Om du vill fortsätta utvecklingsresan med Windows App SDK kan du läsa Utveckla Windows-skrivbordsappar.

Relaterade ämnen

• WinUI 3
• Windows App SDK-utgivningskanaler
• Installera verktyg för Windows App SDK
• Vad är MSIX?
• Paketera din app med MSIX som ett enskilt projekt
• WinUI 3-projektmallar i Visual Studio
• Distribueringsguide för Windows App SDK för appar beroende av ramverk som paketeras på en extern plats eller är opaketerade
• Microsoft Visual C++ Redistributable (VCRedist)
• Använd Windows App SDK-körmiljö för appar som paketeras med extern platsangivelse eller är opackerade
• Distributionsarkitektur för Windows App SDK
• Självstudie: Använd bootstrapper-API:t i en app som antingen paketeras med en extern plats eller är opaketerad och använder Windows App SDK
• Utveckla Windows-skrivbordsappar