dotnet watch run

  • Article

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

Nom

dotnet watch - Redémarre ou recharge à chaud l’application spécifiée, ou bien exécute une commande dotnet spécifiée lorsque des modifications sont détectées dans le code source.

Synopsis

dotnet watch [<command>]
  [--list]
  [--no-hot-reload] [--non-interactive]
  [--project <PROJECT>]
  [-q|--quiet] [-v|--verbose]
  [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Description

La commande dotnet watch est un observateur de fichier. Quand une modification est détectée, elle exécute la commande dotnet run ou une commande dotnet spécifiée. Si elle exécute dotnet run et que la modification est prise en charge pour un rechargement à chaud, elle recharge à chaud l’application spécifiée. Si la modification n’est pas prise en charge, elle redémarre l’application. Ce processus permet un développement itératif rapide à partir de la ligne de commande.

Lors de l’exécution de dotnet watch, vous pouvez forcer l’application à se regénérer et à redémarrer en appuyant sur Ctrl+R dans l’interpréteur de commandes. Cette fonctionnalité est disponible uniquement pendant l’exécution de l’application. Par exemple, si vous exécutez dotnet watch sur une application console qui se termine avant que vous appuyiez sur Ctrl+R, l’appui sur Ctrl+R ne produit aucun effet. En revanche, dans ce cas, dotnet watch est encore en train d’observer les fichiers et redémarre l’application si un fichier est mis à jour.

Compression des réponses

Si dotnet watch s’exécute pour une application qui utilise la compression des réponses, l’outil ne peut pas injecter le script d’actualisation du navigateur. .NET 7 et les versions ultérieures de l’outil affichent un message d’avertissement semblable au suivant :

Avertissement : Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]

Impossible de configurer l’injection de script d’actualisation du navigateur sur la réponse. Ce problème peut être dû à la valeur Content-Encoding de la réponse : 'br'. Envisagez de désactiver la compression des réponses.

Au lieu de désactiver la compression des réponses, ajoutez manuellement la référence JavaScript de l’actualisation du navigateur aux pages de l’application :

@if (Environment.GetEnvironmentVariable("__ASPNETCORE_BROWSER_TOOLS") is not null)
{
    <script src="/_framework/aspnetcore-browser-refresh.js"></script>
}

Arguments

  • command

    dotnet watch peut exécuter toute commande distribuée par le biais de l’exécutable dotnet, comme les outils globaux et les commandes CLI intégrées. Si vous pouvez exécuter dotnet <command>, vous pouvez exécuter dotnet watch <command>. Si la commande enfant n’est pas spécifiée, la valeur par défaut est run pour dotnet run.

  • forwarded arguments

    Les arguments fournis après un double tiret (--) sont passés au processus dotnet enfant. Si vous exécutez dotnet watch run, ces arguments sont des options pour dotnet run. Si vous exécutez dotnet watch test, ces arguments sont des options pour dotnet test.

Options

  • --list

    Liste tous les fichiers découverts sans démarrer l’observateur.

  • --no-hot-reload

    Supprimez le rechargement à chaud pour les applications prises en charge.

  • --non-interactive

    Exécute dotnet watch en mode non interactif. Utilisez cette option pour empêcher toute demande d’entrée de console. Lorsque le rechargement à chaud est activé et qu’une modification non applicable est détectée, dotnet watch redémarre l’application. Disponible depuis le SDK .NET 7.

  • --project <PATH>

    Spécifie le chemin du fichier projet à exécuter (dossier uniquement ou nom du fichier projet compris). Si aucune valeur n’est spécifiée, le répertoire actif est utilisé par défaut.

  • -q|--quiet

    Supprime toute la sortie générée par la commande dotnet watch, à l’exception des avertissements et des erreurs. L’option n’est pas passée aux commandes enfants. Par exemple, la sortie de dotnet restore et dotnet run continue d’être générée.

  • -v|--verbose

    Affiche la sortie en clair pour le débogage.

  • --version

    Affiche la version de dotnet watch.

  • --

    L’option de double tiret ('--') peut être utilisée pour délimiter les options dotnet watch des arguments passés au processus enfant. Son utilisation est facultative. Lorsque l’option de double tiret n’est pas utilisée, dotnet watch considère que le premier argument non reconnu correspond au début des arguments à passer au processus dotnet enfant.

