通过

dotnet watch

本文适用于：✔️ .NET 6 SDK 及更高版本

Name

dotnet watch - 检测到源代码更改时重启或 热重载 指定的应用程序，或运行指定的 dotnet 命令。

概要

dotnet watch [<command>]
  [--artifacts-path <ARTIFACTS_DIR>] [--disable-build-servers]
  [--list] [--no-hot-reload] [--no-self-contained]
  [--non-interactive] [--project <PROJECT>] [--sc|--self-contained]
  [-q|--quiet] [-v|--verbose] [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Description

该 dotnet watch 命令是文件观察程序。 检测到更改时，它会运行 dotnet run 命令或指定的 dotnet 命令。 如果运行 dotnet run，并且 热重载支持更改，则会热重载指定的应用程序。 如果不支持更改，则会重启应用程序。 此过程允许从命令行进行快速迭代开发。

运行 dotnet watch时，可以通过在命令行界面中按 Ctrl+R 来强制应用重新生成和重启。 仅当应用正在运行时，此功能才可用。 例如，如果在按 Ctrl+R 之前结束的控制台应用上运行 dotnet watch ，请按 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>
}

Arguments

  • <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或buildtest指定 。<command>

    如果未指定子命令，则默认值为 rundotnet run.

  • <forwarded arguments>

    在双短划线（--）之后提供的参数将传递给子 dotnet 进程。 如果正在运行 dotnet watch run，这些参数是 dotnet 运行的选项。 如果正在运行 dotnet watch test，这些参数是 dotnet 测试的选项。

选项

  • --artifacts-path <ARTIFACTS_DIR>

    执行命令中的所有生成输出文件都将位于指定路径下的子文件夹中，由项目分隔。 有关详细信息，请参阅 Artifacts 输出布局。 自 .NET 8 SDK 起可用。

  • --disable-build-servers

    强制运行命令以忽略任何永久性生成服务器。 此选项提供一种一致的方法来禁止对生成缓存的所有使用，这会强制从头开始生成。 当缓存可能由于某种原因而损坏或不正确时，不依赖缓存的生成非常有用。 自 .NET 7 SDK 起可用。

  • --list

    列出所有发现的文件，而无需启动观察程序。

  • --no-self-contained

    等效于 --self-contained false。

  • --no-hot-reload

    禁止对受支持的应用进行热重载。

  • --non-interactive

    在非交互式模式下运行 dotnet watch 。 使用此选项可防止请求控制台输入。 启用热重载并检测到 粗鲁的编辑 时，dotnet watch 将重启应用。 自 .NET 7 SDK 起可用。

  • --project <PATH>

    指定要运行的项目文件的路径（仅文件夹或包括项目文件名）。 如果未指定，则默认为当前目录。

  • --sc|--self-contained

    使用应用程序发布 .NET 运行时，以便不需要在目标计算机上安装运行时。 默认值为 true。

  • -q|--quiet

    取消命令生成 dotnet watch 的所有输出，但警告和错误除外。 此选项不会传递给子命令。 例如，输出并继续dotnet restoredotnet run输出。

  • -v|--verbose

    显示用于调试的详细输出。

  • --version

    显示 . 的版本 dotnet watch。

  • --

    双划线选项 （'--'） 可用于分隔dotnet watch将传递给子进程的自变量中的选项。 它的使用是可选的。 如果未使用双划线选项， dotnet watch 请考虑第一个无法识别的参数是它应传递到子 dotnet 进程的自变量的开头。

  • -?|-h|--help

    打印出有关如何使用命令的说明。

环境变量

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 主机环境。 该值127.0.0.1被localhost替换，并http://分别替换为ws://和https://wss://方案。

  • DOTNET_WATCH_ITERATION

    dotnet watch 每次更改文件时，将此变量设置为 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或设置为， dotnet watchtrue则不会为在launchSettings.json中配置的 Web 应用launchBrowser启动或刷新浏览器。

  • 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 将忽略 Compile 具有 EmbeddedResource 该属性的 Watch="false" 项，如以下示例所示：

<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 SDK 开始， 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

另请参阅