dotnet-watch(1)

1dotnet-watch(1)               .NET Documentation               dotnet-watch(1)
2
3
4

dotnet watch

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

NAME

9       dotnet-watch  -  Restarts or hot reloads the specified application when
10       changes in the source code are detected.
11

SYNOPSIS

13              dotnet watch [--list]
14                [--no-hot-reload] [--non-interactive]
15                [--project <PROJECT>]
16                [-q|--quiet] [-v|--verbose]
17                [--version]
18                [--] <forwarded arguments>
19
20              dotnet watch -?|-h|--help
21

DESCRIPTION

23       The dotnet watch command is a file watcher.  When it detects  a  change
24       that is supported for hot reload, it hot reloads the specified applica‐
25       tion.  When it detects an unsupported change, it restarts the  applica‐
26       tion.  This process enables fast iterative development from the command
27       line.
28
29       While running dotnet watch, you  can  force  the  app  to  rebuild  and
30       restart  by  pressing  Ctrl+R  in  the  command shell.  This feature is
31       available only while the app is running.  For example, if you run  dot‐
32       net  watch on a console app that ends before you press Ctrl+R, pressing
33       Ctrl+R has no effect.  However, in that  case  dotnet  watch  is  still
34       watching files and will restart the app if a file is updated.
35
36   Response compression
37       If  dotnet  watch  runs  for an app that uses response compression, the
38       tool can’t inject the browser refresh script.  The  .NET  7  and  later
39       version of the tool displays a warning message like the following:
40
41              warn:  Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefresh‐
42              Middleware[4]
43
44              Unable to configure browser refresh script injection on the  re‐
45              sponse.  This may have been caused by the response’s Content-En‐
46              coding: `br'.  Consider disabling response compression.
47
48       As an alternative to disabling response compression, manually  add  the
49       browser refresh JavaScript reference to the app’s pages:
50
51              @if (Environment.GetEnvironmentVariable("__ASPNETCORE_BROWSER_TOOLS") is not null)
52              {
53                  <script src="/_framework/aspnetcore-browser-refresh.js"></script>
54              }
55

ARGUMENTS

57       • forwarded arguments
58
59         Arguments to pass to the child dotnet process.  For example: run with
60         options for dotnet run or test with options for dotnet test.  If  the
61         child command isn’t specified, the default is run for dotnet run.
62

OPTIONS

64       • --list
65
66         Lists all discovered files without starting the watcher.
67
68       • --no-hot-reload
69
70         Suppress hot reload for supported apps.
71
72       • --non-interactive
73
74         Runs  dotnet  watch in non-interactive mode.  Use this option to pre‐
75         vent console input from being requested.  When hot reload is  enabled
76         and  a  rude edit is detected, dotnet watch restarts the app.  Avail‐
77         able since .NET 7 SDK.
78
79       • --project <PATH>
80
81         Specifies the path of the project file to run (folder only or includ‐
82         ing  the  project  file  name).  If not specified, it defaults to the
83         current directory.
84
85       • -q|--quiet
86
87         Suppresses all output that is generated by the dotnet  watch  command
88         except  warnings  and  errors.   The option is not passed on to child
89         commands.  For example, output from dotnet  restore  and  dotnet  run
90         continues to be output.
91
92       • -v|--verbose
93
94         Shows verbose output for debugging.
95
96       • --version
97
98         Shows the version of dotnet watch.
99
100       • --
101
102         The  double-dash option (`–') can be used to delimit dotnet watch op‐
103         tions from arguments that will be passed to the child  process.   Its
104         use  is  optional.   When  the  double-dash option isn’t used, dotnet
105         watch considers the first unrecognized argument to be  the  beginning
106         of arguments that it should pass into the child dotnet process.
107

ENVIRONMENT VARIABLES