Variables d'environnement

dotnet watch utilise les variables d’environnement suivantes :

  • DOTNET_HOTRELOAD_NAMEDPIPE_NAME

    Cette valeur est configurée par dotnet watch quand l’application est sur le point d’être lancée, et elle spécifie le canal nommé.

  • DOTNET_USE_POLLING_FILE_WATCHER

    Quand la valeur est 1 ou true, dotnet watch utilise un observateur de fichier d’interrogation au lieu de System.IO.FileSystemWatcher. L’interrogation est nécessaire pour certains systèmes de fichiers, tels que les partages réseau, les volumes montés par Docker et d’autres systèmes de fichiers virtuels. La classe PhysicalFileProvider utilise DOTNET_USE_POLLING_FILE_WATCHER pour déterminer si la méthode PhysicalFileProvider.Watch s’appuie sur PollingFileChangeToken.

  • DOTNET_WATCH

    dotnet watch définit cette variable sur 1 sur tous les processus enfants qu’elle lance.

  • DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

    Dans le cadre de dotnet watch, le mécanisme du serveur d’actualisation du navigateur lit cette valeur pour déterminer l’environnement hôte WebSocket. La valeur 127.0.0.1 est remplacée par localhost et les schémas http:// et https:// sont remplacés respectivement par ws:// et wss://.

  • DOTNET_WATCH_ITERATION

    dotnet watch définit cette variable sur 1 et l’incrémente de 1 chaque fois qu’un fichier est modifié et que la commande redémarre ou recharge à chaud l’application.

  • DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

    Si la valeur est 1 ou true, dotnet watch n’actualise pas les navigateurs lorsqu’elle détecte des modifications de fichier.

  • DOTNET_WATCH_SUPPRESS_EMOJIS

    Avec le SDK .NET 6.0.300 et versions ultérieures, dotnet watch émet des caractères non-ASCII dans la console, comme illustré dans l’exemple suivant :

    dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload.
  💡 Press "Ctrl + R" to restart.
dotnet watch 🔧 Building...
dotnet watch 🚀 Started
dotnet watch ⌚ Exited
dotnet watch ⏳ Waiting for a file to change before restarting dotnet...

    Sur certains hôtes de console, ces caractères peuvent sembler confus. Pour éviter de voir des caractères confus, définissez cette variable sur 1 ou true.

  • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

    Si la valeur est 1 ou true, dotnet watch ne lance pas ou n’actualise pas les navigateurs pour les applications web pour lesquelles launchBrowser est configuré dans launchSettings.json.

  • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

    Par défaut, dotnet watch optimise la génération en évitant certaines opérations, comme l’exécution d’une restauration ou la réévaluation de l’ensemble des fichiers observés à chaque modification de fichier. Si cette variable est définie sur 1 ou true, ces optimisations sont désactivées.

  • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

    Si la valeur est 1 ou true, dotnet watch n’effectue pas de gestion spéciale pour les fichiers de contenu statique. dotnet watch définit la propriété MSBuild DotNetWatchContentFiles sur false.

  • DOTNET_WATCH_RESTART_ON_RUDE_EDIT

    Lorsque la valeur est définie sur 1 ou true, dotnet watch redémarre toujours en cas de modifications non applicables au lieu de poser la question.

Fichiers observés par défaut

dotnet watch observe tous les éléments du groupe d’éléments Watch dans le fichier projet. Par défaut, ce groupe inclut tous les éléments des groupes Compile et EmbeddedResource. dotnet watch analyse également la totalité du graphe des références de projet et observe tous les fichiers au sein de ces projets.

