Delen via

Uw eerste WinUI 3-project (Windows App SDK) maken

  • Artikel

In dit onderwerp ziet u hoe u Visual Studio gebruikt om een nieuw Windows App SDK-project te maken voor een C# .NET- of C++-app met een WinUI 3-gebruikersinterface (UI). We bekijken ook enkele code in het resulterende project, wat het doet en hoe het werkt.

Koppelingen naar volledige installatiedetails vindt u in de onderstaande stappen. U wordt aangeraden de nieuwste Stabiele release van de Windows App SDK te installeren en te richten (zie releaseopmerkingen voor stabiele kanalen).

Hint

Ongeacht welke versie van de Windows App SDK u kiest om te installeren en te targeten (of welke versie van Visual Studio u gebruikt), is het belangrijk om eventuele beperkingen en bekende problemen in de releaseopmerkingen voor die versie te controleren (zie releasekanalen voor Windows App SDK). Als u op de hoogte bent van eventuele beperkingen en bekende problemen voor uw versie van de Windows App SDK, kunt u deze omzeilen als u ze tegenkomt terwijl u de stappen in dit onderwerp volgt.

Als u andere problemen ondervindt, vindt u waarschijnlijk informatie over deze problemen in GitHub, of op het tabblad Discussies, van de GitHub-opslagplaats WindowsAppSDK ; of via een online zoekopdracht.

Belangrijk

Als u aan een UWP-app werkt, raadpleegt u Migreren van UWP naar de Windows App SDK-.

Verpakt, uitgepakt en verpakt met externe locatie

Verpakking is een belangrijke overweging van elk Windows App SDK-project. Zie Voor meer informatie over uw verpakkingsopties voordelen en nadelen van het verpakken van uw app.

Verpakt: Maak een nieuw project voor een verpakte C# of C++ WinUI 3-bureaublad-app

  1. Om uw ontwikkelcomputer in te stellen, zie Hulpprogramma's installeren voor de Windows App SDK.

  2. Selecteer in Visual Studio Bestand>Nieuw>Project.

  3. Selecteer in de vervolgkeuzelijsten van het dialoogvenster Nieuw projectrespectievelijk C# of C++, Windows en WinUI.

  4. Selecteer de Lege app, verpakte (WinUI 3 op desktop) projectsjabloon en klik op Volgende. Met deze sjabloon maakt u een bureaublad-app met een gebruikersinterface op basis van WinUI 3. Het gegenereerde project wordt geconfigureerd met het pakketmanifest en andere ondersteuning die nodig is om de app in te bouwen in een MSIX-pakket (zie Wat is MSIX?). Zie Uw app verpakken met MSIX voor één projectvoor meer informatie over deze projectsjabloon.

    Screenshot van de wizard

  5. Voer een projectnaam in, kies desgewenst andere opties en klik op maken.

    Het project dat Visual Studio genereert, bevat de code van uw app. Het App.xaml-bestand en code-behind-bestand(en) definiëren een door toepassing afgeleide klasse die uw actieve app vertegenwoordigt. Het bestand MainWindow.xaml en code-behind-bestand(en) definiëren een MainWindow-klasse die het hoofdvenster vertegenwoordigt dat door uw app wordt weergegeven. Deze klassen zijn afgeleid van typen in de Microsoft.UI.Xaml-naamruimte die wordt geleverd door WinUI 3.

    Het project bevat ook het pakketmanifest voor het bouwen van de app in een MSIX-pakket.

    Schermopname van Visual Studio met het deelvenster Solution Explorer en de inhoud van het bestand Main Windows X A M L dot C S voor één project M S I X.

  6. Druk op F5 of gebruik de menuoptie Foutopsporing> starten om uw oplossing op uw ontwikkelcomputer te bouwen en uit te voeren en te controleren of de app zonder fouten wordt uitgevoerd.

Met de sjabloon Lege app maakt u een eenvoudige app met één venster voor uw inhoud. Apps zijn doorgaans complexer en u wilt elementen toevoegen terwijl uw app vordert, zoals nieuwe vensters, pagina's of aangepaste gebruikersbesturingselementen. Zie WinUI 3-sjablonen in Visual Studio voor meer informatie over de beschikbare items en instructies voor het toevoegen ervan.

Schermopname van het dialoogvenster Nieuw item toevoegen met de optie Geïnstalleerde > Visual C# Items > WinUI geselecteerd en de optie Lege pagina gemarkeerd.

Uitgepakt: Maak een nieuw project voor een uitgepakte C# of C++ WinUI 3-bureaublad-app

Belangrijk

