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 は、組み込みの CLI コマンドやグローバル ツールなど、dotnet 実行可能ファイルを介してディスパッチされる任意のコマンドを実行できます。 dotnet <command> を実行できる場合は、dotnet watch <command> を実行できます。 子コマンドが指定されていない場合、既定値は dotnet run の run です。

• forwarded arguments

  二重ダッシュ (--) の後に指定された引数は、子 dotnet プロセスに渡されます。 dotnet watch run を実行している場合、これらの引数は dotnet 実行のオプションです。 dotnet watch test を実行している場合、これらの引数は dotnet 実行のオプションです。

オプション

• --list

  ウォッチャーを起動せずに、検出されたすべてのファイルを一覧表示します。

• --no-hot-reload

  サポートされているアプリのホット リロードを抑制します。

• --non-interactive

  非対話型モードで dotnet watch を実行します。 コンソール入力が要求されないようにするには、このオプションを使用します。 ホット リロードが有効で、Rude 編集が検出されると、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 に設定し、ファイルが変更されて、コマンドによりアプリケーションが再起動またはホット リロードされるたびに 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 の再起動はトリガーされません。

ファイルはウォッチ リストに追加することも、プロジェクト ファイルを編集してリストから削除することもできます。 ファイルは個別に指定することも、glob パターンを使用して指定することもできます。

追加ファイルを監視する

Watch グループに項目を追加することで、さらに多くのファイルを監視できます。 たとえば、次のマークアップにより、JavaScript ファイルを含むようにそのグループが拡張されます。

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

指定したファイルを無視する

次の例に示すように、dotnet watch では、Watch="false" 属性を持つCompile および EmbeddedResource の項目は無視されます。

<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 アプリのフレームワークとシナリオに関するページを参照してください。

Rude 編集

ファイルが変更されると、アプリをホット リロードできるかどうかが dotnet watch によって判断されます。 ホット リロードできない場合、変更は Rude 編集と呼ばれ、アプリを再起動するかどうかが 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)?

• はい: アプリを再起動します。
• いいえ: 変更を適用せずに、アプリを実行したままにします。
• 常時: アプリを再起動します。Rude 編集のプロンプトが表示されなくなります。
• なし: 変更を適用せずにアプリを実行したままにします。Rude 編集を求めるメッセージが表示されなくなります。

Rude 編集と見なされる変更の種類については、コードを編集してデバッグを続行するおよびコードへのサポートされていない変更に関する記事を参照してください。

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
  

こちらもご覧ください

• チュートリアル: ファイル ウォッチャーを使用した ASP.NET Core アプリの開発
• Visual Studio でのホット リロード
• ホット リロードがサポートされているアプリ
• ホット リロードでサポートされているコードの変更
• ホット リロード テストの実行
• ASP.NET Core のホット リロード サポート