Skip to content

Commit 5ba83b2

Browse files
tdykstratdykstra
authored
CLI reference article for dotnet watch (#29300)
1 parent ab1417a commit 5ba83b2

File tree

4 files changed

+267
-23
lines changed

4 files changed

+267
-23
lines changed

‎docs/core/tools/dotnet-environment-variables.md‎

Lines changed: 5 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: .NET environment variables
33
description: Learn about the environment variables that you can use to configure the .NET SDK, .NET CLI, and .NET runtime.
4-
ms.date: 01/31/2022
4+
ms.date: 05/11/2022
55
---
66

77
# .NET environment variables
@@ -297,26 +297,6 @@ The typical way to get detailed trace information about application startup is t
297297

298298
If set to `true`, invoking `dotnet` won't produce a warning when a preview SDK is being used.
299299

300-
### `DOTNET_WATCH_*`
301-
302-
The following .NET watch settings are available as environment variables:
303-
304-
- `DOTNET_WATCH`: The `dotnet watch` command sets this variable to `1` on all child processes launched.
305-
- `DOTNET_WATCH_ITERATION`: The `dotnet watch` command sets this variable to `1` and increments by one each time
306-
a file is changed and the command is restarted.
307-
- `DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`: If set to `1`, or `true`, `dotnet watch` will _not_ perform special handling for static content file.
308-
- `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 set to `1` or `true`, these optimizations are disabled.
309-
- `DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`: The `dotnet watch run` command will attempt to launch browsers for web apps with `launchBrowser` configured in the _launchSettings.json_ file. If set to `1` or `true`, this behavior is suppressed.
310-
- `DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`
311-
- `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.
312-
- `DOTNET_HOTRELOAD_NAMEDPIPE_NAME`: This value is configured by `dotnet watch` when the app is to be launched, and it specifies the named pipe.
313-
314-
For more information, see [GitHub: .NET SDK dotnet-watch](https://github.com/dotnet/sdk/blob/main/src/BuiltInTools/dotnet-watch/README.md).
315-
316-
#### `DOTNET_USE_POLLING_FILE_WATCHER`
317-
318-
When set to `1` or `true`, `dotnet watch` will poll the file system for changes. This 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>.
319-
320300
### Configure MSBuild in the .NET CLI
321301

322302
To execute MSBuild out-of-process, set the `DOTNET_CLI_RUN_MSBUILD_OUTOFPROC` environment variable to either `1`, `true`, or `yes`. By default, MSBuild will execute in-proc. To force MSBuild to use an external working node long-living process for building projects, set `DOTNET_CLI_USE_MSBUILDNOINPROCNODE` to `1`, `true`, or `yes`. This will set the `MSBUILDNOINPROCNODE` environment variable to `1`, which is referred to as _MSBuild Server V1_, as the entry process forwards most of the work to it.
@@ -333,6 +313,10 @@ These are overrides that are used to force the resolved SDK tasks and targets to
333313

334314
Configures the default programming language for the `dotnet new` command when the `-lang|--language` switch is omitted. The default value is `C#`. Valid values are `C#`, `F#`, or `VB`. For more information, see [dotnet new](dotnet-new.md).
335315

316+
### `dotnet watch` environment variables
317+
318+
For information about `dotnet watch` settings that are available as environment variables, see [dotnet watch environment variables](dotnet-watch.md#environment-variables).
319+
336320
## See also
337321

338322
- [dotnet command](dotnet.md)

‎docs/core/tools/dotnet-watch.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
title: dotnet watch command
3+
description: The dotnet watch command is a file watcher that restarts or hot reloads the specified application when changes in the source code are detected.
4+
ms.date: 05/11/2022
5+
---
6+
# dotnet watch
7+
8+
**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
9+
10+
## Name
11+
12+
`dotnet watch` - Restarts or [hot reloads](#hot-reload) the specified application when changes in the source code are detected.
13+
14+
## Synopsis
15+
16+
```dotnetcli
17+
dotnet watch [--list]
18+
[--no-hot-reload] [--non-interactive]
19+
[--project <PROJECT>]
20+
[-q|--quiet] [-v|--verbose]
21+
[--version]
22+
[--] <forwarded arguments>
23+
24+
dotnet watch -?|-h|--help
25+
```
26+
27+
## Description
28+
29+
The `dotnet watch` command is a file watcher. When it detects a change that is supported for [hot reload](#hot-reload), it hot reloads the specified application. When it detects an unsupported change, it restarts the application. This process enables fast iterative development from the command line.
30+
31+
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.
32+
33+
## Arguments
34+
35+
<!-- markdownlint-disable MD012 -->
36+
37+
- **`forwarded arguments`**
38+
39+
Arguments to pass to the child `dotnet` process. For example: `run` with options for [dotnet run](dotnet-run.md) or `test` with options for [dotnet test](dotnet-test.md). If the child command isn't specified, the default is `run` for `dotnet run`.
40+
41+
## Options
42+
43+
- **`--list`**
44+
45+
Lists all discovered files without starting the watcher.
46+
47+
- **`--no-hot-reload`**
48+
49+
Suppress [hot reload](#hot-reload) for [supported apps](/visualstudio/debugger/hot-reload#supported-net-app-frameworks-and-scenarios).
50+
51+
- **`--non-interactive`**
52+
53+
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](#rude-edits) is detected, dotnet watch restarts the app.
54+
55+
- **`--project <PATH>`**
56+
57+
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.
58+
59+
- **`-q|--quiet`**
60+
61+
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.
62+
63+
- **`-v|--verbose`**
64+
65+
Shows verbose output for debugging.
66+
67+
- **`--version`**
68+
69+
Shows the version of `dotnet watch`.
70+
71+
- **`--`**
72+
73+
The [double-dash option ('--')](../../standard/commandline/syntax.md#the----token) 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.
74+
75+
## Environment variables
76+
77+
`dotnet watch` uses the following environment variables:
78+
79+
- **`DOTNET_HOTRELOAD_NAMEDPIPE_NAME`**
80+
81+
This value is configured by `dotnet watch` when the app is to be launched, and it specifies the named pipe.
82+
83+
- **`DOTNET_USE_POLLING_FILE_WATCHER`**
84+
85+
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>.
86+
87+
- **`DOTNET_WATCH`**
88+
89+
`dotnet watch` sets this variable to `1` on all child processes that it launches.
90+
91+
- **`DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME`**
92+
93+
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.
94+
95+
- **`DOTNET_WATCH_ITERATION`**
96+
97+
`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.
98+
99+
- **`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`**
100+
101+
When set to `1` or `true`, `dotnet watch` won't refresh browsers when it detects file changes.
102+
103+
- **`DOTNET_WATCH_SUPPRESS_EMOJIS`**
104+
105+
With the .NET SDK 6.0.300 and later, `dotnet watch` emits non-ASCII characters to the console, as shown in the following example:
106+
107+
```output
108+
dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload.
109+
💡 Press "Ctrl + R" to restart.
110+
dotnet watch 🔧 Building...
111+
dotnet watch 🚀 Started
112+
dotnet watch ⌚ Exited
113+
dotnet watch ⏳ Waiting for a file to change before restarting dotnet...
114+
```
115+
116+
On certain console hosts, these characters may appear garbled. To avoid seeing garbled characters, set this variable to `1` or `true`.
117+
118+
- **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`**
119+
120+
When set to `1` or `true`, `dotnet watch` won't launch or refresh browsers for web apps that have `launchBrowser` configured in *launchSettings.json*.
121+
122+
- **`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`**
123+
124+
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.
125+
126+
- **`DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`**
127+
128+
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`.
129+
130+
## Files watched by default
131+
132+
`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.
133+
134+
By default, the `Compile` and `EmbeddedResource` groups include all files matching the following glob patterns:
135+
136+
* `**/*.cs`
137+
* `*.csproj`
138+
* `**/*.resx`
139+
* Content files in web apps: `wwwroot/**`
140+
141+
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.
142+
143+
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.
144+
145+
## Watch additional files
146+
147+
More files can be watched by adding items to the `Watch` group. For example, the following markup extends that group to include JavaScript files:
148+
149+
```xml
150+
<ItemGroup>
151+
<Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
152+
</ItemGroup>
153+
```
154+
155+
## Ignore specified files
156+
157+
`dotnet watch` will ignore `Compile` and `EmbeddedResource` items that have the `Watch="false"` attribute, as shown in the following example:
158+
159+
```xml
160+
<ItemGroup>
161+
<Compile Update="Generated.cs" Watch="false" />
162+
<EmbeddedResource Update="Strings.resx" Watch="false" />
163+
</ItemGroup>
164+
```
165+
166+
`dotnet watch` will ignore project references that have the `Watch="false"` attribute, as shown in the following example:
167+
168+
```xml
169+
<ItemGroup>
170+
<ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
171+
</ItemGroup>
172+
```
173+
174+
## Advanced configuration
175+
176+
`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:
177+
178+
```xml
179+
<ItemGroup Condition="'$(DotNetWatchBuild)'=='true'">
180+
<!-- only included in the project when dotnet-watch is running -->
181+
</ItemGroup>
182+
```
183+
184+
## Hot Reload
185+
186+
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.
187+
188+
For information about app types and .NET versions that support hot reload, see [Supported .NET app frameworks and scenarios](/visualstudio/debugger/hot-reload#supported-net-app-frameworks-and-scenarios).
189+
190+
### Rude edits
191+
192+
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:
193+
194+
```dotnetcli
195+
dotnet watch ⌚ Unable to apply hot reload because of a rude edit.
196+
❔ Do you want to restart your app - Yes (y) / No (n) / Always (a) / Never (v)?
197+
```
198+
199+
* **Yes**: Restarts the app.
200+
* **No**: Leaves the app running without the changes applied.
201+
* **Always**: Restarts the app and doesn't prompt anymore for rude edits.
202+
* **Never**: Leaves the app running without the changes applied and doesn't prompt anymore for rude edits.
203+
204+
For information about what kinds of changes are considered rude edits, see [Edit code and continue debugging](/visualstudio/debugger/edit-and-continue) and [Unsupported changes to code](/visualstudio/debugger/supported-code-changes-csharp#unsupported-changes-to-code).
205+
206+
To disable hot reload when you run `dotnet watch`, use the `--no-hot-reload` option, as shown in the following example:
207+
208+
```.NET CLI
209+
dotnet watch --no-hot-reload
210+
```
211+
212+
## Examples
213+
214+
- Run `dotnet run` for the project in the current directory whenever source code changes:
215+
216+
```dotnetcli
217+
dotnet watch
218+
```
219+
220+
Or:
221+
222+
```dotnetcli
223+
dotnet watch run
224+
```
225+
226+
- Run `dotnet test` for the project in the current directory whenever source code changes:
227+
228+
```dotnetcli
229+
dotnet watch test
230+
```
231+
232+
- Run `dotnet run --project ./HelloWorld.csproj` whenever source code changes:
233+
234+
```dotnetcli
235+
dotnet watch run --project ./HelloWorld.csproj
236+
```
237+
238+
- Run `dotnet run -- arg0` for the project in the current directory whenever source code changes:
239+
240+
```dotnetcli
241+
dotnet watch run -- arg0
242+
```
243+
244+
Or:
245+
246+
```dotnetcli
247+
dotnet watch -- run arg0
248+
```
249+
250+
## See also
251+
252+
* [Tutorial: Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch)
253+
* [Hot reload in Visual Studio](/visualstudio/debugger/hot-reload)
254+
* [Hot reload supported apps](/visualstudio/debugger/hot-reload#supported-net-app-frameworks-and-scenarios)
255+
* [Hot reload supported code changes](/visualstudio/debugger/supported-code-changes-csharp)
256+
* [Hot reload test execution](/visualstudio/test/test-execution-with-hot-reload)
257+
* [Hot reload support for ASP.NET Core](/aspnet/core/test/hot-reload)

‎docs/core/tools/dotnet.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: dotnet command
33
description: Learn about the dotnet command (the generic driver for the .NET CLI) and its usage.
4-
ms.date: 07/19/2021
4+
ms.date: 05/06/2022
55
---
66
# dotnet command
77

@@ -226,7 +226,7 @@ The following additional tools are available as part of the .NET SDK:
226226
| dev-certs | Creates and manages development certificates. |
227227
| [ef](/ef/core/miscellaneous/cli/dotnet) | Entity Framework Core command-line tools. |
228228
| [user-secrets](/aspnet/core/security/app-secrets) | Manages development user secrets. |
229-
| [watch](/aspnet/core/tutorials/dotnet-watch) | Starts a file watcher that runs a command when files change. |
229+
| [watch](dotnet-watch.md) | A file watcher that restarts or hot reloads an application when it detects changes in the source code. |
230230

231231
For more information about each tool, type `dotnet <tool-name> --help`.
232232

‎docs/fundamentals/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,9 @@ items:
350350
href: ../core/tools/dotnet-tool-update.md
351351
- name: dotnet vstest
352352
href: ../core/tools/dotnet-vstest.md
353+
- name: dotnet watch
354+
displayName: hot reload
355+
href: ../core/tools/dotnet-watch.md
353356
- name: dotnet workload
354357
items:
355358
- name: dotnet workload install

0 commit comments

Comments
 (0)