Vanaf de Windows App SDK 1.0 is de standaardbenadering voor het laden van de Windows App SDK vanuit een app die is verpakt met een externe locatie of een uitgepakte app, het gebruik van automatische initialisatie via de <WindowsPackageType> projecteigenschap (en het aanbrengen van aanvullende configuratiewijzigingen). Lees deze sectie verder voor de stappen voor automatische initialisatie in de context van het WinUI 3-project. Als u een bestaand project hebt dat niet WinUI 3 is, raadpleegt u De Windows App SDK gebruiken in een bestaand project.

  1. Om uw ontwikkelcomputer in te stellen, zie Hulpprogramma's installeren voor de Windows App SDK.

  2. Download en voer het meest recente -installatieprogramma uit voor de Windows App SDK via Downloads voor de Windows App SDK. Hiermee worden de afhankelijkheden van het runtimepakket geïnstalleerd die zijn vereist voor het uitvoeren en implementeren van een app die is verpakt met een externe locatie of een uitgepakte app op het doelapparaat (zie de Windows App SDK-implementatiehandleiding voor frameworkafhankelijke apps die zijn verpakt met externe locatie of uitgepakt).

  3. C++. Installeer de Microsoft Visual C++ Redistributable (VCRedist) die geschikt is voor de architectuur van het doelapparaat.

    • De nieuwste versie van VCRedist is compatibel met de nieuwste algemeen beschikbare (GA) versie van Visual Studio (dus niet preview) en alle versies van Visual Studio die kunnen worden gebruikt om binaire bestanden voor Windows App SDK te bouwen.
    • Insider-builds van Visual Studio hebben mogelijk een latere versie van VCRedist geïnstalleerd en het uitvoeren van de openbare versie mislukt vervolgens met deze fout (die u kunt negeren): Fout 0x80070666: Kan een product niet installeren wanneer een nieuwere versie is geïnstalleerd.

    Notitie

    Als u VCRedist niet op het doelapparaat hebt geïnstalleerd, dan mislukken dynamische koppelingen naar c:\windows\system32\vcruntime140.dll. Deze fout kan op verschillende manieren zichtbaar zijn voor eindgebruikers.

  4. Selecteer in Visual Studio Bestand>Nieuw>Project.

  5. Selecteer in de vervolgkeuzelijsten van het dialoogvenster Nieuw project respectievelijk C# of C++, Windows en WinUI.

  6. U moet beginnen met een verpakt project om XAML-diagnostische gegevens te kunnen gebruiken. Selecteer daarom de Lege app, Verpakte (WinUI 3 in Desktop) projectsjabloon en klik op Volgende.

    Belangrijk

    Zorg ervoor dat het project dat u zojuist hebt gemaakt gericht is op de versie van de Windows App SDK die u hebt geïnstalleerd met het installatieprogramma in stap 2. Klik hiervoor in Visual Studio op Tools>NuGet pakketbeheer>NuGet-pakketten beheren voor oplossing...>Updates. En werk indien nodig de verwijzing naar het NuGet-pakket Microsoft.WindowsAppSDK bij. U kunt zien welke versie is geïnstalleerd op het tabblad Geïnstalleerd .

  7. Voeg de volgende eigenschap toe aan uw projectbestand: uw .csproj (C#) of .vcxproj (C++)-bestand. Plaats het binnen het PropertyGroup-element dat er al is (voor C++ zal het element Label="Globals" bevatten).

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

  8. C++. Stel in het bestand van uw C++-project (.vcxproj), binnen het bestaande PropertyGroup-element, de eigenschap AppxPackage in op onwaar.

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

  9. C#. Als u een C#-app wilt starten vanuit Visual Studio ( foutopsporing of zonder foutopsporing), selecteert u het uitgepakte startprofiel in de vervolgkeuzelijst Start . Als het pakketprofiel is geselecteerd, ziet u een implementatiefout in Visual Studio. Deze stap is niet nodig als u de toepassing (.exe) start vanaf de commandoregel of vanuit Windows Verkenner.

    Visual Studio - Vervolgkeuzelijst starten met het uitgepakte startprofiel van de C#-toepassing gemarkeerd

  10. Bouwen en uitvoeren.

De bootstrapper-API

Als u de <WindowsPackageType>None</WindowsPackageType> projecteigenschap instelt, wordt de automatische initialisatiefunctie gebruikt om een versie van de Windows App SDK-versie te zoeken en te laden die het meest geschikt is voor uw app.

Als u geavanceerde behoeften hebt (zoals aangepaste foutafhandeling of als u een specifieke versie van de Windows App SDK wilt laden), kunt u in plaats daarvan de bootstrapper-API expliciet aanroepen. Zie voor meer informatie De Windows App SDK-runtime gebruiken voor apps die zijn verpakt met een externe locatie of ongepakt, en Handleiding: De bootstrapper-API gebruiken in een app die is verpakt met een externe locatie of ongepakt die gebruikmaakt van de Windows App SDK.

Zie De implementatiearchitectuur en het overzicht voor frameworkafhankelijke apps voor meer informatie over de bootstrapper.

De code in de projectsjabloon bekijken

In dit scenario hebben we de projectsjabloon Blank App, Packaged (WinUI 3 in Desktop) gebruikt, waarmee een bureaublad-app wordt gemaakt met een gebruikersinterface op basis van WinUI 3. Laten we eens kijken naar een deel van de code die bij die sjabloon wordt geleverd en wat deze doet. Zie WinUI 3-sjablonen in Visual Studio voor meer informatie over beschikbare WinUI 3-project- en itemsjablonen.

Het toegangspunt van de app

Wanneer het Windows-besturingssysteem (OS) een app uitvoert, wordt het besturingssysteem uitgevoerd in het toegangspunt van de app. Dit toegangspunt heeft de vorm van een Main (of wWinMain voor C++/WinRT) functie. Normaal gesproken configureert een nieuw project die functie zodanig dat deze automatisch door het buildproces van Visual Studio wordt gegenereerd. En het is standaard verborgen, dus u hoeft zich er geen zorgen over te maken. Maar als je nieuwsgierig bent naar meer informatie, kun je Single-instancing in Main of wWinMain bekijken.

De app-klasse

De app als geheel wordt vertegenwoordigd door een klasse die doorgaans gewoon App wordt genoemd. Deze klasse is gedefinieerd in App.xaml en in de bijbehorende code-behind-bestanden (App.xaml.cs, of App.xaml.h en .cpp). De app is afgeleid van de klasse WinUI 3 Microsoft.UI.Xaml.Application .

De gegenereerde code in het toegangspunt creëert een instantie van Appen laat deze draaien.

In de constructor van App-ziet u de InitializeComponent methode die wordt aangeroepen. Deze methode parseert in feite de inhoud van App.xaml, wat XAML-opmaak is. En dat is belangrijk omdat App.xaml samengevoegde resources bevat die opgelost moeten worden en in een dictionary moeten worden geladen voor gebruik door de actieve app.

Een andere interessante methode van App is OnLaunched. Daar maken en activeren we een nieuw exemplaar van de Klasse MainWindow (die we hierna gaan bekijken).

De klasse MainWindow

Het hoofdvenster dat door de app wordt weergegeven, wordt natuurlijk vertegenwoordigd door de Klasse MainWindow . Deze klasse wordt gedefinieerd in MainWindow.xaml en in de bijbehorende code-behind-bestand(en) (MainWindow.xaml.csof MainWindow.xaml.h en)..cpp MainWindow- is afgeleid van de WinUI 3-klasse Microsoft.UI.Xaml.Window.

De constructor van MainWindow roept een eigen InitializeComponent-methode aan. Opnieuw is het zijn taak om de XAML-markering in MainWindow.xaml om te zetten in een grafiek van gebruikersinterfaceobjecten (UI).

In MainWindow.xaml ziet u de basisindeling van MainWindow. In de hoofdstructuur van de indeling bevindt zich een dynamisch deelvenster genaamd Microsoft.UI.Xaml.Controls.StackPanel. Zie Indelingspanelen voor meer informatie over indelingspanelen.

Binnen dat StackPanel is een Microsoft.UI.Xaml.Controls.Button. En dat Button de markup Click="myButton_Click" gebruikt om declaratief een gebeurtenishandlermethode te koppelen voor de Klik gebeurtenis.

Deze methode heeft de naam myButton_Click en u kunt de implementatie van die methode vinden in MainWindow.xaml.cs, of in MainWindow.xaml.cpp. Hierin wordt de inhoud van de knop gewijzigd van de standaard 'Klik hier' naar 'Geklikt'.

C++. Als u een C++-project hebt gemaakt, ziet u ook een MainWindow.idl bestand. Zie de C++/WinRT-documentatie voor meer informatie. XAML-besturingselementen; binden aan een C++/WinRT-eigenschap is een goede plek om te leren over het doel en het gebruik van .idl bestanden.

Volgende stappen

In dit onderwerp is uitgelegd hoe u een Visual Studio-project maakt voor een verpakte of uitgepakte app. Zie Zelfstudie: Een eenvoudige fotoviewer maken met WinUI 3 voor een voorbeeld van het toevoegen van functionaliteit aan een dergelijke app. In dit onderwerp wordt uitgelegd hoe u een eenvoudige app bouwt om foto's weer te geven.

Om uw ontwikkelreis voort te zetten met de Windows App SDK, zie Windows-bureaublad-apps ontwikkelen.