dotnet-watch - Man Page

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

dotnet watch

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

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

Options

Environment Variables

dotnet watch uses the following environment variables:

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:

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

Ignore specified files

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>

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:

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

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

See Also

Info

2023-10-25 .NET Documentation