共用方式為

dotnet 監視

此文章適用於：✔️ .NET 6 SDK 與更新版本

名稱

dotnet watch - 偵測到原始程式碼變更時，重新啟動或 熱重新載入 指定的應用程式，或執行指定的 dotnet 命令。

概要

dotnet watch [<command>]
  [--artifacts-path <ARTIFACTS_DIR>] [--disable-build-servers]
  [--list] [--no-hot-reload] [--no-self-contained]
  [--non-interactive] [--project <PROJECT>] [--sc|--self-contained]
  [-q|--quiet] [-v|--verbose] [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Description

該 dotnet watch 命令是檔案監看器。 當它偵測到變更時，它會執行 dotnet run 命令或指定的 dotnet 命令。 如果它執行 dotnet run，且 熱重新載入支援變更，則會熱重新載入指定的應用程式。 如果不支援變更，則會重新啟動應用程式。 此過程可實現從命令列快速迭代開發。

執行 dotnet watch時，您可以在命令 shell 中按 Ctrl+R 來強制應用程式重建並重新啟動。 此功能僅在應用程序運行時可用。 例如，如果您在按 Ctrl+R 之前結束的主控台應用程式上執行 dotnet watch ，則按 Ctrl+R 沒有任何效果。 但是，在這種情況下 dotnet watch ，仍在監視文件，如果文件更新，將重新啟動應用程序。

回應壓縮

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

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

無法在回應上設定瀏覽器重新整理指令碼插入。 這可能是由回應的內容編碼：「br」所造成。 請考慮停用回應壓縮。

作為停用回應壓縮的替代方案，請手動將瀏覽器重新整理 JavaScript 參考新增至應用程式的頁面：

@if (Environment.GetEnvironmentVariable("__ASPNETCORE_BROWSER_TOOLS") is not null)
{
    <script src="/_framework/aspnetcore-browser-refresh.js"></script>
}

Arguments

  • <command>

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

    在 .NET 8 SDK 和更新版本中， dotnet watch 可以執行 dotnet run、 dotnet build或 dotnet test。 指定 runbuild、 test或 <command> 。

    如果未指定子命令，則預設值為 rundotnet run。

  • <forwarded arguments>

    在雙破折號 （--） 之後提供的引數會傳遞至子 dotnet 處理程序。 如果您正在執行 dotnet watch run，這些引數是 dotnet run 的選項。 如果您正在執行 dotnet watch test，這些引數是 dotnet test 的選項。

選項

  • --artifacts-path <ARTIFACTS_DIR>

    執行命令的所有建置輸出檔案都會位於指定路徑下的子資料夾中，並以專案分隔。 如需詳細資訊，請參閱 成品輸出配置。 自 .NET 8 SDK 起提供。

  • --disable-build-servers

    強制命令忽略任何持續性組建伺服器。 此選項提供一致的方式來停用所有建置快取的使用，以強制從頭開始建置。 當快取可能損毀或因某些原因而不正確時，不依賴快取的組建很有用。 自 .NET 7 SDK 起提供。

  • --list

    列出所有探索到的檔案，而不啟動監看器。

  • --no-self-contained

    將你的應用程式發佈為依賴框架的應用程式。 目標電腦上必須安裝相容的 .NET 執行階段，才能執行您的應用程式。

  • --no-hot-reload

    禁止支援應用程式的熱重新載入。

  • --non-interactive

    以非互動模式執行 dotnet watch 。 使用此選項可防止要求主控台輸入。 啟用熱重新載入並偵測到 粗魯編輯 時，dotnet 監看會重新啟動應用程式。 自 .NET 7 SDK 起提供。

  • --project <PATH>

    指定要執行的專案檔案路徑 （僅資料夾或包含專案檔名）。 如果未指定，則會預設為目前目錄。

  • --sc|--self-contained

    使用您的應用程式發佈 .NET 執行階段，因此不需要在目標電腦上安裝執行階段。

  • -q|--quiet

    隱藏命令產生 dotnet watch 的所有輸出，但警告和錯誤除外。 此選項不會傳遞至子命令。 例如，輸出 dotnet restore 和 dotnet run 繼續輸出。

  • -v|--verbose

    顯示用於偵錯的詳細輸出。

  • --version

    顯示 的版本 dotnet watch。

  • --

    雙破折號選項 （'--'） 可用來分隔dotnet watch選項，以將傳遞至子進程的引數。 它的使用是可選的。 未使用雙破折號選項時， dotnet watch 會將第一個無法辨識的引數視為它應該傳遞至子 dotnet 進程的引數的開頭。

  • -?|-h|--help

    輸出有關如何使用命令的說明。

環境變數

dotnet watch 使用下列環境變數：

  • DOTNET_HOTRELOAD_NAMEDPIPE_NAME

    此值是由應用程式啟動時設定的 dotnet watch ，並指定具名管道。

  • DOTNET_USE_POLLING_FILE_WATCHER

    當設定為 1 或 時，true會使用輪詢檔案監看器，而不是 dotnet watchSystem.IO.FileSystemWatcher。 某些檔案系統需要輪詢，例如網路共用、Docker 掛載磁碟區和其他虛擬檔案系統。 類別用PhysicalFileProviderDOTNET_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 ，並在每次變更檔案且指令重新啟動或熱重新載入應用程式時遞增 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 ，將不會啟動或重新整理已 launchBrowser 在 launchSettings.json中設定的 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 監看重新啟動，因為組態系統有自己的機制來處理組態變更。

檔案可以新增至監看清單，或透過編輯專案檔案從清單中移除。 檔案可以個別指定，也可以使用 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 SDK 開始， 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

另請參閱

  • Last updated on