dotnet watch
This article applies to: ✔️ .NET Core 3.1 SDK and later versions
dotnet watch
- Restarts or hot reloads the specified application, or runs a specified dotnet command, when changes in source code are detected.
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 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>
}
<command>
In .NET 7 SDK and earlier,
dotnet watch
can run any command that is dispatched via thedotnet
executable, such as built-in CLI commands and global tools. If you can rundotnet <command>
, you can rundotnet watch <command>
.In .NET 8 SDK and later,
dotnet watch
can rundotnet run
,dotnet build
, ordotnet test
. Specifyrun
,build
, ortest
for<command>
.If the child command isn't specified, the default is
run
fordotnet run
.<forwarded arguments>
Arguments provided after a double dash (
--
) are passed to the childdotnet
process. If you're runningdotnet watch run
, these arguments are options for dotnet run. If you're runningdotnet 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 fromdotnet restore
anddotnet 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 childdotnet
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
ortrue
,dotnet watch
uses a polling file watcher instead of System.IO.FileSystemWatcher. Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. The PhysicalFileProvider class usesDOTNET_USE_POLLING_FILE_WATCHER
to determine whether the PhysicalFileProvider.Watch method will rely on the PollingFileChangeToken.DOTNET_WATCH
dotnet watch
sets this variable to1
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 value127.0.0.1
is replaced bylocalhost
, and thehttp://
andhttps://
schemes are replaced withws://
andwss://
respectively.DOTNET_WATCH_ITERATION
dotnet watch
sets this variable to1
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
ortrue
,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
ortrue
.DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER
When set to
1
ortrue
,dotnet watch
won't launch or refresh browsers for web apps that havelaunchBrowser
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 to1
ortrue
, these optimizations are disabled.DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING
When set to
1
ortrue
,dotnet watch
won't do special handling for static content files.dotnet watch
sets MSBuild propertyDotNetWatchContentFiles
tofalse
.DOTNET_WATCH_RESTART_ON_RUDE_EDIT
When set to
1
ortrue
,dotnet watch
will always restart on rude edits instead of asking.
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.
More files can be watched by adding items to the Watch
group. For example, the following markup extends that group to include JavaScript files:
<ItemGroup>
<Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>
dotnet watch
will ignore Compile
and EmbeddedResource
items that have the Watch="false"
attribute, as shown in the following example:
<ItemGroup>
<Compile Update="Generated.cs" Watch="false" />
<EmbeddedResource Update="Strings.resx" Watch="false" />
</ItemGroup>
dotnet watch
will ignore project references that have the Watch="false"
attribute, as shown in the following example:
<ItemGroup>
<ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>
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:
<ItemGroup Condition="'$(DotNetWatchBuild)'=='true'">
<!-- only included in the project when dotnet-watch is running -->
</ItemGroup>
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.
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:
dotnet watch --no-hot-reload
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
.NET feedback
.NET is an open source project. Select a link to provide feedback: