Partager via

dotnet watch

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

Nom

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

Synopsis

dotnet watch [<command>]
  [--artifacts-path <ARTIFACTS_DIR>] [--disable-build-servers]
  [--list] [--no-hot-reload] [--no-self-contained]
  [--non-interactive] [--project <PROJECT>] [--sc|--self-contained]
  [-q|--quiet] [-v|--verbose] [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Descriptif

La dotnet watch commande est un observateur de fichiers. Lorsqu’il détecte une modification, il exécute la dotnet run commande ou une commande spécifiée dotnet . S’il s’exécute dotnet runet que la modification est prise en charge pour le 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 dotnet watch, vous pouvez forcer l’application à reconstruire 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 d’appuyer sur Ctrl+R, l’appui sur Ctrl+R n’a aucun effet. Toutefois, dans ce cas dotnet watch , il surveille toujours les fichiers et redémarre l’application si un fichier est mis à jour.

Compression des réponses

Si dotnet watch elle s’exécute pour une application qui utilise la compression de réponse, l’outil ne peut pas injecter le script d’actualisation du navigateur. La version .NET 7 et ultérieure de l’outil affiche un message d’avertissement comme suit :

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

Impossible de configurer l’injection de script d’actualisation du navigateur sur la réponse. Cela peut avoir été dû à l’encodage de contenu de la réponse : « br ». Envisagez de désactiver la compression de réponse.

En guise d’alternative à la désactivation de la compression de réponse, ajoutez manuellement la référence JavaScript d’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>

    Dans le Kit de développement logiciel (SDK) .NET 7 et versions antérieures, dotnet watch vous pouvez exécuter n’importe quelle commande distribuée via l’exécutable dotnet , comme les commandes CLI intégrées et les outils globaux. Si vous pouvez exécuter dotnet <command>, vous pouvez exécuter dotnet watch <command>.

    Dans le Kit de développement logiciel (SDK) .NET 8 et versions ultérieures, dotnet watch peuvent exécuter dotnet run, dotnet buildou dotnet test. Spécifiez run, buildou test pour <command>.

    Si la commande enfant n’est pas spécifiée, la valeur par défaut est run pour dotnet run.

  • <forwarded arguments>

    Arguments fournis après le passage d’un double tiret (--) au processus enfant dotnet . Si vous exécutez dotnet watch run, ces arguments sont des options pour l’exécution dotnet. Si vous exécutez dotnet watch test, ces arguments sont des options pour le test dotnet.

Options

  • --artifacts-path <ARTIFACTS_DIR>

    Tous les fichiers de sortie de build de la commande exécutée vont dans les sous-dossiers sous le chemin spécifié, séparés par projet. Pour plus d’informations, consultez disposition de sortie d’artefacts. Disponible depuis le Kit de développement logiciel (SDK) .NET 8.

  • --disable-build-servers

    Force la commande à ignorer tous les serveurs de build persistants. Cette option offre un moyen cohérent de désactiver toute utilisation de la mise en cache de build, ce qui force une build à partir de zéro. Une build qui ne repose pas sur des caches est utile quand les caches peuvent être endommagés ou incorrects pour une raison quelconque. Disponible depuis le SDK .NET 7.

  • --list

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

  • --no-self-contained

    Publiez votre application en tant qu’application dépendante de l’infrastructure. Un runtime .NET compatible doit être installé sur l’ordinateur cible pour exécuter votre application.

  • --no-hot-reload

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

  • --non-interactive

    S’exécute dotnet watch en mode non interactif. Utilisez cette option pour empêcher l’entrée de la console d’être demandée. Lorsque le rechargement à chaud est activé et qu’une modification grossière est détectée, dotnet watch redémarre l’application. Disponible depuis le SDK .NET 7.

  • --project <PATH>

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

  • --sc|--self-contained

    Publiez le runtime .NET avec votre application afin que le runtime n’ait pas besoin d’être installé sur l’ordinateur cible.

  • -q|--quiet

    Supprime toutes les sorties générées par la dotnet watch commande, à l’exception des avertissements et des erreurs. L’option n’est pas transmise aux commandes enfants. Par exemple, la sortie depuis dotnet restore et dotnet run continue d’être sortie.

  • -v|--verbose

    Affiche une sortie détaillée pour le débogage.

  • --version

    Affiche la version de dotnet watch.

  • --

    L’option double-tiret ('--') peut être utilisée pour délimiter dotnet watch les options des arguments qui seront transmis au processus enfant. Son utilisation est facultative. Lorsque l’option double-tiret n’est pas utilisée, dotnet watch considère le premier argument non reconnu comme le début des arguments qu’il doit passer dans le processus enfant dotnet .

  • -?|-h|--help

    Imprime une description de l’utilisation de la commande.

Variables d'environnement

dotnet watch utilise les variables d’environnement suivantes :

  • DOTNET_HOTRELOAD_NAMEDPIPE_NAME

    Cette valeur est configurée dotnet watch lorsque l’application doit être lancée et spécifie le canal nommé.

  • DOTNET_USE_POLLING_FILE_WATCHER

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

  • DOTNET_WATCH

    dotnet watch définit cette variable 1 sur tous les processus enfants qu’il 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 http://https:// schémas sont remplacés ws:// par et wss:// respectivement.

  • DOTNET_WATCH_ITERATION

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

  • DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

    Lorsqu’il est défini 1 sur ou true, dotnet watch n’actualise pas les navigateurs lorsqu’il détecte les modifications de fichier.

  • DOTNET_WATCH_SUPPRESS_EMOJIS

    Avec le Kit de développement logiciel (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 apparaître garbrés. Pour éviter de voir des caractères garbrés, définissez cette variable sur 1 ou true.

  • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

    Lorsqu’il est défini 1 sur ou true, dotnet watch ne lance pas ou n’actualise pas les navigateurs pour les applications web qui ont launchBrowser été configurées dans launchSettings.json.

  • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

    Par défaut, dotnet watch optimise la build en évitant certaines opérations, telles que l’exécution de la restauration ou la réévaluation de l’ensemble des fichiers surveillés sur chaque modification de fichier. Si cette variable est définie 1 ou truesi ces optimisations sont désactivées.

  • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

    Lorsqu’il est défini 1 sur ou true, dotnet watch ne gère pas de manière spéciale les fichiers de contenu statiques. dotnet watch définit la propriété DotNetWatchContentFiles MSBuild sur false.

  • DOTNET_WATCH_RESTART_ON_RUDE_EDIT

    Lorsque la valeur est définie 1 ou true, dotnet watch redémarre toujours sur les modifications grossières au lieu de demander.

Fichiers surveillés par défaut

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

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

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

Par défaut, .configet les fichiers.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 de surveillance ou supprimés de la liste en modifiant le fichier projet. Les fichiers peuvent être spécifiés individuellement ou à l’aide de modèles glob.

Regarder des fichiers supplémentaires

Vous pouvez observer d’autres fichiers en ajoutant des éléments au Watch groupe. 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 et dossiers spécifiés

Utilisez l’attribut Watch="false" pour ignorer les fichiers spécifiés. Utilisez la DefaultItemExcludes propriété pour ignorer les dossiers ou les fichiers d’être surveillés.

Pour empêcher dotnet watch l’observation des fichiers, utilisez les éléments et EmbeddedResource les Compile éléments avec l’attributWatch="false", comme illustré 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>

À compter de .NET 10, utilisez la DefaultItemExcludes propriété pour exclure des dossiers entiers ou des modèles de fichiers d’être surveillés par dotnet watch. Cette approche est utile lorsque vous souhaitez exclure des fichiers qui ne sont pas pertinents pour la compilation ou les fichiers qui déclenchent des redémarrages indésirables ou des rechargements.

Par exemple, les fichiers dans le App_Data dossier des applications ASP.NET Core peuvent changer pendant l’exécution de l’application, ce qui entraîne des rechargements de pages inutiles. Excluez ce dossier d’être surveillé :

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/App_Data/**</DefaultItemExcludes>
</PropertyGroup>

Excluez plusieurs modèles en les séparant par des points-virgules :

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/App_Data/**;**/temp/**;**/*.log</DefaultItemExcludes>
</PropertyGroup>

La DefaultItemExcludes propriété affecte tous les types d’éléments par défaut, comme Compile et EmbeddedResource. L’attribut Watch="false" fournit un contrôle plus fin sur des fichiers spécifiques ou des références de projet.

Pour plus d’informations, consultez la référence DefaultItemExcludes.

Configuration avancée

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

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

Rechargement à chaud

À compter du Kit de développement logiciel (SDK) .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 à le reconstruire et à le redémarrer. Les modifications peuvent être apportées aux fichiers de code ou aux ressources statiques, telles que les fichiers feuille de style et les 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 Les frameworks et scénarios d’application .NET pris en charge.

Modifications grossières

Lorsqu’un fichier est modifié, dotnet watch détermine si l’application peut être rechargée à chaud. S’il ne peut pas être rechargé à chaud, la modification est appelée une modification grossière et dotnet watch vous demande si vous souhaitez 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 les modifications appliquées.
  • Toujours : redémarre l’application et n’invite plus les modifications grossières.
  • Jamais : laisse l’application en cours d’exécution sans les modifications appliquées et n’invite plus les modifications grossières.

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

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

dotnet watch --no-hot-reload

Examples

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

    dotnet watch

    Ou:

    dotnet watch run

  • Exécutez dotnet test 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 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

  • Last updated on