Applications basées sur des fichiers

Cet article s’applique à : ✔️ SDK .NET 10 et versions ultérieures

Les applications basées sur des fichiers vous permettent de générer, d’exécuter et de publier des applications .NET à partir d’un seul fichier C# sans créer de fichier projet traditionnel. Ils offrent une alternative légère aux projets .NET traditionnels. Cette approche simplifie le développement pour les scripts, les utilitaires et les petites applications. Le Kit de développement logiciel (SDK) .NET génère automatiquement la configuration de projet nécessaire en fonction des directives de votre fichier source.

Les principaux avantages sont les suivants :

Réduction du code standard pour les applications simples.
Fichiers sources autonomes avec configuration incorporée.
Publication AOT native activée par défaut.
Empaquetage automatique en tant qu’outils .NET.

Dans cet article, découvrez comment créer, configurer et utiliser efficacement des applications basées sur des fichiers.

Directives prises en charge

Les applications basées sur des fichiers utilisent des directives préfixées #: pour configurer la build et exécuter l’application. Les directives prises en charge sont les suivantes : #:package, , #:project#:property, et #:sdk. Placez ces directives en haut du fichier C#.

`#:package`

Ajoute une référence de package NuGet à votre application.

#:package Newtonsoft.Json
#:package Serilog version="3.1.1"

`#:project`

Fait référence à un autre fichier ou répertoire projet qui contient un fichier projet.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Définit une valeur de propriété MSBuild.

#:property TargetFramework=net10.0
#:property PublishAot=false

`#:sdk`

Spécifie le Kit de développement logiciel (SDK) à utiliser. La valeur par défaut est Microsoft.NET.Sdk.

#:sdk Microsoft.NET.Sdk.Web

Commandes CLI

L’interface CLI .NET fournit une prise en charge complète des applications basées sur des fichiers via des commandes familières.

Exécuter des applications

Exécutez une application basée sur des fichiers directement à l’aide de la dotnet run commande :

dotnet run file.cs

Vous pouvez également utiliser la syntaxe abrégée :

dotnet file.cs

Passer des arguments

Transmettez des arguments à votre application de plusieurs façons :

dotnet run file.cs -- arg1 arg2

Arguments après -- sont transmis à votre application. Sans --, les arguments passent à la dotnet run commande :

dotnet run file.cs arg1 arg2

Toutefois, avec la syntaxe abrégée, tous les arguments vont à votre application :

dotnet file.cs arg1 arg2

Générer des applications

Compilez votre application basée sur des fichiers à l’aide de la dotnet build commande :

dotnet build file.cs

Le Kit de développement logiciel (SDK) génère un projet temporaire et génère votre application.

Nettoyer les sorties de build

Supprimez les artefacts de build à l’aide de la dotnet clean commande :

dotnet clean file.cs

Nettoyez toutes les applications basées sur des fichiers dans un répertoire :

dotnet clean file-based-apps

Publier des applications

Créez un package de déploiement à l’aide de la dotnet publish commande :

dotnet publish file.cs

Les applications basées sur des fichiers permettent la publication AOT native par défaut, produisant des exécutables autonomes optimisés.

Empaqueter en tant qu’outil

Empaqueter votre application basée sur des fichiers en tant qu’outil .NET à l’aide de la dotnet pack commande :

dotnet pack file.cs

Les applications basées sur fichier sont définies PackAsTool=true par défaut.

Convertir en projet

Convertissez votre application basée sur des fichiers en projet traditionnel à l’aide de la dotnet project convert commande :

dotnet project convert file.cs

Cette commande crée un fichier .csproj avec des propriétés équivalentes au SDK. Toutes les # directives sont supprimées du .cs fichier et transformées en éléments dans le fichier correspondant .csproj .

Restaurer les dépendances

Restaurez les packages NuGet référencés dans votre fichier à l’aide de la dotnet restore commande :

dotnet restore file.cs

La restauration s’exécute implicitement lorsque vous générez ou exécutez votre application.

Éléments inclus par défaut

Les applications basées sur des fichiers incluent automatiquement des types de fichiers spécifiques pour la compilation et l’empaquetage.

Par défaut, les éléments suivants sont inclus :

Le fichier unique C# lui-même.
Fichiers de ressources ResX dans le même répertoire.

Les kits SDK différents incluent d’autres types de fichiers :

Microsoft.NET.Sdk.Web inclut des *.json fichiers de configuration.
D’autres kits SDK spécialisés peuvent inclure d’autres modèles.

Publication AOT native

Par défaut, les applications basées sur des fichiers activent la compilation anticipée native (AOT). Cette fonctionnalité produit des exécutables autonomes optimisés avec un démarrage plus rapide et une empreinte mémoire plus faible.

Si vous devez désactiver AOT natif, utilisez le paramètre suivant :

#:property PublishAot=false

Pour plus d’informations sur le déploiement AOT natif, consultez Déploiement AOT natif.

Secrets utilisateur

Les applications basées sur des fichiers génèrent un ID de secrets utilisateur stable en fonction d’un hachage du chemin d’accès complet du fichier. Cet ID vous permet de stocker la configuration sensible séparément de votre code source.

Accédez aux secrets utilisateur de la même façon que les projets traditionnels :

dotnet user-secrets set "ApiKey" "your-secret-value" --project file.cs

