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

Provided by: dotnet-host-8.0_8.0.11-0ubuntu1~22.04.1_amd64

dotnet watch

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

NAME

       dotnet-watch  -  Restarts  or  hot  reloads the specified application, or runs a specified
       dotnet command, when changes in source code are detected.

SYNOPSIS

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

              dotnet watch -?|-h|--help

DESCRIPTION

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.

Response compression
If dotnet watch runs for an app that uses response compression, the tool can’t inject the
browser refresh script. The .NET 7 and later version of the tool displays a warning
message like the following:

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

Unable to configure browser refresh script injection on the response. This may
have been caused by the response’s Content-Encoding: `br'. Consider disabling
response compression.

As an alternative to disabling response compression, manually add the browser refresh
JavaScript reference to the app’s pages:

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

ARGUMENTS

       • command

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

OPTIONS

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

ENVIRONMENT VARIABLES

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.

Files watched by default
dotnet watch watches all items in the Watch item group in the project file. By default,
this group includes all items in the Compile and EmbeddedResource groups. dotnet watch
also scans the entire graph of project references and watches all files within those
projects.

By default, the Compile and EmbeddedResource groups include all files matching the
following glob patterns:

• **/*.cs

• *.csproj

• **/*.resx

• Content files in web apps: wwwroot/**

By default, .config, and .json files don’t trigger a dotnet watch restart because the
configuration system has its own mechanisms for handling configuration changes.

Files can be added to the watch list or removed from the list by editing the project file.
Files can be specified individually or by using glob patterns.

Watch additional files
More files can be watched by adding items to the Watch group. For example, the following
markup extends that group to include JavaScript files:

Ignore specified files
dotnet watch will ignore Compile and EmbeddedResource items that have the Watch="false"
attribute, as shown in the following example:

dotnet watch will ignore project references that have the Watch="false" attribute, as
shown in the following example:

Advanced configuration
dotnet watch performs a design-time build to find items to watch. When this build is run,
dotnet watch sets the property DotNetWatchBuild=true. This property can be used as shown
in the following example:

Hot Reload
Starting in .NET 6, dotnet watch includes support for hot reload. Hot reload is a feature
that lets you apply changes to a running app without having to rebuild and restart it.
The changes may be to code files or static assets, such as stylesheet files and JavaScript
files. This feature streamlines the local development experience, as it gives immediate
feedback when you modify your app.

For information about app types and .NET versions that support hot reload, see Supported
.NET app frameworks and scenarios.

Rude edits
When a file is modified, dotnet watch determines if the app can be hot reloaded. If it
can’t be hot reloaded, the change is called a rude edit and dotnet watch asks if you want
to restart the app:

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

• Yes: Restarts the app.

• No: Leaves the app running without the changes applied.

• Always: Restarts the app and doesn’t prompt anymore for rude edits.

• Never: Leaves the app running without the changes applied and doesn’t prompt anymore for
rude edits.

For information about what kinds of changes are considered rude edits, see Edit code and
continue debugging and Unsupported changes to code.

To disable hot reload when you run dotnet watch, use the --no-hot-reload option, as shown
in the following example:

.NET CLI dotnet watch --no-hot-reload

EXAMPLES

       • 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