Använda winapp CLI med .NET

Den här guiden bör fungera för de flesta .NET projekttyper. Stegen har testats med både konsol- och gränssnittsbaserade projekt som WPF. I arbetsexempel kan du titta på dotnet-app (konsol) och wpf-app (WPF) i exempelmappen.

Den här guiden visar hur du använder winapp CLI med ett .NET-program för att felsöka med paketidentitet och paketera ditt program som en MSIX.

Paketidentitet är ett grundläggande begrepp i Windows app modellen. Det gör att ditt program kan komma åt specifika Windows API:er (t.ex. meddelanden, säkerhet, AI-API:er osv.), har en ren installations-/avinstallationsupplevelse med mera.

En körbar standard (som en som skapats med dotnet build) har inte paketidentitet. Den här guiden visar hur du lägger till den för felsökning och sedan paketera den för distribution.

Förutsättningar

1. .NET SDK: Installera .NET SDK (kräver en omstart efter installationen):

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

2. winapp CLI: Installera winapp verktyget via winget (eller uppdatera om det redan är installerat):

   winget install Microsoft.winappcli --source winget
   

1. Skapa en ny .NET-app

Börja med att skapa ett enkelt .NET konsolprogram:

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

Kör den för att kontrollera att allt fungerar:

dotnet run

Utdata ska vara "Hello, World!"

2. Uppdatera koden för att kontrollera identiteten

Vi uppdaterar appen för att kontrollera om den körs med paketidentitet. Vi använder Windows Runtime API:et för att komma åt paket-API:erna.

Uppdatera först din project-fil för att rikta in dig på en specifik Windows SDK-version. Öppna dotnet-app.csproj och ändra TargetFramework så att den innehåller Windows SDK-versionen:

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

Detta ger dig åtkomst till Windows Runtime API:er utan att behöva ytterligare paket.

Ersätt nu innehållet i Program.cs med följande kod. Den här koden försöker hämta den aktuella paketidentiteten med hjälp av Windows Runtime-API:et. Om det lyckas skrivs paketfamiljenamnet ut. annars skrivs "Inte paketerad".

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. Kör utan identitet

Kör appen som vanligt:

dotnet run

Du bör se utdata "Inte paketerad". Detta bekräftar att den körbara standarden körs utan paketidentitet.

4. Initiera Project med winapp CLI

Kommandot winapp init identifierar automatiskt .csproj-filer och kör en .NET specifik installation. Den konfigurerar allt du behöver på en och samma plats: verifierar dina TargetFramework, lägger till nödvändiga NuGet-paket, genererar appmanifestet och tillgångarna.

Kör följande kommando och följ anvisningarna:

winapp init

När du uppmanas att göra det:

• Paketnamn: Tryck på Retur för att acceptera standardvärdet (dotnet-app)
• Utgivarens namn: Tryck på Enter för att acceptera standardvärdet eller ange ditt namn
• Version: Tryck på Retur för att acceptera 1.0.0.0
• Description: Tryck på Retur för att acceptera standardvärdet (Windows-applikation) eller ange en beskrivning
• Windows App SDK installation: Välj Stabil, Förhandsversion eller Experimentell (avgör vilken Windows App SDK version som läggs till)
• TargetFramework update: Om din TargetFramework inte innehåller en Windows SDK-version som stöds, kommer du att uppmanas att uppdatera den (t.ex. till net10.0-windows10.0.26100.0)
• Utvecklarläge: Om du tillfrågas om "Utvecklarläge" kan du aktivera det om du vill, men tänk på att det kräver administratörsbehörighet

Det här kommandot kommer att:

• Uppdatera TargetFramework i din .csproj till en Windows TFM som stöds (om det behövs)
• Lägg till Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools och Microsoft.Windows.SDK.BuildTools.WinApp NuGet-paketreferenser till dina .csproj
• Skapa Package.appxmanifest och Assets mapp för din appidentitet

Du kan öppna Package.appxmanifest för att ytterligare anpassa egenskaper som visningsnamn, utgivare och funktioner.

