使用文件观察程序开发 ASP.NET Core 应用

项目
11/06/2024

dotnet watch 是一种在源文件更改时运行 .NET CLI 命令的工具。例如，文件更改可能触发编译、测试执行或部署。

本教程使用一个现有 Web API 和两个终结点：分别返回两个数的总和以及乘积。乘积的方法有一个 bug，本教程将会对其进行修复。

下载示例应用。它包含两个项目：WebApp (ASP.NET Core Web API) 和 WebAppTests（用于 Web API 的单元测试）。

在命令行界面中，导航到 WebApp 文件夹。运行下面的命令：

dotnet run

注意

可使用 dotnet run --project <PROJECT> 来指定要运行的项目。例如，从示例应用的根路径运行 dotnet run --project WebApp 还会运行 WebApp 项目。

控制台输出会显示如下类似的消息（表示应用正在运行且正在等待请求）：

$ dotnet run
Hosting environment: Development
Content root path: C:/Docs/aspnetcore/tutorials/dotnet-watch/sample/WebApp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

在 Web 浏览器中，导航到 http://localhost:<port number>/api/math/sum?a=4&b=5。应该会显示结果 9。

导航到产品 API (http://localhost:<port number>/api/math/product?a=4&b=5)。它会返回 9，而不是所预期的 20。本教程的后面部分将解决该问题。

将 `dotnet watch` 添加到项目

dotnet watch 文件观察程序工具随 2.1.300 版本的 .NET Core SDK 一同提供。使用早期版本的 .NET Core SDK 时，需要执行以下步骤。

将 Microsoft.DotNet.Watcher.Tools 包引用添加到 .csproj 文件：

<ItemGroup>
    <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="2.0.0" />
</ItemGroup>

运行以下命令，安装 Microsoft.DotNet.Watcher.Tools 包：
```
dotnet restore
```

使用 `dotnet watch` 运行 .NET CLI 命令

任何 .NET CLI 命令都可与 dotnet watch 一起运行。例如：

命令	带 watch 的命令
dotnet run	dotnet watch run
dotnet run -f netcoreapp3.1	dotnet watch run -f netcoreapp3.1
dotnet run -f netcoreapp3.1 -- --arg1	dotnet watch run -f netcoreapp3.1 -- --arg1
dotnet test	dotnet watch test

运行“WebApp”文件夹中的 dotnet watch run。控制台输出指示 watch 已启动。

在 Web 应用上运行 dotnet watch run 将启动一个浏览器，一旦准备就绪，该浏览器将导航到应用的 URL。 dotnet watch 通过读取应用的控制台输出并等待 WebHost 显示的就绪消息来完成此操作。

当 dotnet watch 检测到监视文件的更改时刷新浏览器。为此，watch 命令向应用注入一个中间件，用于修改应用创建的 HTML 响应。中间件将 JavaScript 脚本块添加到页面，使 dotnet watch 可以指示浏览器进行刷新。目前，对所有监视的文件（包括静态内容，如 .html 和 .css 文件）的更改都会导致重建应用。

dotnet watch：

默认情况下，仅监视影响生成的文件。
任何（通过配置）额外监视的文件仍然会导致生成发生。

有关配置的详细信息，请参阅本文档中的 dotnet-watch 配置。

注意

可使用 dotnet watch --project <PROJECT> 来指定要监视的项目。例如，从示例应用的根路径运行 dotnet watch --project WebApp run 还会运行并监视 WebApp 项目。

使用 `dotnet watch` 执行更改

确保 dotnet watch 正在运行。

在 MathController.cs 的 Product 方法中修复该 bug，使其返回产品而非总和：

public static int Product(int a, int b)
{
    return a * b;
}

保存该文件。控制台输出指示 dotnet watch 已检测到文件更改并已重启应用。

验证 http://localhost:<port number>/api/math/product?a=4&b=5 是否返回正确结果。

使用 `dotnet watch` 运行测试

将 MathController.cs 的 Product 方法改回返回总和。保存该文件。
在命令外壳中，导航到“WebAppTests”文件夹。
运行 dotnet restore。
运行 dotnet watch test。其输出指示测试失败且观察程序正在等待文件更改：
```
Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.
Test Run Failed.
```
修复 Product 方法代码，使其返回乘积。保存该文件。

dotnet watch 检测到文件更改并重新运行测试。控制台输出指示测试通过。

自定义要监视的文件列表

默认情况下，dotnet-watch 跟踪与以下 glob 模式匹配的所有文件：

**/*.cs
*.csproj
**/*.resx
内容文件：wwwroot/**、**/*.config、**/*.json

通过编辑 .csproj 文件，可向监视列表添加更多项。可以单独指定项或使用 glob 模式指定。

<ItemGroup>
    <!-- extends watching group to include *.js files -->
    <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>

从要监视的文件中排除

dotnet-watch 可配置为忽略其默认设置。要忽略特定文件，请在 .csproj 文件中向某项的定义中添加 Watch="false" 特性：

<ItemGroup>
    <!-- exclude Generated.cs from dotnet-watch -->
    <Compile Include="Generated.cs" Watch="false" />

    <!-- exclude Strings.resx from dotnet-watch -->
    <EmbeddedResource Include="Strings.resx" Watch="false" />

    <!-- exclude changes in this referenced project -->
    <ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>

<ItemGroup>
     <!-- Exclude all Content items from being watched. -->
    <Content Update="@(Content)" Watch="false" />
</ItemGroup>

自定义监视项目

dotnet-watch 不仅限于 C# 项目。可以创建自定义监视项目来处理不同的方案。假设项目布局如下：

test/
- UnitTests/UnitTests.csproj
- IntegrationTests/IntegrationTests.csproj

如果目标是监视这两个项目，请创建配置为监视这两个项目的自定义项目文件：

<Project>
    <ItemGroup>
        <TestProjects Include="**\*.csproj" />
        <Watch Include="**\*.cs" />
    </ItemGroup>

    <Target Name="Test">
        <MSBuild Targets="VSTest" Projects="@(TestProjects)" />
    </Target>

    <Import Project="$(MSBuildExtensionsPath)\Microsoft.Common.targets" />
</Project>

要对这两个项目启动文件监视，请更改为 test 文件夹。请执行以下命令：

dotnet watch msbuild /t:Test

当任一测试项目中的任何文件发生更改时，将会执行 VSTest。

dotnet-watch 配置

一些配置选项可以通过环境变量传递给 dotnet watch。可用变量有：

设置	说明
`DOTNET_USE_POLLING_FILE_WATCHER`	如果设置为“1”或“true”，则 `dotnet watch` 使用轮询文件观察程序，而不是 CoreFx 的 `FileSystemWatcher`。在监视网络共享或 Docker 装入卷上的文件时使用。
`DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM`	默认情况下，`dotnet watch` 通过避免某些操作（如在每次文件更改时运行还原或重新评估监视的文件集）来优化生成。如果设置为“1”或“true”，则禁用这些优化。
`DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`	`dotnet watch run` 尝试为在 `launchSettings.json` 中配置了 `launchBrowser` 的 Web 应用启动浏览器。如果设置为“1”或“true”，则抑制此行为。
`DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH`	`dotnet watch run` 检测到文件更改时尝试刷新浏览器。如果设置为“1”或“true”，则抑制此行为。如果设置了 `DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER`，则也会抑制此行为。

浏览器刷新

dotnet watch 将脚本注入应用，使应用可以在内容发生更改时刷新浏览器。在某些情况下（例如，当应用启用响应压缩时），dotnet watch 可能无法注入脚本。如果开发过程中出现这类情况，请手动将脚本注入应用。例如，若要将 Web 应用配置为手动注入脚本，请更新布局文件以包括 _framework/aspnet-browser-refresh.js：

@* _Layout.cshtml *@
<environment names="Development">
    <script src="/_framework/aspnetcore-browser-refresh.js"></script>
</environment>

非 ASCII 字符

Visual Studio 17.2 及更高版本包括 .NET SDK 6.0.300 及更高版本。使用 .NET SDK 和 6.0.300 更高版本时，dotnet-watch 在热重载会话期间向控制台发出非 ASCII 字符。在某些控制台主机（例如 Windows conhost）上，这些字符可能会出现乱码。为了避免出现乱码，请考虑以下方法之一：

配置 DOTNET_WATCH_SUPPRESS_EMOJIS=1 环境变量以禁止发出这些值。
切换到支持呈现非 ASCII 字符的其他终端，例如 https://github.com/microsoft/terminal。

通过

使用文件观察程序开发 ASP.NET Core 应用

将 dotnet watch 添加到项目

使用 dotnet watch 运行 .NET CLI 命令

使用 dotnet watch 执行更改

使用 dotnet watch 运行测试