Utilisation de winapp CLI avec applications .NET basées sur des fichiers

Pour obtenir un exemple fonctionnel, consultez l’exemple dotnet-file-app sample. Pour obtenir la référence complète, consultez le mode fichier unique dans la référence CLI.

.NET 10 peut exécuter un seul fichier .cs sans fichier de projet. Ce guide montre comment exécuter ce fichier avec une identité de package en utilisant winapp run, afin que des API telles que Windows.ApplicationModel.Package.Current, les notifications d’application et l’IA sur l’appareil fonctionnent. Vous ne créez pas de manifeste ou de ressources d’image : winapp les génère pour vous.

L’identité de package est un concept de base dans le modèle Windows app. Il permet à votre application d’accéder à des API Windows spécifiques, d’avoir une expérience d’installation/désinstallation propre, et bien plus encore. Une application basée sur des fichiers exécutée avec dotnet run n’a pas d’identité de package.

Prerequisites

1. .NET SDK 10.0.300 ou version ultérieure : installez le SDK .NET 10 (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 basée sur des fichiers

Créez un dossier avec un fichier nommé hello.cs:

#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

using Windows.ApplicationModel;

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

Les #:property lignes configurent l’application comme le ferait une .csproj. La fonctionnalité Windows TargetFramework donne au code l’accès aux API Windows Runtime telles que Package.

Exécutez ceci avec dotnet run:

dotnet run hello.cs

La sortie est Not packaged: l’application s’exécute sans identité de package.

2. Exécuter avec l’identité du package

Exécutez le même fichier avec winapp :

winapp run hello.cs

winapp compile l’application, génère un manifeste et des ressources d’image par défaut dans la sortie de build, inscrit l’application en tant que package et la lance. La sortie affiche maintenant l’identité du package :

Package Family Name: hello-<hash>_<publisher-hash>

Votre dossier source contient toujours uniquement hello.cs. Étant donné qu’il s’agit d’une application console (OutputType=Exe), winapp la lance via un alias d’exécution, de sorte que sa sortie s’affiche dans votre terminal.

L’enregistrement reste en place après la fermeture de l’application, de sorte qu’en exécutant winapp run hello.cs à nouveau, la même identité est réutilisée. Vous la supprimez à l’étape 5.

3. Nommer votre package

Par défaut, le nom du package est le nom du fichier plus un hachage court du chemin d’accès du fichier. Pour choisir votre propre nom, désenregistrez d’abord le package actuel, car un nouveau nom enregistre un nouveau package :

winapp unregister hello.cs

Ensuite, ajoutez des #:property directives en haut de hello.cs:

#:property WinAppPackageName=com.contoso.hello
#:property WinAppDisplayName=Contoso Hello
#:property Version=1.0.0

Réexécutez-le :

winapp run hello.cs

La sortie affiche le nouveau nom, par exemple Package Family Name: com.contoso.hello_<publisher-hash>. L’application apparaît également dans le menu Démarrer en tant que Contoso Hello.

Pour chaque propriété d’identité et sa valeur par défaut, consultez les propriétés du manifeste.

4. Exécuter avec dotnet run

Pour obtenir la même version packagée à partir de dotnet run simple, faites référence au package Microsoft.Windows.SDK.BuildTools.WinApp au début de hello.cs :

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*

dotnet run hello.cs

La sortie affiche la même identité de package que winapp run. Étant donné que dotnet run se génère dans un autre dossier de sortie, il avertit qu’il remplace un enregistrement existant installé à partir d’un autre emplacement. Ceci est attendu et vous pouvez l’ignorer.

Le package donne également à l’application une icône temporaire pour la fenêtre. Par conséquent, une application fenêtrée affiche une icône dans sa barre de titre. Pour utiliser la vôtre, pointez ApplicationIcon sur un fichier .ico :

#:property ApplicationIcon=Assets\MyApp.ico

Pour connaître les propriétés qui contrôlent ce lancement, consultez Exécution avec dotnet run.

5. Nettoyage

Supprimez l’enregistrement en transmettant le fichier .cs à winapp unregister :

winapp unregister hello.cs

Ajouter des fonctionnalités ou un manifeste personnalisé

Certaines API ont besoin d’une capacité déclarée. Par exemple, les API d’IA Windows ont besoin des éléments suivants systemAIModels:

#:property WinAppCapabilities=systemAIModels

winapp écrit chaque fonctionnalité dans l’élément manifeste correct. Consultez fonctionnalités pour obtenir la liste complète et les règles d’affectation de noms.

Les gestionnaires de protocole, les associations de fichiers et d’autres intégrations du shell ont besoin d’un manifeste rédigé. Placez un hello.appxmanifest à côté de hello.cs et winapp l’utilise au lieu d’en générer un. Voir Utiliser votre propre manifeste.

Prochaines étapes

• Paquet pour la distribution : winapp run enregistre l’application pour le développement uniquement. Pour produire un MSIX que vous pouvez distribuer, déplacez votre code dans un projet et suivez Package avec MSIX dans le guide .NET.
• Explorez les API Windows : avec l’identité du package, vous pouvez maintenant utiliser les Notifications, l’IA sur appareil et d’autres API dépendantes de l’identité