Par défaut, les groupes Compile et EmbeddedResource incluent tous les fichiers correspondant aux modèles Glob suivants :

  • **/*.cs
  • *.csproj
  • **/*.resx
  • Fichiers de contenu dans les applications web : wwwroot/**

Par défaut, les fichiers .config et .json ne déclenchent pas de redémarrage dotnet watch, car le système de configuration dispose de ses propres mécanismes pour gérer les modifications de configuration.

Les fichiers peuvent être ajoutés à la liste d’observation ou supprimés de la liste en modifiant le fichier projet. Vous pouvez spécifier des fichiers individuellement ou en utilisant des modèles Glob.

Observer des fichiers supplémentaires

Vous pouvez observer d’autres fichiers en ajoutant des éléments au groupe Watch. Par exemple, le balisage suivant étend ce groupe pour inclure des fichiers JavaScript :

<ItemGroup>
  <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>

Ignorer les fichiers spécifiés

dotnet watch ignore les éléments Compile et EmbeddedResource qui ont l’attribut Watch="false", comme indiqué dans l’exemple suivant :

<ItemGroup>
  <Compile Update="Generated.cs" Watch="false" />
  <EmbeddedResource Update="Strings.resx" Watch="false" />
</ItemGroup>

dotnet watch ignore les références de projet qui ont l’attribut Watch="false", comme indiqué dans l’exemple suivant :

<ItemGroup>
  <ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>

Configuration avancée

dotnet watch effectue une génération au moment du design pour rechercher les éléments à observer. Lorsque cette génération est exécutée, dotnet watch définit la propriété DotNetWatchBuild=true. Cette propriété peut être utilisée comme indiqué dans l’exemple suivant :

<ItemGroup Condition="'$(DotNetWatchBuild)'=='true'">
  <!-- only included in the project when dotnet-watch is running -->
</ItemGroup>

Rechargement à chaud

À compter de .NET 6, dotnet watch inclut la prise en charge du rechargement à chaud. Le rechargement à chaud est une fonctionnalité qui vous permet d’appliquer des modifications à une application en cours d’exécution sans avoir à la regénérer et à la redémarrer. Les modifications peuvent concerner des fichiers de code ou des ressources statiques, telles que des fichiers de feuille de style et des fichiers JavaScript. Cette fonctionnalité simplifie l’expérience de développement local, car elle fournit des commentaires immédiats lorsque vous modifiez votre application.

Pour plus d’informations sur les types d’applications et les versions .NET qui prennent en charge le rechargement à chaud, consultez Frameworks et scénarios d’application .NET pris en charge.

Modifications non applicables

Lorsqu’un fichier est modifié, dotnet watch détermine si l’application peut être rechargée à chaud. Si elle ne peut pas être rechargée à chaud, la modification est appelée modification non applicable et dotnet watch vous demande si vous voulez redémarrer l’application :

dotnet watch ⌚ Unable to apply hot reload because of a rude edit.
  ❔ Do you want to restart your app - Yes (y) / No (n) / Always (a) / Never (v)?
  • Oui : redémarre l’application.
  • Non : laisse l’application en cours d’exécution sans appliquer les modifications.
  • Toujours : redémarre l’application et n’invite plus à la redémarrer en cas de modification non applicable.
  • Jamais : laisse l’application en cours d’exécution sans appliquer les modifications et n’invite plus à la redémarrer en cas de modification non applicable.

Pour plus d’informations sur les types de modifications considérés comme des modifications non applicables, consultez Modifier le code et continuer le débogage et Modifications du code non prises en charge.

Pour désactiver le rechargement à chaud lorsque vous exécutez dotnet watch, utilisez l’option --no-hot-reload, comme indiqué dans l’exemple suivant :

dotnet watch --no-hot-reload

Exemples

  • Exécutez dotnet run pour le projet dans le répertoire actif chaque fois que le code source change :

    dotnet watch

    Ou :

    dotnet watch run

  • Exécutez dotnet test pour le projet dans le répertoire actif chaque fois que le code source change :

    dotnet watch test

  • Exécutez dotnet run --project ./HelloWorld.csproj chaque fois que le code source change :

    dotnet watch run --project  ./HelloWorld.csproj

  • Exécutez dotnet run -- arg0 pour le projet dans le répertoire actif chaque fois que le code source change :

    dotnet watch run -- arg0

    Ou :

    dotnet watch -- run arg0

Voir aussi