Så här kontrollerar du att paketen har lagts till i projektet:

dotnet list package

Du bör se Microsoft.WindowsAppSDK och Microsoft.Windows.SDK.BuildTools i utdata.

Lägg till köralias (för konsolappar)

Eftersom vi skapar en konsolapp måste vi se dotnet run till att konsolens utdata bevaras i den aktuella terminalen. Som standard dotnet run startar den paketerade appen via AUMID-aktivering, vilket öppnar ett nytt fönster – och fönstret stängs omedelbart när konsolappen är klar och sväljer eventuella utdata.

För att åtgärda detta lägger du till ett köralias i manifestet och anger körintegration att starta via det aliaset i stället.

Skip det här steget om du skapar en användargränssnittsapp (WPF, WinForms, WinUI). Dessa appar renderar sitt eget fönster, så standardstarten för AUMID är vad du vill ha.

1. Lägg till körningsaliaset i manifestet:

   winapp manifest add-alias
   

   Detta lägger till ett uap5:ExecutionAlias till Package.appxmanifest (som standard i projektets exe-namn) så att appen kan startas med namn från en terminal.

2. Be integreringen dotnet run att använda aliaset. Öppna dotnet-app.csproj och lägg till följande i valfri <PropertyGroup> (eller skapa en ny <PropertyGroup> om det behövs):

   <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
   

   Med de här egenskaperna startar dotnet run appen via körningsaliaset och ärver den aktuella terminalens stdin/stdout/stderr så att du ser konsolens utdata direkt.

5. Felsöka med identitet

Eftersom winapp init lade till Microsoft.Windows.SDK.BuildTools.WinApp NuGet-paketet i projektet kan du helt enkelt köra:

dotnet run

Detta anropar automatiskt winapp run under huven – skapa ett löst layoutpaket, registrera det med Windows och starta appen med fullständig paketidentitet.

Du bör se utdata som liknar följande:

Package Family Name: dotnet-app_12345abcde

Detta bekräftar att din app körs med en giltig paketidentitet!

Alternativ: Manuell winapp run

Om du inte använde winapp init (eller tog bort NuGet-paketet) kan du skapa och köra manuellt:

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

Så här lägger du till NuGet-paketet igen: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Alternativ: Gles paketidentitet

Om du behöver glesa paketbeteende specifikt (identitet utan att kopiera filer) kan du använda create-debug-identity i stället. Detta registrerar ett glest paket som pekar på din exe i stället för att skapa en lös layout:

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

Kör sedan den körbara filen direkt (använd dotnet run inte eftersom den kan återskapa/skriva över filen):

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

Alternativ: Manuellt MSBuild-mål

Om du föredrar att inte använda NuGet-paketet kan du lägga till ett anpassat MSBuild-mål som körs create-debug-identity efter felsökningsversioner. Lägg till detta i filen .csproj i slutet, precis före den avslutande taggen </Project>:

  <!-- 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>

Med den här konfigurationen dotnet build tillämpar du felsökningsidentiteten och du kan köra den körbara filen direkt. Observera att dotnet run kan återskapa och skriva över identiteten, så kör exe-filen manuellt efter att du har byggt.

När du ska hoppa över detta: Om du föredrar explicit kontroll över när identitet tillämpas, eller om du arbetar med kod som inte behöver identitet under större delen av utvecklingscykeln, kan den manuella metoden ovan vara enklare.

6. Använda Windows App SDK (valfritt)

Med Windows App SDK får du tillgång till moderna Windows API:er utöver det grundläggande Windows SDK tillhandahåller – till exempel meddelandesystemet, fönster-API:er, applivscykelhantering och AI på enheten. Om din app behöver någon av dessa funktioner är det här steget för dig. Om du bara behöver paketidentitet för distribution kan du gå vidare till steg 7.

Om du körde winapp init (steg 4) har Microsoft.WindowsAppSDK redan lagts till som en NuGet-paketreferens till din .csproj. Du kan verifiera med dotnet list package. Om du hoppades över SDK-installationen under init, eller om du behöver lägga till den manuellt, kör du:

