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 run
、dotnet build
或dotnet test
。 指定指定run
、build
或test
<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