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

    dotnet watch可以运行通过dotnet可执行文件调度的任何命令，例如内置 CLI 命令和全局工具。 如果可以运行dotnet <command>，则可以运行dotnet watch <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

另请参阅