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，強制應用程式重建並重新啟動。 只有應用程式正在執行時，才能使用這項功能。 例如，如果您在按下 Ctrl+R 之前就結束的主控台應用程式上執行 dotnet watch，按 Ctrl+R 不會有任何作用。 不過，在此情況下 dotnet watch，仍會監看檔案，並在檔案更新時重新開啟應用程式。

回應壓縮

如果 dotnet watch 針對使用回應壓縮的應用程式執行，此工具就無法插入瀏覽器重新整理指令碼。 工具的 .NET 7 和更新版本會顯示如下的警告訊息：

警告：Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]

無法在回應上設定瀏覽器重新整理指令碼插入。 這可能是由回應的 Content-Encoding：'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 主機環境。 值 127.0.0.1 會由 localhost 取代，而 http:// 和 https:// 配置會分別取代為 ws:// 和 wss://。

  • DOTNET_WATCH_ITERATION

    dotnet watch 每次變更檔案時，會將此變數設定為 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 重新開機，因為組態系統有自己的處理組態變更的機制。

檔案可以新增至 watch 清單，或藉由編輯專案檔從清單中移除。 檔案可以個別或使用 Glob 模式指定。

監看其他檔案

將項目新增至 Watch 群組，即可監看更多檔案。 例如，下列標記會擴充該群組以包含 JavaScript 檔案：

<ItemGroup>
  <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>

忽略指定的檔案

dotnet watch 將會忽略 Compile 和 EmbeddedResource 具有 Watch="false" 屬性的項目，如下列範例所示：

<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

另請參閱