dotnet add package Microsoft.WindowsAppSDK

Uppdatera Program.cs

Ersätt hela innehållet i Program.cs med följande kod, som lägger till en Windows App Körningsversionskontroll:

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");
        }
    }
}

Skapa och kör

Återskapa och kör programmet med Windows App SDK. Eftersom vi har lagt till WinAppSDK måste vi återigen registrera med identitet så winapp lägger till körningstidsberoendet. Om du har lagt till WinApp NuGet-paketet (rekommenderas) kör du helt enkelt dotnet run. Annars (ersätt dotnet-app med projektnamnet):

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

Nu bör du se utdata som:

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

NuGet-paketet Windows App SDK innehåller alla nödvändiga sammansättningar för åtkomst till moderna Windows API:er, inklusive:

• Meddelanden och dynamiska paneler
• Fönster- och applikationslivscykel
• Push-meddelanden
• Och många fler Windows App SDK komponenter

Mer avancerad Windows App SDK användning finns i dokumentationen Windows App SDK.

7. Paket med MSIX

När du är redo att distribuera din app kan du paketera den som en MSIX med samma manifest.

Skapa för lansering

Börja med att skapa ditt program i versionsläge för optimala prestanda:

dotnet build -c Release

Generera ett utvecklingscertifikat

Innan du paketerar behöver du ett utvecklingscertifikat för signering. Generera en om du inte redan har gjort det:

winapp cert generate --if-exists skip

Signera och packa

Nu kan du paketera och signera. Peka på packkommandot till mappen med utdata för bygget (byt ut dotnet-app och TFM-sökvägen med projektets specifika värden):

# 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 

Obs! Kommandot pack använder automatiskt Package.appxmanifest från din aktuella katalog och kopierar den till målmappen före paketering. Den genererade .msix-filen finns i den aktuella katalogen.

Installera certifikatet

Innan du kan installera MSIX-paketet måste du installera utvecklingscertifikatet. Kör det här kommandot som administratör:

winapp cert install .\devcert.pfx

Installera och kör

Installera paketet genom att dubbelklicka på den genererade *.msix-filen.

Nu kan du köra appen var som helst i terminalen genom att skriva:

dotnet-app

Du bör se utdata för "Package Family Name" som bekräftar att det är installerat och körs med rätt identitet.

Tips

1. När du är redo för distribution kan du signera MSIX med ett kodsigneringscertifikat från en certifikatutfärdare så att användarna inte behöver installera ett självsignerat certifikat.
2. Microsoft Store signerar MSIX åt dig, du behöver inte signera innan det skickas in.
3. Du kan behöva skapa flera MSIX-paket, ett för varje arkitektur som du stöder (x64, Arm64). -r Använd flaggan med dotnet build för att rikta specifika arkitekturer: dotnet build -c Release -r win-x64 eller dotnet build -c Release -r win-arm64.

Automatisera MSIX-paketering (valfritt)

Om du vill automatisera MSIX-paketering som en del av dina utgåvekompileringar, lägg till detta byggmål i .csproj-filen (du kan lägga till det tillsammans med felsökningsidentitetsbyggmålet).

  <!-- 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>

Med den här konfigurationen:

• Kompilering i produktionsläge (dotnet build -c Release) kommer automatiskt att skapa MSIX-paketet
• MSIX är paketerat och signerat med ditt utvecklingscertifikat
• Den sista .msix filen kommer att finnas i projektets rot

Du kan också skapa en anpassad konfiguration (t.ex. PackagedRelease) genom att ändra villkoret till '$(Configuration)' == 'PackagedRelease'.

Nästa steg

• Distribute via winget: Skicka din MSIX till Windows Správca balíkov Community Repository
• Publicera till Microsoft Store: Skicka paketet med winapp store
• Set up CI/CD: Använd setup-WinAppCli GitHub Action för att automatisera paketeringen i din pipeline
• Explore Windows API:er: Med paketidentitet kan du nu använda notiser, AI på enheten och andra identitetsberoende API:er