109       dotnet watch uses the following environment variables:
110
111       • DOTNET_HOTRELOAD_NAMEDPIPE_NAME
112
113         This  value  is  configured  by  dotnet  watch  when the app is to be
114         launched, and it specifies the named pipe.
115
116       • DOTNET_USE_POLLING_FILE_WATCHER
117
118         When set to 1 or true, dotnet watch uses a polling file  watcher  in‐
119         stead    of   <xref:System.IO.FileSystemWatcher?displayProperty=name‐
120         WithType>.  Polling is required for some file systems, such  as  net‐
121         work  shares, Docker mounted volumes, and other virtual file systems.
122         The    <xref:Microsoft.Extensions.FileProviders.PhysicalFileProvider>
123         class  uses  DOTNET_USE_POLLING_FILE_WATCHER to determine whether the
124         <xref:Microsoft.Extensions.FileProviders.Physical‐
125         FileProvider.Watch%2A?displayProperty=nameWithType>  method will rely
126         on   the   <xref:Microsoft.Extensions.FileProviders.Physical.Polling‐
127         FileChangeToken>.
128
129       • DOTNET_WATCH
130
131         dotnet  watch  sets this variable to 1 on all child processes that it
132         launches.
133
134       • DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME
135
136         As part of dotnet watch, the browser refresh server  mechanism  reads
137         this  value  to  determine the WebSocket host environment.  The value
138         127.0.0.1 is replaced by localhost,  and  the  http://  and  https://
139         schemes are replaced with ws:// and wss:// respectively.
140
141       • DOTNET_WATCH_ITERATION
142
143         dotnet  watch sets this variable to 1 and increments by one each time
144         a file is changed and the command restarts or hot reloads the  appli‐
145         cation.
146
147       • DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH
148
149         When  set  to  1 or true, dotnet watch won’t refresh browsers when it
150         detects file changes.
151
152       • DOTNET_WATCH_SUPPRESS_EMOJIS
153
154         With the .NET SDK 6.0.300 and later,  dotnet  watch  emits  non-ASCII
155         characters to the console, as shown in the following example:
156
157                dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload.
158                  💡 Press "Ctrl + R" to restart.
159                dotnet watch 🔧 Building...
160                dotnet watch 🚀 Started
161                dotnet watch ⌚ Exited
162                dotnet watch ⏳ Waiting for a file to change before restarting dotnet...
163
164         On  certain  console  hosts, these characters may appear garbled.  To
165         avoid seeing garbled characters, set this variable to 1 or true.
166
167       • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER
168
169         When set to 1 or true, dotnet watch won’t launch or refresh  browsers
170         for  web  apps  that  have  launchBrowser  configured  in  launchSet‐
171         tings.json.
172
173       • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM
174
175         By default, dotnet watch optimizes the build by avoiding certain  op‐
176         erations, such as running restore or re-evaluating the set of watched
177         files on every file change.  If this variable is set to  1  or  true,
178         these optimizations are disabled.
179
180       • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING
181
182         When  set  to  1  or true, dotnet watch won’t do special handling for
183         static content files.  dotnet watch  sets  MSBuild  property  DotNet‐
184         WatchContentFiles to false.
185
186   Files watched by default
187       dotnet  watch  watches all items in the Watch item group in the project
188       file.  By default, this group includes all items in the Compile and Em‐
189       beddedResource  groups.   dotnet  watch  also scans the entire graph of
190       project references and watches all files within those projects.
191
192       By default, the Compile and EmbeddedResource groups include  all  files
193       matching the following glob patterns:
194
195       • **/*.cs
196
197       • *.csproj
198
199       • **/*.resx
200
201       • Content files in web apps: wwwroot/**
202
203       By  default,  .config,  and  .json  files  don’t trigger a dotnet watch
204       restart because the configuration system has  its  own  mechanisms  for
205       handling configuration changes.
206
207       Files  can be added to the watch list or removed from the list by edit‐
208       ing the project file.  Files can be specified individually or by  using
209       glob patterns.
210
211   Watch additional files
212       More  files can be watched by adding items to the Watch group.  For ex‐
213       ample, the following markup extends that group  to  include  JavaScript
214       files:
215
216              <ItemGroup>
217                <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
218              </ItemGroup>
219
220   Ignore specified files
221       dotnet  watch  will ignore Compile and EmbeddedResource items that have
222       the Watch="false" attribute, as shown in the following example:
223
224              <ItemGroup>
225                <Compile Update="Generated.cs" Watch="false" />
226                <EmbeddedResource Update="Strings.resx" Watch="false" />
227              </ItemGroup>
228
229       dotnet watch will ignore project references that have the Watch="false"
230       attribute, as shown in the following example:
231
232              <ItemGroup>
233                <ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
234              </ItemGroup>
235
236   Advanced configuration
237       dotnet watch performs a design-time build to find items to watch.  When
238       this  build  is  run,  dotnet  watch  sets  the  property  DotNetWatch‐
239       Build=true.   This property can be used as shown in the following exam‐
240       ple:
241
242              <ItemGroup Condition="'$(DotNetWatchBuild)'=='true'">
243                <!-- only included in the project when dotnet-watch is running -->
244              </ItemGroup>
245
246   Hot Reload
247       Starting in .NET 6, dotnet watch includes support for hot reload.   Hot
248       reload  is a feature that lets you apply changes to a running app with‐
249       out having to rebuild and restart it.  The changes may be to code files
250       or  static assets, such as stylesheet files and JavaScript files.  This
251       feature streamlines the local development experience, as it gives imme‐
252       diate feedback when you modify your app.
253
254       For  information  about  app  types  and .NET versions that support hot
255       reload, see Supported .NET app frameworks and scenarios.
256
257   Rude edits
258       When a file is modified, dotnet watch determines if the app can be  hot
259       reloaded.  If it can’t be hot reloaded, the change is called a rude ed‐
260       it and dotnet watch asks if you want to restart the app:
261
262              dotnet watch ⌚ Unable to apply hot reload because of a rude edit.
263                ❔ Do you want to restart your app - Yes (y) / No (n) / Always (a) / Never (v)?
264
265       • Yes: Restarts the app.
266
267       • No: Leaves the app running without the changes applied.
268
269       • Always: Restarts the app and doesn’t prompt anymore for rude edits.
270
271       • Never: Leaves the app running without the changes applied and doesn’t
272         prompt anymore for rude edits.
273
274       For  information about what kinds of changes are considered rude edits,
275       see Edit code and continue debugging and Unsupported changes to code.
276
277       To disable hot reload when you run  dotnet  watch,  use  the  --no-hot-
278       reload option, as shown in the following example:
279
280       .NET CLI dotnet watch --no-hot-reload
281

EXAMPLES

283       • Run  dotnet  run  for  the  project in the current directory whenever
284         source code changes:
285
286                dotnet watch
287
288         Or:
289
290                dotnet watch run
291
292       • Run dotnet test for the project in  the  current  directory  whenever
293         source code changes:
294
295                dotnet watch test
296
297       • Run  dotnet  run  --project  ./HelloWorld.csproj whenever source code
298         changes:
299
300                dotnet watch run --project  ./HelloWorld.csproj
301
302       • Run dotnet run -- arg0 for the project in the current directory when‐
303         ever source code changes:
304
305                dotnet watch run -- arg0
306
307         Or:
308
309                dotnet watch -- run arg0
310