閱讀英文

共用方式為


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>

    在 .NET 7 SDK 和更早版本中, dotnet watch 可以執行透過 dotnet 可執行檔分派的任何命令,例如內建 CLI 命令和全域工具。 如果可以執行 dotnet <command>,就可以執行 dotnet watch <command>

    在 .NET 8 SDK 和更新版本中, dotnet watch 可以執行 dotnet rundotnet builddotnet test。 指定指定 runbuildtest<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 restoredotnet 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 主機環境。 值 127.0.0.1 會由 localhost 取代,而 http://https:// 配置會分別取代為 ws://wss://

  • DOTNET_WATCH_ITERATION

    dotnet watch 每次變更檔案時,會將此變數設定為 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

    設定為 1true 時,dotnet 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 重新開機,因為組態系統有自己的處理組態變更的機制。

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

監看其他檔案

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

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

忽略指定的檔案

dotnet watch 將會忽略 CompileEmbeddedResource 具有 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
    

另請參閱