Pour plus d’informations, consultez Stockage sécurisé des secrets d’application dans le développement.

Profils de lancement

Les applications basées sur des fichiers prennent en charge les profils de lancement pour configurer la façon dont l’application s’exécute pendant le développement. Au lieu de placer des profils de lancement dans Properties/launchSettings.jsondes applications basées sur des fichiers, vous pouvez utiliser un fichier de paramètres de lancement plat nommé [ApplicationName].run.json dans le même répertoire que le fichier source.

Fichier de paramètres de lancement plat

Créez un fichier de paramètres de lancement nommé après votre application. Par exemple, si votre application basée sur des fichiers est app.cs, créez app.run.json dans le même répertoire :

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Plusieurs applications basées sur des fichiers

Lorsque vous avez plusieurs applications basées sur des fichiers dans le même répertoire, chaque application peut avoir son propre fichier de paramètres de lancement :

📁 myapps/
├── foo.cs
├── foo.run.json
├── bar.cs
└── bar.run.json

Sélection de profil

L’interface CLI .NET sélectionne les profils de lancement à l’aide de la priorité suivante :

Profil spécifié par l’option --launch-profile .
Profil spécifié par la variable d’environnement DOTNET_LAUNCH_PROFILE .
Premier profil défini dans le fichier de paramètres de lancement.

Pour exécuter avec un profil spécifique :

dotnet run app.cs --launch-profile https

Paramètres de lancement traditionnels

Les applications basées sur des fichiers prennent également en charge le fichier traditionnel Properties/launchSettings.json . Si les deux fichiers existent, l’emplacement traditionnel est prioritaire. Si les deux fichiers sont présents, l’interface CLI .NET consigne un avertissement pour clarifier le fichier utilisé.

Exécution du shell

Activez le lancement direct d’applications de type fichier sur des systèmes Unix à l’aide d’une ligne shebang et d’autorisations exécutables.

Ajoutez un shebang en haut de votre fichier :

#!/usr/bin/env dotnet
#:package Spectre.Console

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

Rendez le fichier exécutable :

chmod +x file.cs

Exécutez directement :

./file.cs

Fichiers de build implicites

Les applications basées sur des fichiers respectent les fichiers de configuration MSBuild et NuGet dans le même répertoire ou les mêmes répertoires parents. Ces fichiers affectent la façon dont le Kit de développement logiciel (SDK) génère votre application. Gardez à l’esprit ces fichiers lors de l’organisation de vos applications basées sur des fichiers.

`Directory.Build.props`

Définit les propriétés MSBuild qui s’appliquent à tous les projets d’une arborescence de répertoires. Les applications basées sur des fichiers héritent de ces propriétés.

`Directory.Build.targets`

Définit les cibles MSBuild et la logique de génération personnalisée. Les applications basées sur des fichiers exécutent ces cibles pendant la compilation.

`Directory.Packages.props`

Active la gestion centralisée des packages pour les dépendances NuGet. Les applications basées sur des fichiers peuvent utiliser des versions de package gérées de manière centralisée.

`nuget.config`

Configure les sources et paramètres du package NuGet. Les applications basées sur des fichiers utilisent ces configurations lors de la restauration des packages.

`global.json`

Spécifie la version du Kit de développement logiciel (SDK) .NET à utiliser. Les applications basées sur des fichiers respectent cette sélection de version.

Mise en cache des builds

Le Kit de développement logiciel (SDK) .NET met en cache les sorties de build pour améliorer les performances sur les builds suivantes. Les applications basées sur des fichiers participent à ce système de mise en cache.

Comportement du cache

Le SDK met en cache les sorties de build en fonction des points suivants :

Contenu du fichier source.
Configuration d'une directive.
Version du SDK.
Fichiers de build implicites.

La mise en cache améliore les performances de build, mais peut entraîner une confusion quand :

Les modifications apportées aux fichiers de build implicites ne déclenchent pas de reconstructions.
Le déplacement de fichiers vers différents répertoires n’invalide pas le cache.

Solutions de contournement

Exécutez une build complète à l’aide de l’indicateur --no-cache :
```
dotnet build file.cs --no-cache
```
Forcer une compilation propre pour éviter le cache :
```
dotnet clean file.cs
dotnet build file.cs
```

Recommandations relatives à la disposition des dossiers

Organisez soigneusement vos applications basées sur des fichiers pour éviter les conflits avec les projets traditionnels et les fichiers de build implicites.

Éviter les cônes de fichier projet

Ne placez pas d’applications basées sur des fichiers dans la structure de répertoires d’un .csproj projet. Les fichiers et paramètres de build implicites du fichier projet peuvent interférer avec votre application basée sur des fichiers.

❌ Non recommandé :

📁 MyProject/
├── MyProject.csproj
├── Program.cs
└──📁 scripts/
    └── utility.cs  // File-based app - bad location

✅ Recommandé:

📁 MyProject/
├── MyProject.csproj
└── Program.cs
📁 scripts/
└── utility.cs  // File-based app - good location

Gardez à l’esprit les fichiers implicites

Les fichiers de build implicites dans les répertoires parents affectent toutes les applications basées sur des fichiers dans les sous-répertoires. Créez des répertoires isolés pour les applications basées sur des fichiers lorsque vous avez besoin de différentes configurations de build.