共用方式為

使用檔案監看員開發 ASP.NET Core 應用程式

由 里克·安德森 和 維克多·赫杜加奇

dotnet watch 是一種工具，可在來源檔案變更時執行 .NET CLI 命令。 例如，檔案變更可以觸發編譯、測試執行或部署。

本教學課程使用具有兩個端點的現有 Web API：一個會傳回總和，另一個會傳回產品。 產品功能有缺陷，在本教學課程中已修正。

下載 範例應用程式。 它包含兩個專案： WebApp （ASP.NET Core Web API）和 WebAppTests（Web API 的單元測試）。

在命令殼層中，流覽至 WebApp 資料夾。 執行下列命令：

dotnet run

Note

您可以使用 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.

在網頁瀏覽器中，巡覽至 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 監看員工具隨附於 .NET SDK 2.1.300 版。 使用舊版 .NET SDK 時，需要下列步驟。

  1. 將Microsoft.DotNet.Watcher.Tools套件參考新增至.csproj檔案：

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

  2. 執行下列命令來安裝 Microsoft.DotNet.Watcher.Tools 套件：

    dotnet restore

使用 .NET CLI 指令 dotnet watch

任何 .NET CLI 命令 都可以使用 dotnet watch來執行。 For example:

Command 使用 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 監視 測試

在 dotnet watch run 資料夾中執行。 主控台輸出表示 watch 已啟動。

在 Web 應用程式上執行 dotnet watch run 會啟動瀏覽器，一旦準備就緒，就會巡覽至應用程式的 URL。 dotnet watch 這樣做的方式是讀取應用程式的控制台輸出，並等候 所 WebHost顯示的就緒訊息。

dotnet watch 當偵測到監看的檔案變更時，會重新整理瀏覽器。 若要這樣做，監看式命令會將中間件插入應用程式，以修改應用程式所建立的 HTML 回應。 中間件會將 JavaScript 腳本區塊新增至頁面，以允許 dotnet watch 指示瀏覽器重新整理。 目前，所有監看的檔案的變更，包括靜態內容，例如.html 和 .css 檔案，會導致應用程式被重建。

dotnet watch:

  • 預設只監看會影響建置的檔案。
  • 任何額外的監看檔案（透過組態）仍然會導致組建發生。

如需設定的詳細資訊，請參閱本檔中 的 dotnet-watch 組態 。

Note

您可以使用 dotnet watch --project <PROJECT> 指定要監看的專案。 例如，從範例應用程式的根目錄執行 dotnet watch --project WebApp run ，也會執行並監看 WebApp 專案。

使用 dotnet watch 進行變更

請確定 dotnet watch 正在執行中。

修正 Product方法中的MathController.cs 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

  1. 將 Product 的 MathController.cs 方法變更為回傳總和。 儲存檔案。

  2. 在命令提示字元中，導航到 WebAppTests 資料夾。

  3. 執行 dotnet restore。

  4. 執行 dotnet watch test。 其輸出指出測試失敗，且監看員正在等候檔案變更：

    Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.
Test Run Failed.

  5. 修正方法 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 可以設定為忽略其預設設定。 若要忽略特定檔案，請將 Watch="false" 屬性新增至檔案中的 .csproj 項目定義：

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

某些組態選項可以透過環境變數傳遞至 dotnet watch 。 可用的變數如下：

Setting Description
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 嘗試啟動 Web 應用程式的瀏覽器，這些應用程式在 launchBrowser 中已設定 launchSettings.json。 如果設定為 「1」 或 「true」 則會隱藏此行為。
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH dotnet watch run 嘗試在偵測到檔案變更時更新瀏覽器。 如果設定為 「1」 或 「true」 則會隱藏此行為。 如果 DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER 已設定，也會隱藏此行為。

Browser refresh

dotnet watch 將程式碼注入至應用程式中，讓應用程式在內容變更時能重新整理瀏覽器。 在某些情況下，例如當應用程式啟用回應壓縮時， dotnet watch可能無法插入 文稿。 針對開發中的這類情況，請手動將腳本插入應用程式。 例如，若要將 Web 應用程式設定為手動插入文稿，請更新設定檔案以包含 _framework/aspnet-browser-refresh.js：

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

Non-ASCII characters

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。
  • Last updated on