From 2f49d46e753e7bfb2bc2890fe6a4a79338ceed6d Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Mon, 18 Apr 2022 19:59:42 -0700 Subject: [PATCH 01/13] draft --- docs/core/tools/dotnet-watch.md | 113 ++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/core/tools/dotnet-watch.md diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md new file mode 100644 index 0000000000000..7b1ef470601bd --- /dev/null +++ b/docs/core/tools/dotnet-watch.md @@ -0,0 +1,113 @@ +--- +title: dotnet watch command +description: The dotnet watch command is a file watcher that restarts the specified application when changes in the source code are detected. +ms.date: 04/18/2022 +--- +# dotnet watch + +**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions + +## Name + +`dotnet watch` - Restarts the specified application when changes in the source code are detected. + +## Synopsis + +```dotnetcli +dotnet watch [--list] + [--no-hot-reload] [--non-interactive] + [--project ] [-q|--quiet] [-v|--verbose] + [--version] + +dotnet watch -?|-h|--help +``` + +## Description + +The `dotnet watch` command is a file watcher. It restarts the specified application when changes in the source code are detected. It's useful for fast iterative development from the command line. + +## Environment variables + +`dotnet watch` uses the following environment variables: + +- **`DOTNET_USE_POLLING_FILE_WATCHER`** + + When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. + +- **`DOTNET_WATCH`** + + `dotnet watch` sets this variable to `1` on all child processes launched. + +- **`DOTNET_WATCH_ITERATION`** + + `dotnet watch` sets this variable to `1` and increments by one each time a file is changed and the command is restarted. + +- **`DOTNET_WATCH_SUPPRESS_EMOJIS`** + + When set to `1` or `true`, `dotnet watch` will not show emojis in the console output. + +## Arguments + + + +- **`forwarded arguments`** + + Arguments to pass to the child dotnet process. + +## Options + +- **`--`** + + 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 passed into the child dotnet process. For more information, see [the Examples section](#examples). Can double-dash be used twice, once for watch and once for run? + +- **`--list`** + + Lists all discovered files without starting the watcher. + +- **`--no-hot-reload`** + + Suppress hot reload for supported apps. What does for supported apps mean? + +- **`--non-interactive`** + + Runs `dotnet watch` in non-interactive mode. This option is only supported when running with Hot Reload enabled. Use this option to prevent console input from being captured. + +- **`--project `** + + Specifies the path of the project file to run (folder name or full path). If not specified, it defaults to the current directory.The readme says "The command must be executed in the directory that contains the project to be watched." only the command shows --project, not the readme + +- **`-q|--quiet`** + + Suppresses all output except warnings and errors. + +- **`-v|--verbose`** + + Show verbose output. + +- **`--version`** + + Show version information. of what, the target project or the dotnet watch command? + +## Examples + +- Run `dotnet run` for the project in the current directory whenever source code changes: + + ```dotnetcli + dotnet watch run + ``` + +- Run `dotnet test` for the project in the current directory whenever source code changes: + + ```dotnetcli + dotnet watch test + ``` + +- Run `dotnet run --project ./HelloWorld.csproj` whenever source code changes: + + ```dotnetcli + dotnet watch run -- --project ./HelloWorld.csproj + ``` + + The use of '--' indicates that `project ./HelloWorld.csproj` should be treated as an argument for `dotnet run` rather than `dotnet watch`. + + From 7759a2f6d61662e2e24bc993665876aa8f0f9d97 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Tue, 19 Apr 2022 16:40:51 -0700 Subject: [PATCH 02/13] draft --- docs/core/tools/dotnet-watch.md | 139 +++++++++++++++++++++++++++----- 1 file changed, 117 insertions(+), 22 deletions(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index 7b1ef470601bd..94ea43db881ce 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -26,25 +26,7 @@ dotnet watch -?|-h|--help The `dotnet watch` command is a file watcher. It restarts the specified application when changes in the source code are detected. It's useful for fast iterative development from the command line. -## Environment variables - -`dotnet watch` uses the following environment variables: - -- **`DOTNET_USE_POLLING_FILE_WATCHER`** - - When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. - -- **`DOTNET_WATCH`** - - `dotnet watch` sets this variable to `1` on all child processes launched. - -- **`DOTNET_WATCH_ITERATION`** - - `dotnet watch` sets this variable to `1` and increments by one each time a file is changed and the command is restarted. - -- **`DOTNET_WATCH_SUPPRESS_EMOJIS`** - - When set to `1` or `true`, `dotnet watch` will not show emojis in the console output. +While running `dotnet watch`, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell.check this out ## Arguments @@ -66,11 +48,11 @@ The `dotnet watch` command is a file watcher. It restarts the specified applicat - **`--no-hot-reload`** - Suppress hot reload for supported apps. What does for supported apps mean? + Suppress [hot reload](#hot-reload) for supported apps. What does for supported apps mean? - **`--non-interactive`** - Runs `dotnet watch` in non-interactive mode. This option is only supported when running with Hot Reload enabled. Use this option to prevent console input from being captured. + Runs `dotnet watch` in non-interactive mode. This option is only supported when running with [hot reload](#hot-reload) enabled. Use this option to prevent console input from being captured. - **`--project `** @@ -110,4 +92,117 @@ The `dotnet watch` command is a file watcher. It restarts the specified applicat The use of '--' indicates that `project ./HelloWorld.csproj` should be treated as an argument for `dotnet run` rather than `dotnet watch`. - +## Environment variables + +`dotnet watch` uses the following environment variables: + +- **`DOTNET_USE_POLLING_FILE_WATCHER`** + + When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. + +- **`DOTNET_WATCH`** + + `dotnet watch` sets this variable to `1` on all child processes launched. + +- **`DOTNET_WATCH_ITERATION`** + + `dotnet watch` sets this variable to `1` and increments by one each time a file is changed and the command is restarted. + +- **`DOTNET_WATCH_SUPPRESS_EMOJIS`** + + With the .NET SDK 6.0.300 and later, `dotnet watch` emits non-ASCII characters to the console during a hot reload session. On certain console hosts, these characters may appear garbled. To avoid garbled characters, set this variable to `1` or `true`. + +- **`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`**asp.net core tutorial only + + When set to `1` or `true`, `dotnet watch` won't refresh browsers when it detects file changes. + +- **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`**readme only and asp.net core tutorial + + When set to `1` or `true`, `dotnet watch` won't launch or refresh browsers for web apps that have `launchBrowser` configured in *launchSettings.json*. + +- **`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`**readme and asp.net core tutorial + + 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. + +- **`DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`**readme only + + When set to `1` or `true`, `dotnet watch` won't do special handling for static content files. + +## Files watched by default + +By default, `dotnet watch` tracks all files matching the following glob patterns: + +* `**/*.cs` +* `*.csproj` +* `**/*.resx` +* Content files: `wwwroot/**`, `**/*.config`, `**/*.json` + +`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. + +More items can be added to the watch list by editing the project file. Items can be specified individually or by using glob patterns. + +## Watch additional files + +More items can be watched by adding items to the `Watch` group. For example, the following markup extends that group to include JavaScript files: + +```xml + + + +``` + +## Ignore specified items + +`dotnet watch` will ignore `Compile` and `EmbeddedResource` items that have the `Watch="false"` attribute, as shown in the following example: + +```xml + + + + +``` + +`dotnet watch` will ignore project references that have the `Watch="false"` attribute, as shown in the following example: + +```xml + + + +``` + +## 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: what would you use this for? + +```xml + + + +``` + +## Hot Reload + +Starting in .NET 6, `dotnet watch` adds 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 enables a much faster development experience, as you receive immediate feedback when you modify your app during local development. + +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 a *rude edit* and dotnet watch asks if you want to restart the app: + +* **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](/visualstudio/debugger/edit-and-continue) and [Unsupported edits](https://github.com/dotnet/roslyn/blob/main/docs/wiki/EnC-Supported-Edits.md#not-supported-edits). + +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 +``` + +## See also + +* [Hot reload in Visual Studio](/visualstudio/debugger/hot-reload) +* [Test execution with hot reload](/visualstudio/test/test-execution-with-hot-reload) +* [Hot reload for ASP.NET Core](/aspnet/core/test/hot-reload?view=aspnetcore-6.0) +* [Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch) From ebdacd73a8584a74f4879d55cb848664a3d5f7cc Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Thu, 21 Apr 2022 16:14:21 -0700 Subject: [PATCH 03/13] draft --- docs/core/tools/dotnet-watch.md | 97 +++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 34 deletions(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index 94ea43db881ce..fcd3a44d0b8ac 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -1,32 +1,34 @@ --- title: dotnet watch command -description: The dotnet watch command is a file watcher that restarts the specified application when changes in the source code are detected. +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. ms.date: 04/18/2022 --- # dotnet watch -**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions +**This article applies to:** ✅ .NET Core 3.1 SDK and later versions ## Name -`dotnet watch` - Restarts the specified application when changes in the source code are detected. +`dotnet watch` - Restarts or [hot reloads](#hot-reload) the specified application when changes in the source code are detected. ## Synopsis ```dotnetcli -dotnet watch [--list] +dotnet watch [--list] [--no-hot-reload] [--non-interactive] - [--project ] [-q|--quiet] [-v|--verbose] + [--project ] + [-q|--quiet] [-v|--verbose] [--version] + [--] dotnet watch -?|-h|--help ``` ## Description -The `dotnet watch` command is a file watcher. It restarts the specified application when changes in the source code are detected. It's useful for fast iterative development from the command line. +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. -While running `dotnet watch`, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell.check this out +While running `dotnet watch`, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell.this doesn't seem to work in Windows cmd.exe ## Arguments @@ -34,33 +36,36 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`forwarded arguments`** - Arguments to pass to the child dotnet process. + Arguments to pass to the child dotnet process. For example, `run` and options for [dotnet run](dotnet-run.md) or `test` and options for [dotnet test](dotnet-test.md). If not specified, the default is `run` for `dotnet run`. ## Options -- **`--`** - - 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 passed into the child dotnet process. For more information, see [the Examples section](#examples). Can double-dash be used twice, once for watch and once for run? - - **`--list`** Lists all discovered files without starting the watcher. - **`--no-hot-reload`** - Suppress [hot reload](#hot-reload) for supported apps. What does for supported apps mean? + Suppress [hot reload](#hot-reload) for supported apps. What apps are supported/unsupported? - **`--non-interactive`** - Runs `dotnet watch` in non-interactive mode. This option is only supported when running with [hot reload](#hot-reload) enabled. Use this option to prevent console input from being captured. + Runs `dotnet watch` in non-interactive mode. Use this option to prevent console input from being captured. This option is only supported when running with [hot reload](#hot-reload) enabled. What console input is prevented? Ctrl-C still works; no error message or changed behavior with --no-hot-reload and --non-interactive both specified. - **`--project `** - Specifies the path of the project file to run (folder name or full path). If not specified, it defaults to the current directory.The readme says "The command must be executed in the directory that contains the project to be watched." only the command shows --project, not the readme + Specifies the path of the project file to run (folder name or full path). If not specified, it defaults to the current directory.The readme says "The command must be executed in the directory that contains the project to be watched." that seems outdated, as the command help shows --project, not the readme - **`-q|--quiet`** - Suppresses all output except warnings and errors. + Suppresses all output except warnings and errors.It doesn't actually do this, you get: + + Determining projects to restore... + All projects are up-to-date for restore. + You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy + helloworld -> C:\test\helloworld\bin\Debug\net6.0\helloworld.dll +Hello, World! +dotnet watch ⏳ Waiting for a file to change before restarting dotnet... - **`-v|--verbose`** @@ -68,7 +73,11 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`--version`** - Show version information. of what, the target project or the dotnet watch command? + Show the `dotnet watch` version. + +- **`--`** + + 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 passed into the child dotnet process. For more information, see [the Examples section](#examples).I don't see much use for this, as there is hardly any overlap in option names between dotnet watch and run/test/etc. You can use -- for dotnet run without using it for dotnet watch, as in dotnet run -- arg0. ## Examples @@ -87,10 +96,14 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - Run `dotnet run --project ./HelloWorld.csproj` whenever source code changes: ```dotnetcli - dotnet watch run -- --project ./HelloWorld.csproj + dotnet watch run --project ./HelloWorld.csproj ``` - The use of '--' indicates that `project ./HelloWorld.csproj` should be treated as an argument for `dotnet run` rather than `dotnet watch`. +- Run `dotnet run -- arg0` for the project in the current directory whenever source code changes: + + ```dotnetcli + dotnet watch run -- arg0 + ``` ## Environment variables @@ -106,44 +119,55 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`DOTNET_WATCH_ITERATION`** - `dotnet watch` sets this variable to `1` and increments by one each time a file is changed and the command is restarted. + `dotnet watch` sets this variable to `1` and increments by one each time a file is changed and the command restarts the application. - **`DOTNET_WATCH_SUPPRESS_EMOJIS`** - With the .NET SDK 6.0.300 and later, `dotnet watch` emits non-ASCII characters to the console during a hot reload session. On certain console hosts, these characters may appear garbled. To avoid garbled characters, set this variable to `1` or `true`. + 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_SUPPRESS_BROWSER_REFRESH`**asp.net core tutorial only + ```output + 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 garbled characters, set this variable to `1` or `true`. + +- **`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`**not in the app help; asp.net core tutorial only When set to `1` or `true`, `dotnet watch` won't refresh browsers when it detects file changes. -- **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`**readme only and asp.net core tutorial +- **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`**not in the app help; readme and asp.net core tutorial only When set to `1` or `true`, `dotnet watch` won't launch or refresh browsers for web apps that have `launchBrowser` configured in *launchSettings.json*. -- **`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`**readme and asp.net core tutorial +- **`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`**not in the app help; readme and asp.net core tutorial only 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. - **`DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`**readme only - When set to `1` or `true`, `dotnet watch` won't do special handling for static content files. + When set to `1` or `true`, `dotnet watch` won't do special handling for static content files.what is the special handling that it otherwise does? ## Files watched by default -By default, `dotnet watch` tracks all files matching the following glob patterns: +`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:this list is from the ASP.NET Core tutorial -- is it correct? * `**/*.cs` * `*.csproj` * `**/*.resx` * Content files: `wwwroot/**`, `**/*.config`, `**/*.json` -`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. - -More items can be added to the watch list by editing the project file. Items can be specified individually or by using glob patterns. +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 items can be watched by adding items to the `Watch` group. For example, the following markup extends that group to include JavaScript 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: ```xml @@ -182,17 +206,21 @@ More items can be watched by adding items to the `Watch` group. For example, the ## Hot Reload -Starting in .NET 6, `dotnet watch` adds 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 enables a much faster development experience, as you receive immediate feedback when you modify your app during local development. +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 you receive immediate feedback when you modify your app. -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 a *rude edit* and dotnet watch asks if you want to restart the app: +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 a *rude edit* and `dotnet watch` asks if you want to restart the app: + +```dotnetcli +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](/visualstudio/debugger/edit-and-continue) and [Unsupported edits](https://github.com/dotnet/roslyn/blob/main/docs/wiki/EnC-Supported-Edits.md#not-supported-edits). +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). To disable hot reload when you run `dotnet watch`, use the `--no-hot-reload` option, as shown in the following example: @@ -206,3 +234,4 @@ dotnet watch --no-hot-reload * [Test execution with hot reload](/visualstudio/test/test-execution-with-hot-reload) * [Hot reload for ASP.NET Core](/aspnet/core/test/hot-reload?view=aspnetcore-6.0) * [Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch) +* [Supported code changes](/visualstudio/debugger/supported-code-changes-csharp) From e2b76a2eaaf5c82d405157c57e3c90863eb4e819 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Thu, 5 May 2022 10:18:07 -0700 Subject: [PATCH 04/13] draft --- docs/core/tools/dotnet-watch.md | 55 ++++++++++++++++----------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index fcd3a44d0b8ac..8faa9377b04a9 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -1,11 +1,11 @@ --- title: dotnet watch command 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. -ms.date: 04/18/2022 +ms.date: 05/05/2022 --- # dotnet watch -**This article applies to:** ✅ .NET Core 3.1 SDK and later versions +**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions ## Name @@ -28,7 +28,7 @@ dotnet watch -?|-h|--help 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. -While running `dotnet watch`, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell.this doesn't seem to work in Windows cmd.exe +While running `dotnet watch`, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell. ## Arguments @@ -36,7 +36,7 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`forwarded arguments`** - Arguments to pass to the child dotnet process. For example, `run` and options for [dotnet run](dotnet-run.md) or `test` and options for [dotnet test](dotnet-test.md). If not specified, the default is `run` for `dotnet run`. + Arguments to pass to the child `dotnet` process. For example, `run` and options for [dotnet run](dotnet-run.md) or `test` and options for [dotnet test](dotnet-test.md). If not specified, the default is `run` for `dotnet run`. ## Options @@ -46,43 +46,42 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`--no-hot-reload`** - Suppress [hot reload](#hot-reload) for supported apps. What apps are supported/unsupported? + Suppress [hot reload](#hot-reload) for supported apps. - **`--non-interactive`** - Runs `dotnet watch` in non-interactive mode. Use this option to prevent console input from being captured. This option is only supported when running with [hot reload](#hot-reload) enabled. What console input is prevented? Ctrl-C still works; no error message or changed behavior with --no-hot-reload and --non-interactive both specified. + Runs `dotnet watch` in non-interactive mode. Use this option to prevent console input from being captured. This option is only supported when running with [hot reload](#hot-reload) enabled. - **`--project `** - Specifies the path of the project file to run (folder name or full path). If not specified, it defaults to the current directory.The readme says "The command must be executed in the directory that contains the project to be watched." that seems outdated, as the command help shows --project, not the readme + 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 except warnings and errors.It doesn't actually do this, you get: - - Determining projects to restore... - All projects are up-to-date for restore. - You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy - helloworld -> C:\test\helloworld\bin\Debug\net6.0\helloworld.dll -Hello, World! -dotnet watch ⏳ Waiting for a file to change before restarting dotnet... + Suppresses all output except warnings and errors. - **`-v|--verbose`** - Show verbose output. + Shows verbose output. - **`--version`** - Show the `dotnet watch` version. + Shows the version of `dotnet watch`. - **`--`** - 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 passed into the child dotnet process. For more information, see [the Examples section](#examples).I don't see much use for this, as there is hardly any overlap in option names between dotnet watch and run/test/etc. You can use -- for dotnet run without using it for dotnet watch, as in dotnet run -- arg0. + 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. For more information, see [the Examples section](#examples). ## Examples - Run `dotnet run` for the project in the current directory whenever source code changes: + ```dotnetcli + dotnet watch + ``` + + Or: + ```dotnetcli dotnet watch run ``` @@ -115,11 +114,11 @@ dotnet watch ⏳ Waiting for a file to change before restarting dotnet... not in the app help; asp.net core tutorial only +- **`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`** When set to `1` or `true`, `dotnet watch` won't refresh browsers when it detects file changes. -- **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`**not in the app help; readme and asp.net core tutorial only +- **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`** When set to `1` or `true`, `dotnet watch` won't launch or refresh browsers for web apps that have `launchBrowser` configured in *launchSettings.json*. -- **`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`**not in the app help; readme and asp.net core tutorial only +- **`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 to `1` or `true`, these optimizations are disabled. -- **`DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`**readme only +- **`DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`** - When set to `1` or `true`, `dotnet watch` won't do special handling for static content files.what is the special handling that it otherwise does? + When set to `1` or `true`, `dotnet watch` won't do special handling for static content files. ## Files watched by default @@ -175,7 +174,7 @@ More files can be watched by adding items to the `Watch` group. For example, the ``` -## Ignore specified items +## Ignore specified files `dotnet watch` will ignore `Compile` and `EmbeddedResource` items that have the `Watch="false"` attribute, as shown in the following example: @@ -196,7 +195,7 @@ More files can be watched by adding items to the `Watch` group. For example, the ## 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: what would you use this for? +`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: ```xml From a6d69a000b5d9786f8730553c74319a95694a67f Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Thu, 5 May 2022 10:39:10 -0700 Subject: [PATCH 05/13] add to toc --- docs/fundamentals/toc.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index df2154f1ab3df..b89dcc6859ae9 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -350,6 +350,9 @@ items: href: ../core/tools/dotnet-tool-update.md - name: dotnet vstest href: ../core/tools/dotnet-vstest.md + - name: dotnet watch + displayName: hot reload + href: ../core/tools/dotnet-watch.md - name: dotnet workload items: - name: dotnet workload install From 0e62abd82838a11a3f83cd86b56fbf232742aca3 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Thu, 5 May 2022 10:43:13 -0700 Subject: [PATCH 06/13] remove todo note --- docs/core/tools/dotnet-watch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index 8faa9377b04a9..a88dbeaa19359 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -155,7 +155,7 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr `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:this list is from the ASP.NET Core tutorial -- is it correct? +By default, the `Compile` and `EmbeddedResource` groups include all files matching the following glob patterns: * `**/*.cs` * `*.csproj` From c9a4d00cce7c2aee4905bf9cd1a344fa770c2060 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Thu, 5 May 2022 12:10:04 -0700 Subject: [PATCH 07/13] tweak wording --- docs/core/tools/dotnet-watch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index a88dbeaa19359..5c76d501af208 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -36,7 +36,7 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`forwarded arguments`** - Arguments to pass to the child `dotnet` process. For example, `run` and options for [dotnet run](dotnet-run.md) or `test` and options for [dotnet test](dotnet-test.md). If not specified, the default is `run` for `dotnet run`. + 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 not specified, the default is `run` for `dotnet run`. ## Options From a435bc09045fe0265b326362f1d5c80adacf6f63 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Fri, 6 May 2022 10:48:02 -0700 Subject: [PATCH 08/13] add link in dotnet doc --- docs/core/tools/dotnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/tools/dotnet.md b/docs/core/tools/dotnet.md index 0e04f4073a9e3..7273c711ba537 100644 --- a/docs/core/tools/dotnet.md +++ b/docs/core/tools/dotnet.md @@ -1,7 +1,7 @@ --- title: dotnet command description: Learn about the dotnet command (the generic driver for the .NET CLI) and its usage. -ms.date: 07/19/2021 +ms.date: 05/06/2022 --- # dotnet command @@ -240,7 +240,7 @@ Starting with .NET Core SDK 2.1.300, a number of tools that were available only | dev-certs | Creates and manages development certificates. | | [ef](/ef/core/miscellaneous/cli/dotnet) | Entity Framework Core command-line tools. | | [user-secrets](/aspnet/core/security/app-secrets) | Manages development user secrets. | -| [watch](/aspnet/core/tutorials/dotnet-watch) | Starts a file watcher that runs a command when files change. | +| [watch](dotnet-watch) | Starts a file watcher that runs a command when files change. | For more information about each tool, type `dotnet --help`. From 25fefadad00387558730cb81bb8d555cbc3564fe Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Fri, 6 May 2022 11:00:15 -0700 Subject: [PATCH 09/13] fix links --- docs/core/tools/dotnet-watch.md | 2 +- docs/core/tools/dotnet.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index 5c76d501af208..c8bb7202a15c4 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -231,6 +231,6 @@ dotnet watch --no-hot-reload * [Hot reload in Visual Studio](/visualstudio/debugger/hot-reload) * [Test execution with hot reload](/visualstudio/test/test-execution-with-hot-reload) -* [Hot reload for ASP.NET Core](/aspnet/core/test/hot-reload?view=aspnetcore-6.0) +* [Hot reload for ASP.NET Core](/aspnet/core/test/hot-reload) * [Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch) * [Supported code changes](/visualstudio/debugger/supported-code-changes-csharp) diff --git a/docs/core/tools/dotnet.md b/docs/core/tools/dotnet.md index 7273c711ba537..a1143b2d6f0cd 100644 --- a/docs/core/tools/dotnet.md +++ b/docs/core/tools/dotnet.md @@ -240,7 +240,7 @@ Starting with .NET Core SDK 2.1.300, a number of tools that were available only | dev-certs | Creates and manages development certificates. | | [ef](/ef/core/miscellaneous/cli/dotnet) | Entity Framework Core command-line tools. | | [user-secrets](/aspnet/core/security/app-secrets) | Manages development user secrets. | -| [watch](dotnet-watch) | Starts a file watcher that runs a command when files change. | +| [watch](dotnet-watch.md) | Starts a file watcher that runs a command when files change. | For more information about each tool, type `dotnet --help`. From 16fd2d1ded63770d879f82be9cad7d83aeadab94 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Tue, 10 May 2022 16:19:14 -0700 Subject: [PATCH 10/13] updates --- docs/core/tools/dotnet-watch.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index c8bb7202a15c4..ae2472e4f307a 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -36,7 +36,7 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`forwarded arguments`** - 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 not specified, the default is `run` for `dotnet run`. + 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`. ## Options @@ -46,11 +46,11 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`--no-hot-reload`** - Suppress [hot reload](#hot-reload) for supported apps. + Suppress [hot reload](#hot-reload) for [supported apps](/visualstudio/debugger/hot-reload#supported-net-app-frameworks-and-scenarios). - **`--non-interactive`** - Runs `dotnet watch` in non-interactive mode. Use this option to prevent console input from being captured. This option is only supported when running with [hot reload](#hot-reload) enabled. + 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. - **`--project `** @@ -58,11 +58,11 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`-q|--quiet`** - Suppresses all output except warnings and errors. + 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. - **`-v|--verbose`** - Shows verbose output. + Shows verbose output for debugging. - **`--version`** @@ -104,6 +104,12 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr dotnet watch run -- arg0 ``` + Or: + + ```dotnetcli + dotnet watch run -- arg0 + ``` + ## Environment variables `dotnet watch` uses the following environment variables: @@ -160,7 +166,9 @@ By default, the `Compile` and `EmbeddedResource` groups include all files matchi * `**/*.cs` * `*.csproj` * `**/*.resx` -* Content files: `wwwroot/**`, `**/*.config`, `**/*.json` +* Content files: `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. @@ -205,7 +213,11 @@ More files can be watched by adding items to the `Watch` group. For example, the ## 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 you receive immediate feedback when you modify your app. +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](/visualstudio/debugger/hot-reload#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 a *rude edit* and `dotnet watch` asks if you want to restart the app: From e973d2e031176302a4018cd9f93ac0cd86b2cb82 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Wed, 11 May 2022 14:13:07 -0700 Subject: [PATCH 11/13] rearrange env vars --- .../tools/dotnet-environment-variables.md | 26 ++-------- docs/core/tools/dotnet-watch.md | 47 +++++++++++-------- 2 files changed, 33 insertions(+), 40 deletions(-) diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index 7f2e1d2f84acf..012d1c672bab4 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -1,7 +1,7 @@ --- title: .NET environment variables description: Learn about the environment variables that you can use to configure the .NET SDK, .NET CLI, and .NET runtime. -ms.date: 01/31/2022 +ms.date: 05/11/2022 --- # .NET environment variables @@ -297,26 +297,6 @@ The typical way to get detailed trace information about application startup is t If set to `true`, invoking `dotnet` won't produce a warning when a preview SDK is being used. -### `DOTNET_WATCH_*` - -The following .NET watch settings are available as environment variables: - -- `DOTNET_WATCH`: The `dotnet watch` command sets this variable to `1` on all child processes launched. -- `DOTNET_WATCH_ITERATION`: The `dotnet watch` command sets this variable to `1` and increments by one each time - a file is changed and the command is restarted. -- `DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`: If set to `1`, or `true`, `dotnet watch` will _not_ perform special handling for static content file. -- `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. -- `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. -- `DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH` -- `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. -- `DOTNET_HOTRELOAD_NAMEDPIPE_NAME`: This value is configured by `dotnet watch` when the app is to be launched, and it specifies the named pipe. - -For more information, see [GitHub: .NET SDK dotnet-watch](https://github.com/dotnet/sdk/blob/main/src/BuiltInTools/dotnet-watch/README.md). - -#### `DOTNET_USE_POLLING_FILE_WATCHER` - -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 class uses `DOTNET_USE_POLLING_FILE_WATCHER` to determine whether the method will rely on the . - ### Configure MSBuild in the .NET CLI 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 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). +### `dotnet watch` environment variables + +For information about `dotnet watch` settings that are available as environment variables, see [dotnet watch environment variables](dotnet-watch.md#environment-variables). + ## See also - [dotnet command](dotnet.md) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index ae2472e4f307a..8fa0c1d504a15 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -1,7 +1,7 @@ --- title: dotnet watch command 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. -ms.date: 05/05/2022 +ms.date: 05/11/2022 --- # dotnet watch @@ -28,7 +28,7 @@ dotnet watch -?|-h|--help 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. -While running `dotnet watch`, you can force the app to rebuild and restart by pressing Ctrl+R in the command shell. +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. ## Arguments @@ -70,7 +70,7 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`--`** - 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. For more information, see [the Examples section](#examples). + 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. ## Examples @@ -107,25 +107,33 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr Or: ```dotnetcli - dotnet watch run -- arg0 + dotnet watch -- run arg0 ``` ## Environment variables `dotnet watch` uses the following environment variables: -- **`DOTNET_USE_POLLING_FILE_WATCHER`** - - When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. - - **`DOTNET_WATCH`** `dotnet watch` sets this variable to `1` 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 value `127.0.0.1` is replaced by `localhost`, and the `http://` and `https://` schemes are replaced with `ws://` and `wss://` respectively. + +- **`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_WATCH_ITERATION`** `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. +- **`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`** + + When set to `1` or `true`, `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: @@ -141,10 +149,6 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr On certain console hosts, these characters may appear garbled. To avoid seeing garbled characters, set this variable to `1` or `true`. -- **`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`** - - When set to `1` or `true`, `dotnet watch` won't refresh browsers when it detects file changes. - - **`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`** When set to `1` or `true`, `dotnet watch` won't launch or refresh browsers for web apps that have `launchBrowser` configured in *launchSettings.json*. @@ -155,7 +159,11 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr - **`DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING`** - When set to `1` or `true`, `dotnet watch` won't do special handling for static content files. + 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`. + +- **`DOTNET_USE_POLLING_FILE_WATCHER`** + + When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. ## Files watched by default @@ -166,7 +174,7 @@ By default, the `Compile` and `EmbeddedResource` groups include all files matchi * `**/*.cs` * `*.csproj` * `**/*.resx` -* Content files: `wwwroot/**` +* 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. @@ -219,7 +227,7 @@ For information about app types and .NET versions that support hot reload, see [ ### 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 a *rude edit* and `dotnet watch` asks if you want to restart the app: +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: ```dotnetcli dotnet watch ⌚ Unable to apply hot reload because of a rude edit. @@ -241,8 +249,9 @@ dotnet watch --no-hot-reload ## See also +* [Tutorial: Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch) * [Hot reload in Visual Studio](/visualstudio/debugger/hot-reload) -* [Test execution with hot reload](/visualstudio/test/test-execution-with-hot-reload) -* [Hot reload for ASP.NET Core](/aspnet/core/test/hot-reload) -* [Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch) -* [Supported code changes](/visualstudio/debugger/supported-code-changes-csharp) +* [Hot reload supported apps](/visualstudio/debugger/hot-reload#supported-net-app-frameworks-and-scenarios) +* [Hot reload supported code changes](/visualstudio/debugger/supported-code-changes-csharp) +* [Hot reload test execution](/visualstudio/test/test-execution-with-hot-reload) +* [Hot reload support for ASP.NET Core](/aspnet/core/test/hot-reload) From 1c8d98833e0ca6cb48cd8334527046bdecee4adc Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Wed, 11 May 2022 14:28:06 -0700 Subject: [PATCH 12/13] move examples to end --- docs/core/tools/dotnet-watch.md | 88 ++++++++++++++++----------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/core/tools/dotnet-watch.md b/docs/core/tools/dotnet-watch.md index 8fa0c1d504a15..84831fcf37f1f 100644 --- a/docs/core/tools/dotnet-watch.md +++ b/docs/core/tools/dotnet-watch.md @@ -72,47 +72,17 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr 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. -## Examples - -- Run `dotnet run` for the project in the current directory whenever source code changes: - - ```dotnetcli - dotnet watch - ``` - - Or: - - ```dotnetcli - dotnet watch run - ``` - -- Run `dotnet test` for the project in the current directory whenever source code changes: - - ```dotnetcli - dotnet watch test - ``` - -- Run `dotnet run --project ./HelloWorld.csproj` whenever source code changes: - - ```dotnetcli - dotnet watch run --project ./HelloWorld.csproj - ``` - -- Run `dotnet run -- arg0` for the project in the current directory whenever source code changes: +## Environment variables - ```dotnetcli - dotnet watch run -- arg0 - ``` +`dotnet watch` uses the following environment variables: - Or: +- **`DOTNET_HOTRELOAD_NAMEDPIPE_NAME`** - ```dotnetcli - dotnet watch -- run arg0 - ``` + This value is configured by `dotnet watch` when the app is to be launched, and it specifies the named pipe. -## Environment variables +- **`DOTNET_USE_POLLING_FILE_WATCHER`** -`dotnet watch` uses the following environment variables: + When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. The class uses `DOTNET_USE_POLLING_FILE_WATCHER` to determine whether the method will rely on the . - **`DOTNET_WATCH`** @@ -122,10 +92,6 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr 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. -- **`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_WATCH_ITERATION`** `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. @@ -161,10 +127,6 @@ While running `dotnet watch`, you can force the app to rebuild and restart by pr 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`. -- **`DOTNET_USE_POLLING_FILE_WATCHER`** - - When set to `1` or `true`, `dotnet watch` uses a polling file watcher instead of . Polling is required for some file systems, such as network shares, Docker mounted volumes, and other virtual file systems. - ## 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. @@ -247,6 +209,44 @@ To disable hot reload when you run `dotnet watch`, use the `--no-hot-reload` opt dotnet watch --no-hot-reload ``` +## Examples + +- Run `dotnet run` for the project in the current directory whenever source code changes: + + ```dotnetcli + dotnet watch + ``` + + Or: + + ```dotnetcli + dotnet watch run + ``` + +- Run `dotnet test` for the project in the current directory whenever source code changes: + + ```dotnetcli + dotnet watch test + ``` + +- Run `dotnet run --project ./HelloWorld.csproj` whenever source code changes: + + ```dotnetcli + dotnet watch run --project ./HelloWorld.csproj + ``` + +- Run `dotnet run -- arg0` for the project in the current directory whenever source code changes: + + ```dotnetcli + dotnet watch run -- arg0 + ``` + + Or: + + ```dotnetcli + dotnet watch -- run arg0 + ``` + ## See also * [Tutorial: Develop ASP.NET Core apps using a file watcher](/aspnet/core/tutorials/dotnet-watch) From 475935f84dd217817a3183be634475f29b2f0cd3 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Thu, 12 May 2022 08:39:05 -0700 Subject: [PATCH 13/13] update dotnet watch description --- docs/core/tools/dotnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet.md b/docs/core/tools/dotnet.md index a1143b2d6f0cd..e69b2a38d7970 100644 --- a/docs/core/tools/dotnet.md +++ b/docs/core/tools/dotnet.md @@ -240,7 +240,7 @@ Starting with .NET Core SDK 2.1.300, a number of tools that were available only | dev-certs | Creates and manages development certificates. | | [ef](/ef/core/miscellaneous/cli/dotnet) | Entity Framework Core command-line tools. | | [user-secrets](/aspnet/core/security/app-secrets) | Manages development user secrets. | -| [watch](dotnet-watch.md) | Starts a file watcher that runs a command when files change. | +| [watch](dotnet-watch.md) | A file watcher that restarts or hot reloads an application when it detects changes in the source code. | For more information about each tool, type `dotnet --help`.