Winapp CLI gebruiken met .NET

Deze handleiding moet werken voor de meeste .NET projecttypen. De stappen zijn getest met zowel console- als op gebruikersinterface gebaseerde projecten, zoals WPF. Bekijk voor werkende voorbeelden de voorbeelden dotnet-app (console) en wpf-app (WPF) in de map met voorbeelden.

Deze handleiding laat zien hoe u de winapp CLI gebruikt met een .NET-toepassing om fouten op te sporen met pakketidentiteit en uw toepassing als msix te verpakken.

Pakketidentiteit is een kernconcept in het Windows app model. Hiermee heeft uw toepassing toegang tot specifieke Windows API's (zoals meldingen, beveiliging, AI-API's, enzovoort), een schone installatie-/verwijderingservaring en meer.

Een standaard uitvoerbaar bestand (zoals een bestand dat is gemaakt met dotnet build) heeft geen pakketidentiteit. In deze handleiding ziet u hoe u deze toevoegt voor foutopsporing en deze vervolgens inpakt voor distributie.

Vereiste voorwaarden

1. .NET SDK: installeer de .NET SDK (vereist opnieuw opstarten na de installatie):

   winget install Microsoft.DotNet.SDK.10 --source winget
   

2. winapp CLI: installeer het winapp hulpprogramma via winget (of werk bij als dit al is geïnstalleerd):

   winget install Microsoft.winappcli --source winget
   

1. Een nieuwe .NET-app maken

Begin met het maken van een eenvoudige .NET consoletoepassing:

dotnet new console -n dotnet-app
cd dotnet-app

Voer deze uit om te controleren of alles werkt:

dotnet run

Uitvoer moet 'Hallo, wereld!' zijn

2. Code bijwerken om identiteit te controleren

We werken de app bij om te controleren of deze wordt uitgevoerd met pakketidentiteit. We gebruiken de Windows Runtime-API voor toegang tot de Pakket-API's.

Werk eerst uw project-bestand bij om een specifieke Windows SDK-versie te targeten. Open dotnet-app.csproj en wijzig de TargetFramework om de Windows SDK-versie op te nemen:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Hiermee hebt u toegang tot Windows Runtime API's zonder dat u extra pakketten nodig hebt.

Vervang nu de inhoud van Program.cs door de volgende code. Met deze code wordt geprobeerd de huidige pakketidentiteit op te halen met behulp van de Windows Runtime-API. Als het lukt, wordt de familienaam van het pakket afgedrukt; anders wordt 'Niet verpakt' afgedrukt.

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Uitvoeren zonder identiteit

Voer nu de app uit zoals gebruikelijk:

dotnet run

U zou de uitvoer 'Niet verpakt' moeten zien. Hiermee wordt bevestigd dat het standaard uitvoerbare bestand wordt uitgevoerd zonder pakketidentiteit.

4. Initialiseer Project met winapp CLI

De opdracht winapp init detecteert automatisch .csproj bestanden en voert een .NET-specifieke installatie uit. Hiermee stelt u alles in dat u in één stap nodig hebt: valideert uw TargetFramework, voegt vereiste NuGet-pakketten toe, genereert het app-manifest en assets.

Voer de volgende opdracht uit en volg de aanwijzingen:

winapp init

Wanneer u hierom wordt gevraagd:

• Pakketnaam: Druk op Enter om de standaardwaarde te accepteren (dotnet-app)
• Publisher naam: Druk op Enter om de standaardinstelling te accepteren of voer uw naam in
• Versie: Druk op Enter om 1.0.0.0 te accepteren
• Description: Druk op Enter om de standaardwaarde (Windows toepassing) te accepteren of voer een beschrijving in
• Windows App SDK setup: Selecteer Stabiel, Preview of Experimenteel (bepaalt welke Windows App SDK versie wordt toegevoegd)
• TargetFramework-update: Als uw TargetFramework geen ondersteunde Windows SDK-versie bevat, wordt u gevraagd deze bij te werken (bijvoorbeeld naar net10.0-windows10.0.26100.0).
• Ontwikkelaarsmodus: Als u wordt gevraagd om de ontwikkelaarsmodus, kunt u deze desgewenst inschakelen, maar houd er rekening mee dat hiervoor beheerdersbevoegdheden zijn vereist

Met deze opdracht wordt het volgende uitgevoerd:

• Werk de TargetFramework in uw .csproj bij naar een ondersteunde Windows TFM (indien nodig)
• Voeg Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools en Microsoft.Windows.SDK.BuildTools.WinApp NuGet-pakketverwijzingen toe aan uw .csproj
• Maak Package.appxmanifest en Assets map voor uw app-identiteit

U kunt openen Package.appxmanifest om eigenschappen zoals de weergavenaam, uitgever en mogelijkheden verder aan te passen.

