Utilisation de l’interface CLI winapp avec .NET

Ce guide doit fonctionner pour la plupart des types de projets .NET. Les étapes ont été testées avec des projets basés sur la console et l’interface utilisateur comme WPF. Pour obtenir des exemples de travail, consultez les exemples dotnet-app (console) et wpf-app (WPF) dans le dossier d’exemples.

Ce guide montre comment utiliser l’interface CLI winapp avec une application .NET pour déboguer avec l’identité de package et empaqueter votre application en tant que MSIX.

L’identité de package est un concept de base dans le modèle Windows app. Elle permet à votre application d’accéder à des API Windows spécifiques (telles que notifications, sécurité, API IA, etc.), d’avoir une expérience d’installation/désinstallation propre, etc.

Un exécutable standard (tel qu’un fichier créé avec dotnet build) n’a pas d’identité de package. Ce guide montre comment l’ajouter pour le débogage, et ensuite l'emballer pour la distribution.

Prerequisites

  1. .NET SDK : installez le Kit de développement logiciel (SDK) .NET (nécessite un redémarrage après l’installation) :

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

  2. winapp CLI : Installez l’outil winapp via winget (ou mettez à jour s’il est déjà installé) :

    winget install Microsoft.winappcli --source winget

1. Créer une application .NET

Commencez par créer une application console .NET simple :

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

Exécutez-le pour vous assurer que tout fonctionne :

dotnet run

La sortie doit être « Hello, World ! »

2. Mettre à jour le code pour vérifier l’identité

Nous allons mettre à jour l’application pour vérifier si elle s’exécute avec l’identité du package. Nous allons utiliser l'API Windows Runtime pour accéder aux API de package.

Tout d’abord, mettez à jour votre fichier project pour cibler une version spécifique du Kit de développement logiciel (SDK) Windows. Ouvrez dotnet-app.csproj et modifiez la TargetFramework pour inclure la version du KIT de développement logiciel (SDK) Windows :

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

Cela vous permet d’accéder à Windows Runtime API sans avoir besoin de packages supplémentaires.

Maintenant, remplacez le contenu de Program.cs par le code suivant. Ce code tente de récupérer l’identité de package actuelle à l’aide de l’API Windows Runtime. S’il réussit, il imprime le nom de la famille de packages ; sinon, il imprime « Non empaqueté ».

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. Exécuter sans identité

À présent, exécutez l’application comme d’habitude :

dotnet run

La sortie « Non empaquetée » doit s’afficher. Cela confirme que l’exécutable standard est en cours d’exécution sans identité de package.

4. Initialiser le projet avec l’interface CLI winapp

La commande winapp init détecte automatiquement les fichiers .csproj et exécute une configuration spécifique à .NET. Il configure tout ce dont vous avez besoin en une seule fois : valide votre TargetFramework, ajoute les packages NuGet requis, génère le manifeste de l'application et les ressources.

Exécutez la commande suivante et suivez les instructions :

winapp init

Lorsque vous y êtes invité :

  • Nom du package : appuyez sur Entrée pour accepter la valeur par défaut (dotnet-app)
  • Publisher nom : appuyez sur Entrée pour accepter la valeur par défaut ou entrer votre nom
  • Version : appuyez sur Entrée pour accepter la version 1.0.0.0
  • Description : appuyez sur Entrée pour accepter la valeur par défaut (application Windows) ou entrer une description
  • SDK d'application Windows configuration : sélectionnez Stable, Préversion ou Expérimental (détermine la version SDK d'application Windows ajoutée)
  • mise à jour TargetFramework : si votre TargetFramework n'inclut pas de version prise en charge du SDK Windows, vous serez invité à le mettre à jour (par exemple, pour net10.0-windows10.0.26100.0)
  • Mode développeur : si vous êtes invité à indiquer « Mode développeur », vous pouvez l’activer si vous le souhaitez, mais sachez qu’il nécessite des privilèges d’administration

Cette commande va :

  • Mettez à jour le TargetFramework dans votre .csproj vers un TFM Windows pris en charge (si nécessaire)
  • Ajoutez Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools et Microsoft.Windows.SDK.BuildTools.WinApp références de package NuGet à votre .csproj
  • Créer Package.appxmanifest et Assets dossier pour votre identité d’application

Note

Contrairement aux projets natifs/C++, le flux .NET ne crée pas un fichier . Les packages NuGet sont gérés directement via votre .csproj. Permet dotnet restore de restaurer des packages après le clonage.

Vous pouvez ouvrir Package.appxmanifest pour personnaliser davantage les propriétés telles que le nom d’affichage, l’éditeur et les fonctionnalités.

Pour vérifier que les packages ont été ajoutés à votre projet :

dotnet list package

