dotnet watch 命令

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

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

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 引用添加到应用的页面：

command

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

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

-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 字符，如以下示例所示：

在某些控制台主机上，这些字符可能会出现乱码。 为了避免看到乱码字符，请将此变量设置为 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 模式匹配的所有文件：

默认情况下，.config 和 .json 文件不会触发 dotnet watch 重启，因为配置系统有自己用来处理配置更改的机制。

可以通过编辑项目文件，将文件添加到监视列表中或从列表中删除。 可以单独指定文件，也可以使用 glob 模式指定。

可以通过将项添加到 Watch 组来监视更多文件。 例如，以下标记扩展了该组，以包括 JavaScript 文件：

dotnet watch 将忽略具有 Watch="false" 属性的 Compile 和 EmbeddedResource 项，如以下示例中所示：

dotnet watch 将忽略具有 Watch="false" 属性的项目引用，如以下示例中所示：

dotnet watch 执行设计时生成以查找要监视的项。 运行此生成时，dotnet watch 会设置属性 DotNetWatchBuild=true。 可以按以下示例所示来使用此属性：

从 .NET 6 开始，dotnet watch 包括对热重载的支持。 热重载功能可用于将更改应用到正在运行的应用，而无需重新生成并重启它。 更改可能是代码文件或静态资产，如样式表文件和 JavaScript 文件。 此功能简化了本地开发体验，因为在你修改应用时，它会立即提供反馈。

有关支持热重载的应用类型和 .NET 版本的信息，请参阅支持的 .NET 应用框架和场景。

文件经过修改后，dotnet watch 确定应用是否可以被热重载。 如果无法进行热重载，则更改称为“原始编辑”，并且 dotnet watch 会询问是否要重启应用：

有关被视为原始编辑的更改类型的信息，请参阅编辑代码并继续调试和不受支持的代码更改。

若要在运行 dotnet watch 时禁用热重载，请使用 --no-hot-reload 选项，如以下示例所示：

每当源代码发生更改时，在当前目录中对项目运行 dotnet run：

或：

每当源代码发生更改时，在当前目录中对项目运行 dotnet test：

每当源代码发生更改时，运行 dotnet run --project ./HelloWorld.csproj：

每当源代码发生更改时，在当前目录中对项目运行 dotnet run -- arg0：

或：