dotnet watch
本文适用于: ✔️ .NET Core 3.1 SDK 及更高版本
名称
dotnet watch
- 在检测到源代码中的更改时,重启或热重载指定的应用程序,或者运行指定的 dotnet 命令。
摘要
dotnet watch [<command>]
[--list]
[--no-hot-reload] [--non-interactive]
[--project <PROJECT>]
[-q|--quiet] [-v|--verbose]
[--version]
[--] <forwarded arguments>
dotnet watch -?|-h|--help
说明
dotnet watch
命令是一个文件观察程序。 当它检测到更改时,会运行dotnet run
命令或指定的dotnet
命令。 如果它运行dotnet run
,且支持热重载的更改时,它会热重载指定的应用程序。 如果不支持更改,它会重启应用程序。 此过程对从命令行中进行快速迭代开发很有帮助。
在运行 dotnet watch
时,可以通过在命令行界面中按 Ctrl+R 来强制应用重新生成和重启。 只有当应用正在运行时,此功能才可用。 例如,如果在控制台应用上运行 dotnet watch
,该应用在你按 Ctrl+R 之前结束,则按 Ctrl+R 不起作用。 但是,在这种情况下,dotnet watch
仍在监视文件,如果文件已更新,它将重启应用。
响应压缩
如果dotnet watch
针对使用响应压缩的应用运行,该工具无法注入浏览器刷新脚本。 该工具的 .NET 7 及更高版本会显示如下所示的警告消息:
warn: Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]
无法针对响应配置浏览器刷新脚本注入。 这可能由响应的内容编码“br”引起。 请考虑禁用响应压缩。
作为禁用响应压缩的替代方法,手动将浏览器刷新 JavaScript 引用添加到应用的页面:
@if (Environment.GetEnvironmentVariable("__ASPNETCORE_BROWSER_TOOLS") is not null)
{
<script src="/_framework/aspnetcore-browser-refresh.js"></script>
}
参数
<command>
在 .NET 7 SDK 及更早版本中,
dotnet watch
可以运行通过dotnet
可执行文件调度的任何命令,例如内置 CLI 命令和全局工具。 如果可以运行dotnet <command>
,则可以运行dotnet watch <command>
。在 .NET 8 SDK 及更高版本中,
dotnet watch
可以运行dotnet run
、dotnet build
或dotnet test
。 指定run
或build
test
指定 。<command>
如果未指定子命令,则默认为用于
dotnet run
的run
。<forwarded arguments>
在双划线(
--
)后提供的参数会传递给子dotnet
进程。 如果正在运行dotnet watch run
,则这些参数是dotnet run的选项。 如果正在运行dotnet watch test
,则这些参数是dotnet test的选项。
选项
--list
列出所有发现的文件,不启动观察程序。
--no-hot-reload
--non-interactive
在非交互模式下运行
dotnet watch
。 使用此选项可防止请求控制台输入。 启用热重载并检测到原始编辑时,dotnet watch 将重启应用。 自 .NET 7 SDK 起可用。--project <PATH>
指定要运行的项目文件的路径(仅文件夹或包括项目文件名)。 如果未指定,则默认为当前目录。
-q|--quiet
禁止除警告和错误之外的由
dotnet watch
命令生成的所有输出。 该选项不会被传递给子命令。 例如,从dotnet restore
输出并继续输出dotnet run
。-v|--verbose
显示详细输出,以进行调试。
--version
显示
dotnet watch
的版本。--
双划线选项(“--”)可用于将
dotnet watch
选项与传递给子进程的参数分开。 它的使用是可选的。 如果未使用双划线选项,dotnet watch
会将第一个无法识别的参数视为它应传递到dotnet
子进程的参数的开头。
环境变量
dotnet watch
使用以下环境变量:
DOTNET_HOTRELOAD_NAMEDPIPE_NAME
此值由
dotnet watch
在启动应用程序时配置,用于指定命名管道。DOTNET_USE_POLLING_FILE_WATCHER
如果设置为
1
或true
,则dotnet watch
使用轮询文件观察程序,而不是 System.IO.FileSystemWatcher。 对于某些文件系统(如网络共享、Docker 装载卷和其他虚拟文件系统),轮询是必需的。 PhysicalFileProvider 类使用DOTNET_USE_POLLING_FILE_WATCHER
来确定 PhysicalFileProvider.Watch 方法是否将依赖于 PollingFileChangeToken。DOTNET_WATCH
在所有启动的子进程上,
dotnet watch
将此变量设置为1
。DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME
作为
dotnet watch
的一部分,浏览器刷新服务器机制会读取此值以确定 WebSocket 主机环境。 用localhost
替换值127.0.0.1
,用ws://
和wss://
分别替换http://
和https://
方案。DOTNET_WATCH_ITERATION
dotnet watch
将此变量设置为1
,并在每次更改文件和命令重启或热重载应用程序时递增 1。DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH
如果设置为
1
或true
,则dotnet watch
检测到文件更改时不会刷新浏览器。DOTNET_WATCH_SUPPRESS_EMOJIS
使用 .NET SDK 6.0.300 及更高版本,
dotnet watch
向控制台发出非 ASCII 字符,如以下示例所示: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...
在某些控制台主机上,这些字符可能会出现乱码。 为了避免看到乱码字符,请将此变量设置为
1
或true
。DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER
如果设置为
1
或true
,dotnet watch
就不会针对在 launchSettings.json 中配置了launchBrowser
的 Web 应用启动或刷新浏览器。DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM
默认情况下,
dotnet watch
通过避免某些操作(如在每次文件更改时运行还原或重新评估监视的文件集)来优化生成。 如果此变量设置为1
或true
,则禁用这些优化。DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING
设置为
1
或true
时,dotnet watch
不会对静态内容文件执行特殊处理。dotnet watch
将 MSBuild 属性DotNetWatchContentFiles
设置为false
。DOTNET_WATCH_RESTART_ON_RUDE_EDIT
设置为
1
或true
时,dotnet watch
将始终在粗鲁的编辑时重启,而不是询问。
默认监视的文件
dotnet watch
监视项目文件的 Watch
项组中的所有项。 默认情况下,此组包括 Compile
和 EmbeddedResource
组中的所有项。 dotnet watch
还会扫描项目引用的整个图,并监视这些项目内的所有文件。
默认情况下,Compile
和 EmbeddedResource
组包括与以下 glob 模式匹配的所有文件:
**/*.cs
*.csproj
**/*.resx
- Web 应用中的内容文件:
wwwroot/**
默认情况下,.config 和 .json 文件不会触发 dotnet watch 重启,因为配置系统有自己用来处理配置更改的机制。
可以通过编辑项目文件,将文件添加到监视列表中或从列表中删除。 可以单独指定文件,也可以使用 glob 模式指定。
监视其他文件
可以通过将项添加到 Watch
组来监视更多文件。 例如,以下标记扩展了该组,以包括 JavaScript 文件:
<ItemGroup>
<Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>
忽略指定的文件
dotnet watch
将忽略具有 Watch="false"
属性的 Compile
和 EmbeddedResource
项,如以下示例中所示:
<ItemGroup>
<Compile Update="Generated.cs" Watch="false" />
<EmbeddedResource Update="Strings.resx" Watch="false" />
</ItemGroup>
dotnet watch
将忽略具有 Watch="false"
属性的项目引用,如以下示例中所示:
<ItemGroup>
<ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>
高级配置
dotnet watch
执行设计时生成以查找要监视的项。 运行此生成时,dotnet watch
会设置属性 DotNetWatchBuild=true
。 可以按以下示例所示来使用此属性:
<ItemGroup Condition="'$(DotNetWatchBuild)'=='true'">
<!-- only included in the project when dotnet-watch is running -->
</ItemGroup>
热重载
从 .NET 6 开始,dotnet watch
包括对热重载的支持。 热重载功能可用于将更改应用到正在运行的应用,而无需重新生成并重启它。 更改可能是代码文件或静态资产,如样式表文件和 JavaScript 文件。 此功能简化了本地开发体验,因为在你修改应用时,它会立即提供反馈。
有关支持热重载的应用类型和 .NET 版本的信息,请参阅支持的 .NET 应用框架和场景。
原始编辑
文件经过修改后,dotnet watch
确定应用是否可以被热重载。 如果无法进行热重载,则更改称为“原始编辑”,并且 dotnet watch
会询问是否要重启应用:
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)?
- 是:重启应用。
- 否:将应用保持在运行状态而不应用更改。
- 始终:重启应用,不再提示原始编辑。
- 从不:将应用保持在运行状态而不应用更改,并且不再提示进行原始编辑。
有关被视为原始编辑的更改类型的信息,请参阅编辑代码并继续调试和不受支持的代码更改。
若要在运行 dotnet watch
时禁用热重载,请使用 --no-hot-reload
选项,如以下示例所示:
dotnet watch --no-hot-reload
示例
每当源代码发生更改时,在当前目录中对项目运行
dotnet run
:dotnet watch
或:
dotnet watch run
每当源代码发生更改时,在当前目录中对项目运行
dotnet test
:dotnet watch test
每当源代码发生更改时,运行
dotnet run --project ./HelloWorld.csproj
:dotnet watch run --project ./HelloWorld.csproj
每当源代码发生更改时,在当前目录中对项目运行
dotnet run -- arg0
:dotnet watch run -- arg0
或:
dotnet watch -- run arg0