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@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
#:sdk Aspire.AppHost.Sdk@13.0.2

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 un fichier à l’aide de la dotnet run commande avec l’option --file :

dotnet run --file file.cs

Vous pouvez également utiliser la dotnet run commande suivie du nom du fichier :

dotnet run file.cs

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

dotnet file.cs

Passer des arguments

Transmettez des arguments à votre application en les plaçant après --:

dotnet run file.cs -- arg1 arg2

Sans --, les arguments passent à la dotnet run commande :

dotnet run 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 virtuel et génère votre application. Par défaut, la sortie de build est envoyée au répertoire temporaire du système sous <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Utilisez l’option --output avec la commande dotnet build pour spécifier un autre chemin. Pour définir un nouveau chemin de sortie par défaut, définissez la OutputPath propriété en haut de votre fichier à l’aide de la directive : #:property OutputPath=./output.

Nettoyer les sorties de build

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

dotnet clean file.cs

Supprimez le cache pour les applications basées sur des fichiers dans un répertoire :

dotnet clean file-based-apps

Utilisez l’option avec la --days commande précédente pour spécifier le nombre de jours pendant lesquels un dossier d’artefacts doit être inutilisé avant la suppression. Le nombre de jours par défaut est 30.

Publier des applications

Les applications basées sur des fichiers permettent la publication AOT native par défaut, produisant des exécutables autonomes optimisés. Désactivez cette fonctionnalité en ajoutant #:property PublishAot=false en haut de votre fichier.

Utilisez la dotnet publish commande pour créer un exécutable indépendant :

dotnet publish file.cs

L’emplacement par défaut de l’exécutable est un artifacts répertoire en regard du .cs fichier, avec un sous-répertoire nommé après l’application. Utilisez l’option --output avec la commande dotnet publish pour spécifier un autre chemin d’accè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. Désactivez ce paramètre en ajoutant #:property PackAsTool=false en haut de votre fichier.

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 effectue une copie du .cs fichier et crée un fichier avec des .csproj éléments, des propriétés et des références de package du SDK équivalents en fonction des directives du #: fichier d’origine. Les deux fichiers sont placés dans un répertoire nommé pour l’application en regard du fichier d’origine .cs , qui est laissé inchangé.

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

Par défaut, la restauration s’exécute implicitement lorsque vous générez ou exécutez votre application. Toutefois, vous pouvez passer --no-restore aux commandes dotnet build et dotnet run pour générer ou exécuter sans restaurer implicitement.

É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" --file file.cs

Répertoriez les secrets utilisateur pour les applications basées sur des fichiers :

dotnet user-secrets list --file file.cs

La dotnet user-secrets list commande imprime la valeur de vos secrets. Ne placez pas cette commande dans des scripts qui s’exécutent dans des contextes publics.

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

Note

Utilisez LF au lieu de CRLF lorsque vous ajoutez un shebang. N’incluez pas de boM dans le fichier.

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 résultats de build pour améliorer les performances des appels suivants de dotnet run. Ce système de mise en cache est unique pour les applications basées sur des fichiers.

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.
Existence et contenu implicites du fichier de build.

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

Effacez les artefacts de cache pour les applications basées sur des fichiers à l’aide de la commande suivante :

dotnet clean file-based-apps

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.