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 rundotnet builddotnet test。 指定runbuildtest指定 。<command>

    如果未指定子命令,则默认为用于 dotnet runrun

  • <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

    如果设置为 1true,则 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

    如果设置为 1true,则 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...
    

    在某些控制台主机上,这些字符可能会出现乱码。 为了避免看到乱码字符,请将此变量设置为 1true

  • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

    如果设置为 1truedotnet watch 就不会针对在 launchSettings.json 中配置了 launchBrowser 的 Web 应用启动或刷新浏览器。

  • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

    默认情况下,dotnet watch 通过避免某些操作(如在每次文件更改时运行还原或重新评估监视的文件集)来优化生成。 如果此变量设置为 1true,则禁用这些优化。

  • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

    设置为 1true 时,dotnet watch 不会对静态内容文件执行特殊处理。 dotnet watch 将 MSBuild 属性 DotNetWatchContentFiles 设置为 false

  • DOTNET_WATCH_RESTART_ON_RUDE_EDIT

    设置为1true时,dotnet watch将始终在粗鲁的编辑时重启,而不是询问。

默认监视的文件

dotnet watch 监视项目文件的 Watch 项组中的所有项。 默认情况下,此组包括 CompileEmbeddedResource 组中的所有项。 dotnet watch 还会扫描项目引用的整个图,并监视这些项目内的所有文件。

默认情况下,CompileEmbeddedResource 组包括与以下 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" 属性的 CompileEmbeddedResource 项,如以下示例中所示:

<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
    

另请参阅