dotnet-watch - Man Page

This article applies to: ✔️ .NET Core 3.1 SDK and later versions

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

dotnet watch -?|-h|--help

The dotnet watch command is a file watcher. When it detects a change, it runs the dotnet run command or a specified dotnet command. If it runs dotnet run, and the change is supported for hot reload, it hot reloads the specified application. If the change isn’t supported, it restarts the application. This process enables fast iterative development from the command line.

While running dotnet watch, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell. This feature is available only while the app is running. For example, if you run dotnet watch on a console app that ends before you press Ctrl+R, pressing Ctrl+R has no effect. However, in that case dotnet watch is still watching files and will restart the app if a file is updated.

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

• <command>

  In .NET 7 SDK and earlier, dotnet watch can run any command that is dispatched via the dotnet executable, such as built-in CLI commands and global tools. If you can run dotnet <command>, you can run dotnet watch <command>.

  In .NET 8 SDK and later, dotnet watch can run dotnet run, dotnet build, or dotnet test. Specify run, build, or test for <command>.

  If the child command isn’t specified, the default is run for dotnet run.

• <forwarded arguments>

  Arguments provided after a double dash (--) are passed to the child dotnet process. If you’re running dotnet watch run, these arguments are options for dotnet run. If you’re running dotnet watch test, these arguments are options for dotnet test.

• --list

  Lists all discovered files without starting the watcher.

• --no-hot-reload

  Suppress hot reload for supported apps.

• --non-interactive

  Runs dotnet watch in non-interactive mode. Use this option to prevent console input from being requested. When hot reload is enabled and a rude edit is detected, dotnet watch restarts the app. Available since .NET 7 SDK.

• --project <PATH>

  Specifies the path of the project file to run (folder only or including the project file name). If not specified, it defaults to the current directory.

• -q|--quiet

  Suppresses all output that is generated by the dotnet watch command except warnings and errors. The option is not passed on to child commands. For example, output from dotnet restore and dotnet run continues to be output.

• -v|--verbose

  Shows verbose output for debugging.

• --version

  Shows the version of dotnet watch.

• --

  The double-dash option (`–') can be used to delimit dotnet watch options from arguments that will be passed to the child process. Its use is optional. When the double-dash option isn’t used, dotnet watch considers the first unrecognized argument to be the beginning of arguments that it should pass into the child dotnet process.

dotnet watch uses the following environment variables:

• DOTNET_HOTRELOAD_NAMEDPIPE_NAME

  This value is configured by dotnet watch when the app is to be launched, and it specifies the named pipe.

• DOTNET_USE_POLLING_FILE_WATCHER

  When set to 1 or true, dotnet watch uses a polling file watcher instead of <xref:System.IO.FileSystemWatcher?displayProperty=nameWithType>. Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. The <xref:Microsoft.Extensions.FileProviders.PhysicalFileProvider> class uses DOTNET_USE_POLLING_FILE_WATCHER to determine whether the <xref:Microsoft.Extensions.FileProviders.PhysicalFileProvider.Watch%2A?displayProperty=nameWithType> method will rely on the <xref:Microsoft.Extensions.FileProviders.Physical.PollingFileChangeToken>.

• DOTNET_WATCH

  dotnet watch sets this variable to 1 on all child processes that it launches.

• DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

  As part of dotnet watch, the browser refresh server mechanism reads this value to determine the WebSocket host environment. The value 127.0.0.1 is replaced by localhost, and the http:// and https:// schemes are replaced with ws:// and wss:// respectively.

• DOTNET_WATCH_ITERATION

  dotnet watch sets this variable to 1 and increments by one each time a file is changed and the command restarts or hot reloads the application.

• DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

  When set to 1 or true, dotnet watch won’t refresh browsers when it detects file changes.

• DOTNET_WATCH_SUPPRESS_EMOJIS

  With the .NET SDK 6.0.300 and later, dotnet watch emits non-ASCII characters to the console, as shown in the following example:

  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...

  On certain console hosts, these characters may appear garbled. To avoid seeing garbled characters, set this variable to 1 or true.

• DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

  When set to 1 or true, dotnet watch won’t launch or refresh browsers for web apps that have launchBrowser configured in launchSettings.json.

• DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

  By default, dotnet watch optimizes the build by avoiding certain operations, such as running restore or re-evaluating the set of watched files on every file change. If this variable is set to 1 or true, these optimizations are disabled.

• DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

  When set to 1 or true, dotnet watch won’t do special handling for static content files. dotnet watch sets MSBuild property DotNetWatchContentFiles to false.

• DOTNET_WATCH_RESTART_ON_RUDE_EDIT

  When set to 1 or true, dotnet watch will always restart on rude edits instead of asking.

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

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

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

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

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)?

• Run dotnet run for the project in the current directory whenever source code changes:

  dotnet watch

  Or:

  dotnet watch run

• Run dotnet test for the project in the current directory whenever source code changes:

  dotnet watch test

• Run dotnet run --project ./HelloWorld.csproj whenever source code changes:

  dotnet watch run --project  ./HelloWorld.csproj

• Run dotnet run -- arg0 for the project in the current directory whenever source code changes:

  dotnet watch run -- arg0

  Or:

  dotnet watch -- run arg0

• Tutorial: Develop ASP.NET Core apps using a file watcher
• Hot reload in Visual Studio
• Hot reload supported apps
• Hot reload supported code changes
• Hot reload test execution
• Hot reload support for ASP.NET Core