Controleer of de pakketten zijn toegevoegd aan uw project:

dotnet list package

U ziet Microsoft.WindowsAppSDK en Microsoft.Windows.SDK.BuildTools in de uitvoer.

Uitvoeringsalias toevoegen (voor console-apps)

Omdat we een console-app bouwen, moeten we ervoor zorgen dat dotnet run de console-uitvoer in de huidige terminal blijft. dotnet run Start standaard de verpakte app via AUMID-activering, waarmee een nieuw venster wordt geopend. Het venster wordt onmiddellijk gesloten wanneer de console-app is voltooid, waardoor uitvoer wordt ingeslikt.

U lost dit op door een uitvoeringsalias toe te voegen aan het manifest en de uitvoeringsintegratie te laten starten via die alias.

Skip deze stap als u een UI-app bouwt (WPF, WinForms, WinUI). Deze apps geven hun eigen venster weer, dus de standaard-AUMID-start is wat u wilt.

1. Voeg de uitvoeringsalias toe aan uw manifest:

   winapp manifest add-alias
   

   Hiermee wordt een uap5:ExecutionAlias aan Package.appxmanifest (standaardinstelling voor de exe-naam van uw project) toegevoegd, zodat de app kan worden gestart op naam vanuit een terminal.

2. Vertel de dotnet run integratie dat de alias gebruikt moet worden. Open dotnet-app.csproj en voeg het volgende toe binnen een <PropertyGroup> (of maak indien nodig een nieuwe <PropertyGroup> ):

   <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
   

   Als deze eigenschap is ingesteld, dotnet run start u de app via de uitvoeringsalias en neemt u de stdin/stdout/stderr van de huidige terminal over, zodat de console-uitvoer inline wordt weergegeven.

5. Debuggen met identiteit

Aangezien winapp init het NuGet-pakket Microsoft.Windows.SDK.BuildTools.WinApp aan uw project heeft toegevoegd, kunt u eenvoudig het volgende uitvoeren:

dotnet run

Hiermee wordt automatisch winapp run onder de schermen aangeroepen. Hiermee maakt u een los indelingspakket, registreert u het bij Windows en start u uw app met volledige pakketidentiteit.

De uitvoer moet er ongeveer zo uitzien:

Package Family Name: dotnet-app_12345abcde

Hiermee wordt bevestigd dat uw app wordt uitgevoerd met een geldige pakketidentiteit.

Alternatief: Handmatig winapp run

Als u het NuGet-pakket niet hebt gebruikt winapp init (of verwijderd), kunt u handmatig bouwen en uitvoeren:

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Het NuGet-pakket terug toevoegen: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Alternatief: Sparse-pakketidentiteit

Als u specifiek sparse-pakketgedrag nodig hebt (identiteit zonder bestanden te kopiëren), kunt u in plaats daarvan gebruiken create-debug-identity . Hiermee wordt een sparse-pakket geregistreerd dat verwijst naar uw exe in plaats van een losse indeling te maken:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Voer vervolgens het uitvoerbare bestand rechtstreeks uit (gebruik dotnet run dit niet omdat het bestand opnieuw kan worden opgebouwd/overschreven):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternatief: Handmatig MSBuild-target

Als u het NuGet-pakket liever niet gebruikt, kunt u een aangepast MSBuild-doel toevoegen dat create-debug-identity uitvoert na de Debug-builds. Voeg dit toe aan uw .csproj-bestand aan het einde, vlak voor de afsluitende </Project> tag:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Met deze configuratie dotnet build past u de foutopsporingsidentiteit toe en kunt u het uitvoerbare bestand rechtstreeks uitvoeren. Houd er rekening mee dat dotnet run de identiteit opnieuw kan opbouwen en overschrijven, dus draai de exe handmatig na het bouwen.

Wanneer u dit overslaat: als u liever expliciet controle hebt over wanneer identiteit wordt toegepast, of als u werkt aan code die niet nodig is voor de meeste ontwikkelcyclus, is de bovenstaande handmatige benadering mogelijk eenvoudiger.

6. Windows App SDK gebruiken (optioneel)

De Windows App SDK biedt u toegang tot moderne Windows API's buiten wat de basis-Windows SDK biedt, zoals het systeem voor meldingen, vensters van API's, app-levenscyclusbeheer en AI op het apparaat. Als uw app een van deze mogelijkheden nodig heeft, is deze stap voor u. Als u alleen pakketidentiteit nodig hebt voor distributie, kunt u doorgaan naar stap 7.

Als u winapp init (stap 4) hebt uitgevoerd, is Microsoft.WindowsAppSDK al toegevoegd als een NuGet-pakketreferentie voor uw .csproj. U kunt dit controleren met dotnet list package. Als u de SDK-installatie tijdens init hebt overgeslagen of handmatig moet toevoegen, voert u het volgende uit:

dotnet add package Microsoft.WindowsAppSDK

Program.cs bijwerken

Vervang de volledige inhoud van Program.cs door de volgende code, waarmee een Windows-app Runtime-versiecontrole wordt toegevoegd:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Bouwen en uitvoeren

Bouw de toepassing opnieuw en voer deze uit met Windows App SDK. Omdat we de WinAppSDK hebben toegevoegd, moeten we opnieuw registreren met de identiteit, zodat winapp de runtime-afhankelijkheid wordt toegevoegd. Als u het WinApp NuGet-pakket (aanbevolen) hebt toegevoegd, voert u gewoon uit dotnet run. Anders (vervang door dotnet-app de projectnaam):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

U ziet nu uitvoer zoals:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

Het Windows App SDK NuGet-pakket bevat alle benodigde assembly's voor toegang tot moderne Windows-API's, waaronder:

• Meldingen en live-tegels
• Venstermanagement en applicatielevenscyclus
• Pushmeldingen
• En nog veel meer Windows App SDK onderdelen

Raadpleeg de documentatie Windows App SDK voor geavanceerdere Windows App SDK gebruik.

7. Pakket met MSIX

Zodra u klaar bent om uw app te distribueren, kunt u deze verpakken als een MSIX met hetzelfde manifest.

Build voor release

Bouw eerst uw toepassing in de releasemodus voor optimale prestaties:

dotnet build -c Release

Een ontwikkelingscertificaat genereren

Voordat u gaat verpakken, hebt u een ontwikkelingscertificaat nodig voor ondertekening. Genereer er een als u dat nog niet hebt gedaan:

winapp cert generate --if-exists skip

Ondertekenen en inpakken

U kunt nu verpakken en ondertekenen. Wijs de opdracht pack naar de build-uitvoermap (vervang het TFM-pad en dotnet-app met de waarden van uw project):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx 

Opmerking: De pack opdracht maakt automatisch gebruik van package.appxmanifest uit uw huidige map en kopieert deze naar de doelmap voordat de verpakking wordt verpakt. Het gegenereerde MSIX-bestand bevindt zich in de huidige map.

Het certificaat installeren

Voordat u het MSIX-pakket kunt installeren, moet u het ontwikkelingscertificaat installeren. Voer deze opdracht uit als beheerder:

winapp cert install .\devcert.pfx

Installeren en uitvoeren

Installeer het pakket door te dubbelklikken op het gegenereerde *.msix-bestand.

U kunt nu uw app vanaf elke locatie in de terminal uitvoeren door het volgende te typen:

dotnet-app

Als het goed is, ziet u de uitvoer "Package Family Name", waarin wordt bevestigd dat deze is geïnstalleerd en uitgevoerd met identiteit.

Tips

1. Zodra u klaar bent voor distributie, kunt u uw MSIX ondertekenen met een certificaat voor ondertekening van programmacode van een certificeringsinstantie, zodat uw gebruikers geen zelfondertekend certificaat hoeven te installeren.
2. De Microsoft Store zal de MSIX voor u ondertekenen, u hoeft deze niet te ondertekenen voordat u hem indient.
3. Mogelijk moet u meerdere MSIX-pakketten maken, één voor elke architectuur die u ondersteunt (x64, Arm64). Gebruik de -r vlag met dotnet build om op specifieke architecturen te richten: dotnet build -c Release -r win-x64 of dotnet build -c Release -r win-arm64.

MSIX Packaging automatiseren (optioneel)

Als u MSIX-pakketten wilt automatiseren als onderdeel van uw release-builds, voegt u dit doel toe aan uw .csproj bestand (u kunt het toevoegen naast het doel voor foutopsporingsidentiteit):

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Met deze configuratie:

• In de release-modus (dotnet build -c Release) wordt automatisch het MSIX-pakket gemaakt
• De MSIX is verpakt en ondertekend met uw ontwikkelingscertificaat
• Het uiteindelijke .msix bestand staat in de hoofdmap van het project

U kunt ook een aangepaste configuratie maken (bijvoorbeeld PackagedRelease) door de voorwaarde te wijzigen in '$(Configuration)' == 'PackagedRelease'.

Volgende stappen

• Distribute via winget: Dien uw MSIX in bij de Windows Pakketbeheer Community-opslagplaats
• Publiceren naar de Microsoft Store: gebruik winapp store om uw pakket in te dienen
• Set up CI/CD: Gebruik de GitHub Actie setup-WinAppCli om automatisering van het verpakken in uw pijplijn te realiseren.
• Explore Windows API's: Met pakketidentiteit kunt u nu meldingen, on-device AI en andere identiteitsafhankelijke API's gebruiken