Vous devez voir Microsoft.WindowsAppSDK et Microsoft.Windows.SDK.BuildTools dans la sortie.

Ajouter un alias d’exécution (pour les applications console)

Étant donné que nous créons une application console, nous devons veiller dotnet run à conserver la sortie de la console dans le terminal actuel. Par défaut, dotnet run lance l’application empaquetée via l’activation AUMID, qui ouvre une nouvelle fenêtre , et la fenêtre se ferme immédiatement une fois l’application console terminée, avalant toute sortie.

Pour résoudre ce problème, vous allez ajouter un alias d’exécution au manifeste et indiquer à l’intégration d’exécution de lancer via cet alias à la place.

Skip cette étape si vous créez une application d'interface utilisateur (WPF, WinForms, WinUI). Ces applications affichent leur propre fenêtre. Par conséquent, le lancement AUMID par défaut est ce que vous souhaitez.

  1. Ajoutez l’alias d’exécution à votre manifeste :

    winapp manifest add-alias

    Cela ajoute un uap5:ExecutionAlias à Package.appxmanifest (en utilisant par défaut le nom de l'exécutable de votre projet) afin que l'application puisse être lancée par son nom à partir d'un terminal.

  2. Indiquez à l’intégration dotnet run d’utiliser l’alias. Ouvrez dotnet-app.csproj et ajoutez ce qui suit à l’intérieur de n’importe quel <PropertyGroup> (ou créez-en un <PropertyGroup> si nécessaire) :

    <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>

    Avec cette propriété, dotnet run lance l’application via son alias d’exécution et hérite du stdin/stdout/stderr du terminal actuel pour que vous puissiez voir la sortie de la console en ligne.

5. Déboguer avec l’identité numérique

Étant donné que winapp init ajouté le package NuGet Microsoft.Windows.SDK.BuildTools.WinApp à votre projet, vous pouvez simplement exécuter :

dotnet run

Cela appelle automatiquement winapp run en arrière-plan, créant un ensemble de disposition libre, l'inscrivant auprès de Windows et lançant votre application avec une identité de package complète.

Note

Vous pouvez voir les avertissements de vulnérabilité NuGet (NU1900) sur les sources de packages. Ils sont sûrs d’ignorer : ils n’affectent pas votre build.

Vous devez voir un résultat similaire à :

Package Family Name: dotnet-app_12345abcde

Cela confirme que votre application est en cours d’exécution avec une identité de package valide !

Alternative : Manuel winapp run

Si vous n’avez pas utilisé winapp init (ou supprimé le package NuGet), vous pouvez générer et exécuter manuellement :

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

Pour ajouter le package NuGet à nouveau : dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Conseil / Astuce

Pour désactiver l'intégration automatique dotnet run, ajoutez <EnableWinAppRunSupport>false</EnableWinAppRunSupport> à votre .csproj. Consultez les documents de support dotnet run pour connaître les options de personnalisation.

Alternative : Identité de paquet éparse

Si vous avez besoin d’un comportement de package éparse spécifiquement (identité sans copier de fichiers), vous pouvez utiliser create-debug-identity à la place. Cela enregistre un package épars pointant vers votre exe plutôt que de créer une structure non liée :

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

Exécutez ensuite l’exécutable directement (ne pas utiliser dotnet run car il peut reconstruire/remplacer le fichier) :

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

Alternative : Cible MSBuild manuelle

Si vous préférez ne pas utiliser le package NuGet, vous pouvez ajouter une cible MSBuild personnalisée qui s’exécute create-debug-identity après les builds de débogage. Ajoutez-le à votre fichier .csproj à la fin, juste avant la balise de fermeture </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>

Avec cette configuration, dotnet build applique le profil de débogage et vous pouvez lancer l’exécutable directement. Notez que dotnet run peut reconstruire et remplacer l’identité. Exécutez le fichier .exe manuellement après la compilation.

Conseil / Astuce

Pour les flux de travail de débogage avancés (attachement de débogueurs, configuration de l’IDE, débogage au démarrage), consultez le Guide de débogage.

Quand ignorer ceci : si vous préférez un contrôle explicite sur l’application de l’identité ou si vous travaillez sur du code qui n’a pas besoin d’identité pour la plupart de votre cycle de développement, l’approche manuelle ci-dessus peut être plus simple.

6. Utilisation de SDK d'application Windows (facultatif)

Le SDK d'application Windows vous permet d’accéder aux API de Windows modernes au-delà de ce que fournit le kit SDK de base Windows , comme le système de notification, les API de fenêtrage, la gestion du cycle de vie des applications et l’IA sur appareil. Si votre application a besoin de l’une de ces fonctionnalités, cette étape est pour vous. Si vous avez simplement besoin d’une identité de package pour la distribution, vous pouvez passer à l’étape 7.

Si vous avez exécuté winapp init (étape 4), Microsoft.WindowsAppSDK a déjà été ajouté en tant que référence de package NuGet à votre .csproj. Vous pouvez vérifier avec dotnet list package. Si vous avez ignoré la configuration du Kit de développement logiciel (SDK) pendant l’init ou que vous devez l’ajouter manuellement, exécutez :

dotnet add package Microsoft.WindowsAppSDK

Mise à jour Program.cs

Remplacez l’intégralité du contenu de Program.cs par le code suivant, ce qui ajoute une vérification de version application Windows Runtime :

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

Compiler et exécuter

Régénérez et exécutez l’application avec SDK d'application Windows. Étant donné que nous avons ajouté le WinAppSDK, nous devons nous réenregistrer avec l'identité pour que winapp ajoute la dépendance d'exécution. Simplement, exécutez dotnet run si vous avez ajouté le paquet NuGet WinApp (recommandé). Sinon (remplacez dotnet-app par le nom de votre projet) :

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

Vous devriez maintenant voir une sortie ressemblant à :

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

Le package NuGet SDK d'application Windows inclut tous les assemblys nécessaires pour accéder aux API de Windows modernes, notamment :

  • Notifications et vignettes dynamiques
  • Cycle de vie des fenêtres et des applications
  • Notifications par push
  • Et bien d’autres composants SDK d'application Windows

Pour une utilisation plus avancée SDK d'application Windows, consultez la documentation SDK d'application Windows.

7. Package avec MSIX

Une fois que vous êtes prêt à distribuer votre application, vous pouvez la empaqueter en tant que MSIX à l’aide du même manifeste.

Construction pour la publication

Tout d’abord, générez votre application en mode mise en production pour obtenir des performances optimales :

dotnet build -c Release

Note

Vous pouvez voir des avertissements de vulnérabilité NuGet (NU1900). Ceux-ci sont sans importance et peuvent être ignorés et n’affectent pas votre résultat de compilation.

Générer un certificat de développement

Avant d’empaqueter, vous avez besoin d’un certificat de développement pour la signature. Générez-en un si vous ne l’avez pas déjà fait :

winapp cert generate --if-exists skip

Signer et Emballer

Vous pouvez maintenant empaqueter et signer. Pointez la commande pack vers votre dossier de sortie de build (remplacez dotnet-app et le chemin TFM par les valeurs de votre projet) :

# 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

Remarque : la pack commande utilise automatiquement package.appxmanifest à partir de votre répertoire actif et la copie dans le dossier cible avant l’empaquetage. Le fichier .msix généré se trouvera dans le répertoire actif.

Installer le certificat

Avant de pouvoir installer le package MSIX, vous devez installer le certificat de développement. Exécutez cette commande en tant qu’administrateur :

winapp cert install .\devcert.pfx

Installer et exécuter

Installez le package en double-cliquant sur le fichier *.msix généré.

Vous pouvez maintenant exécuter votre application n’importe où dans le terminal en tapant :

dotnet-app

Vous devez voir la sortie « Nom de la famille de packages », confirmant son installation et son exécution avec l’identité.

Conseil / Astuce

Si vous devez repackager votre application (par exemple, après une modification du code), incrémentez le Version dans votre Package.appxmanifest, avant de lancer à nouveau winapp pack. Windows nécessite un numéro de version supérieur pour mettre à jour un package installé.

Conseils

  1. Une fois que vous êtes prêt à être distribué, vous pouvez signer votre MSIX avec un certificat de signature de code auprès d’une autorité de certification afin que vos utilisateurs n’aient pas besoin d’installer un certificat auto-signé.
  2. Le Microsoft Store signera le MSIX pour vous, sans avoir à le signer vous-même avant la soumission.
  3. Vous devrez peut-être créer plusieurs packages MSIX, un pour chaque architecture prise en charge (x64, Arm64). Utilisez l’indicateur -r avec dotnet build pour cibler des architectures spécifiques : dotnet build -c Release -r win-x64 ou dotnet build -c Release -r win-arm64.

Automatisation de l’empaquetage MSIX (facultatif)

Pour automatiser l’empaquetage MSIX dans le cadre de vos builds Release, ajoutez cette cible à votre .csproj fichier (vous pouvez l’ajouter en même temps que la cible d’identité de débogage) :

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

Avec cette configuration :

  • La génération en mode Release (dotnet build -c Release) crée automatiquement le package MSIX
  • MSIX est empaqueté et signé avec votre certificat de développement
  • Le fichier final .msix sera à la racine du projet

Vous pouvez également créer une configuration personnalisée (par exemple, PackagedRelease) en modifiant la condition à '$(Configuration)' == 'PackagedRelease'.

Prochaines étapes

  • Last updated on