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

Arguments

       • <command>

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

         In .NET 8 SDK and later, dotnetwatch can run dotnetrun, dotnetbuild, or dotnettest.   Specify  run,
         build, or test for <command>.

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

       • <forwardedarguments>

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

Description

The dotnetwatch command is a file watcher. When it detects a change, it runs the dotnetrun command or
a specified dotnet command. If it runs dotnetrun, 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 dotnetwatch, you can force the app to rebuild and restart by pressing Ctrl+R in the com‐
mand shell. This feature is available only while the app is running. For example, if you run dotnetwatch on a console app that ends before you press Ctrl+R, pressing Ctrl+R has no effect. However, in
that case dotnetwatch is still watching files and will restart the app if a file is updated.

Responsecompression
If dotnetwatch 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 refer‐
ence to the app’s pages:

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

Dotnet Watch

Thisarticleappliesto: ✔️ .NET Core 3.1 SDK and later versions

Environment Variables

dotnetwatch uses the following environment variables:

• DOTNET_HOTRELOAD_NAMEDPIPE_NAME

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

• DOTNET_USE_POLLING_FILE_WATCHER

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

• DOTNET_WATCHdotnetwatch sets this variable to 1 on all child processes that it launches.

• DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

As part of dotnetwatch, the browser refresh server mechanism reads this value to determine the Web‐
Socket 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_ITERATIONdotnetwatch 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, dotnetwatch won’t refresh browsers when it detects file changes.

• DOTNET_WATCH_SUPPRESS_EMOJIS

With the .NET SDK 6.0.300 and later, dotnetwatch 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, dotnetwatch won’t launch or refresh browsers for web apps that have launch‐Browser configured in launchSettings.json.

• DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

By default, dotnetwatch 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, dotnetwatch won’t do special handling for static content files. dotnetwatch
sets MSBuild property DotNetWatchContentFiles to false.

• DOTNET_WATCH_RESTART_ON_RUDE_EDIT

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

Fileswatchedbydefaultdotnetwatch watches all items in the Watch item group in the project file. By default, this group in‐
cludes all items in the Compile and EmbeddedResource groups. dotnetwatch 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 pat‐
terns:

• **/*.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 sys‐
tem 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.

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

Ignorespecifiedfilesdotnetwatch will ignore Compile and EmbeddedResource items that have the Watch="false" attribute, as
shown in the following example:

dotnetwatch will ignore project references that have the Watch="false" attribute, as shown in the fol‐
lowing example:

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

HotReload
Starting in .NET 6, dotnetwatch includes support for hotreload. 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 lo‐
cal 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 frame‐
works and scenarios.

Rudeedits
When a file is modified, dotnetwatch determines if the app can be hot reloaded. If it can’t be hot re‐
loaded, the change is called a rudeedit and dotnetwatch 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 debug‐
ging and Unsupported changes to code.

To disable hot reload when you run dotnetwatch, use the --no-hot-reload option, as shown in the follow‐
ing example:

.NETCLIdotnetwatch--no-hot-reload

Examples

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

                dotnet watch

         Or:

                dotnet watch run

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

                dotnet watch test

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

                dotnet watch run --project  ./HelloWorld.csproj

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

                dotnet watch run -- arg0

         Or:

                dotnet watch -- run arg0

Name

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

Options

       • --list

         Lists all discovered files without starting the watcher.

       • --no-hot-reload

         Suppress hot reload for supported apps.

       • --non-interactive

         Runs  dotnetwatch  in  non-interactive mode.  Use this option to prevent console input from being re‐
         quested.  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 dotnetwatch command except warnings and errors.  The
         option is not passed on to child commands.  For example, output from dotnetrestore and dotnetrun con‐
         tinues to be output.

       • -v|--verbose

         Shows verbose output for debugging.

       • --version

         Shows the version of dotnetwatch.

       • --

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

Synopsis

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

              dotnet watch -?|-h|--help