dotnet watch

  • Artikel

Dieser Artikel gilt für: ✔️ .NET Core 3.1 SDK und höher

Name

dotnet watch: Führt einen Neustart oder einen Hot Reload der angegebenen Anwendung aus oder führt einen angegebenen dotnet-Befehl aus, wenn Änderungen im Quellcode erkannt werden.

Übersicht

dotnet watch [<command>]
  [--list]
  [--no-hot-reload] [--non-interactive]
  [--project <PROJECT>]
  [-q|--quiet] [-v|--verbose]
  [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Beschreibung

Der Befehl dotnet watch ist eine Dateiüberwachung. Wenn eine Änderung erkannt wird, wird der Befehl dotnet run oder ein angegebener dotnet-Befehl ausgeführt. Wenn dotnet run ausgeführt wird und Hot Reloads für die Änderung unterstützt werden, wird ein Hot Reload der angegebenen Anwendung ausgeführt. Wenn die Änderung nicht unterstützt wird, wird die Anwendung neu gestartet. Dieser Prozess empfiehlt sich für die schnelle iterative Entwicklung an der Befehlszeile.

Während der Ausführung von dotnet watch können Sie eine erneute Erstellung und einen Neustart der App erzwingen, indem Sie in der Befehlsshell STRG+R drücken. Dieses Feature ist nur verfügbar, während die App ausgeführt wird. Wenn Sie beispielsweise dotnet watch für eine Konsolen-App ausführen, die endet, bevor Sie STRG+R drücken, hat das Drücken von STRG+R keine Auswirkungen. In diesem Fall werden Dateien jedoch weiterhin von dotnet watch überwacht, und die App wird neu gestartet, wenn eine Datei aktualisiert wird.

Antwortkomprimierung

Wenn dotnet watch für eine App ausgeführt wird, die Antwortkomprimierung verwendet, kann das Tool das Skript zur Browseraktualisierung nicht einschleusen. Die Version .NET 7 und höhere Versionen des Tools zeigen eine Warnmeldung wie die folgende an:

warn: Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]

Die Einschleusung des Skripts für die Browseraktualisierung kann für die Antwort nicht konfiguriert werden. Dies wurde möglicherweise durch die Inhaltscodierung „br“ der Antwort verursacht. Erwägen Sie, die Antwortkomprimierung zu deaktivieren.

Als Alternative zum Deaktivieren der Antwortkomprimierung fügen Sie den Seiten der App manuell den Browseraktualisierungs-JavaScript-Verweis hinzu:

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

Argumente

  • command

    dotnet watch kann jeden Befehl ausführen, der über die ausführbare dotnet-Datei verteilt wird, z. B. integrierte CLI-Befehle und globale Tools. Wenn Sie dotnet <command> ausführen können, können Sie auch dotnet watch <command> ausführen. Wenn der untergeordnete Befehl nicht angegeben wird, ist run der Standardwert für dotnet run.

  • forwarded arguments

    Argumente, die nach einem doppelten Bindestrich (--) angegeben werden, werden an den untergeordneten dotnet-Prozess übergeben. Wenn Sie dotnet watch run ausführen, stellen diese Argumente Optionen für dotnet run dar. Wenn Sie dotnet watch test ausführen, stellen diese Argumente Optionen für dotnet test dar.

Optionen

  • --list

    Listet alle ermittelten Dateien auf, ohne die Überwachung zu starten.

  • --no-hot-reload

    Unterdrückt hot reload für unterstützte Apps.

  • --non-interactive

    Führt dotnet watch im nicht interaktiven Modus aus. Verwenden Sie diese Option, um zu verhindern, dass Konsoleneingaben angefordert werden. Wenn Hot Reload aktiviert ist und eine nicht unterstützte Bearbeitung erkannt wird, startet dotnet watch die App neu. Verfügbar ab dem .NET 7 SDK.

  • --project <PATH>

    Gibt den Pfad der auszuführenden Projektdatei an (nur Ordner oder mit dem Namen der Projektdatei). Wenn nicht angegeben, wird standardmäßig das aktuelle Verzeichnis gewählt.

  • -q|--quiet

    Unterdrückt alle Ausgaben, die vom dotnet watch-Befehl generiert werden, mit Ausnahme von Warnungen und Fehlern. Die Option wird nicht an untergeordnete Befehle übergeben. Beispielsweise werden Ausgaben von dotnet restore und dotnet run weiterhin ausgegeben.

  • -v|--verbose

    Zeigt eine ausführliche Ausgabe für das Debuggen an.

  • --version

    Zeigt die Version von dotnet watch an.

  • --

    Die Doppelstrichoption (‚--‘) kann verwendet werden, um dotnet watch-Optionen von Argumenten zu trennen, die an den untergeordneten Prozess übergeben werden. Ihre Verwendung ist optional. Wenn die Doppelstrichoption nicht verwendet wird, sieht dotnet watch das erste nicht erkannte Argument als Anfang der Argumente an, die an den untergeordneten dotnet-Prozess übergeben werden sollen.

Umgebungsvariablen

dotnet watch verwendet die folgenden Umgebungsvariablen:

  • DOTNET_HOTRELOAD_NAMEDPIPE_NAME

    Dieser Wert wird durch dotnet watch konfiguriert, wenn die App gestartet werden soll, und gibt die Named Pipe an.

  • DOTNET_USE_POLLING_FILE_WATCHER

    Wenn diese Einstellung auf 1 oder true festgelegt ist, verwendet dotnet watch eine Polling-Dateiüberwachung anstelle von System.IO.FileSystemWatcher. Polling ist für einige Dateisysteme erforderlich, z. B. Netzwerkfreigaben, in Docker eingebundene Volumes und andere virtuelle Dateisysteme. Die Klasse PhysicalFileProvider verwendet DOTNET_USE_POLLING_FILE_WATCHER, um zu bestimmen, ob die Methode PhysicalFileProvider.Watch auf der PollingFileChangeToken basiert.

  • DOTNET_WATCH

    dotnet watch legt diese Variable für alle untergeordneten Prozesse, die es startet, auf 1 fest.

  • DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

    Im Rahmen von dotnet watch liest der Servermechanismus für die Browseraktualisierung diesen Wert, um die WebSocket-Hostumgebung zu bestimmen. Der Wert 127.0.0.1 wird durch localhost ersetzt, und die Schemas http:// und https:// werden durch ws:// bzw. wss:// ersetzt.

  • DOTNET_WATCH_ITERATION

    dotnet watch legt diese Variable auf 1 fest und erhöht sie bei jeder Änderung einer Datei und bei jedem Neustart oder Hot Reload der Anwendung um eins.

  • DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

    Bei Festlegung auf 1 oder true führt dotnet watch keine Browseraktualisierung durch, wenn es Dateiänderungen erkennt.

  • DOTNET_WATCH_SUPPRESS_EMOJIS

    Mit .NET SDK 6.0.300 und höher gibt dotnet watch ASCII-fremde Zeichen an die Konsole aus, wie im folgenden Beispiel gezeigt:

    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...

    Auf bestimmten Konsolenhosts werden diese Zeichen möglicherweise unlesbar angezeigt. Legen Sie diese Variable auf 1 oder true fest, um die Anzeige unlesbarer Zeichen zu verhindern.

  • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

    Bei den Werten 1 oder true führt dotnet watch für Web-Apps mit einer launchBrowser-Konfiguration in launchSettings.json keinen Start und keine Aktualisierungen aus.

  • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

    dotnet watch optimiert die Erstellung standardmäßig durch Vermeiden bestimmter Vorgänge, etwa die Ausführung der Wiederherstellung oder die Neuauswertung der Menge der überwachten Dateien bei jeder Dateiänderung. Wenn diese Variable auf 1 oder true festgelegt ist, werden diese Optimierungen deaktiviert.

  • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

    Bei einer Festlegung auf 1 oder true führt dotnet watch keine Sonderbehandlung für Dateien mit statischem Inhalt durch. dotnet watch legt die MSBuild-Eigenschaft DotNetWatchContentFiles auf false fest.

  • DOTNET_WATCH_RESTART_ON_RUDE_EDIT

    Für 1 oder true führt dotnet watch bei nicht unterstützten Bearbeitungen ohne Nachfrage einen Neustart durch.

Standardmäßig überwachte Dateien

dotnet watch überwacht alle Elemente in der Watch-Elementgruppe in der Projektdatei. Standardmäßig enthält diese Gruppe alle Elemente in den Gruppen Compile und EmbeddedResource. dotnet watch überprüft außerdem das gesamte Diagramm der Projektverweise und überwacht alle Dateien innerhalb dieser Projekte.

Standardmäßig enthalten die Gruppen Compile und EmbeddedResource alle Dateien, die den folgenden Globmustern entsprechen:

  • **/*.cs
  • *.csproj
  • **/*.resx
  • Inhaltsdateien in Web-Apps: wwwroot/**

Standardmäßig lösen CONFIG- und JSON-Dateien keinen Neustart durch dotnet watch aus, da das Konfigurationssystem über eigene Mechanismen zur Behandlung von Konfigurationsänderungen verfügt.

Dateien können durch Bearbeiten der Projektdatei der Überwachungsliste hinzugefügt oder aus der Liste entfernt werden. Dabei können die Dateien einzeln oder mithilfe von Globmustern angegeben werden.

Überwachen weiterer Dateien

Weitere Dateien können überwacht werden, indem Sie der Gruppe Watch Elemente hinzufügen. Das folgende Markup erweitert diese Gruppe beispielsweise um JavaScript-Dateien:

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

Ignorieren angegebener Dateien

dotnet watch ignoriert Compile- und EmbeddedResource-Elemente mit dem Watch="false"-Attribut, wie im folgenden Beispiel gezeigt:

<ItemGroup>
  <Compile Update="Generated.cs" Watch="false" />
  <EmbeddedResource Update="Strings.resx" Watch="false" />
</ItemGroup>

dotnet watch ignoriert Projektverweise mit dem Watch="false"-Attribut, wie im folgenden Beispiel gezeigt:

<ItemGroup>
  <ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>

Erweiterte Konfiguration

dotnet watch führt einen Build zur Entwurfszeit aus, um zu überwachende Elemente zu finden. Wenn dieser Build ausgeführt wird, legt dotnet watch die Eigenschaft DotNetWatchBuild=true fest. Diese Eigenschaft kann wie im folgenden Beispiel gezeigt verwendet werden:

<ItemGroup Condition="'$(DotNetWatchBuild)'=='true'">
  <!-- only included in the project when dotnet-watch is running -->
</ItemGroup>

Erneut laden

Ab .NET 6 beinhaltet dotnet watch Unterstützung für Hot Reload. Hot Reload ist ein Feature, mit dem Sie Änderungen auf eine ausgeführte App anwenden können, ohne sie neu erstellen und neu starten zu müssen. Die Änderungen können Codedateien oder statische Ressourcen wie Stylesheetdateien und JavaScript-Dateien betreffen. Dieses Feature optimiert die lokale Entwicklungsumgebung, da es sofortiges Feedback gibt, wenn Sie Ihre App ändern.

Informationen zu App-Typen und .NET-Versionen, die Hot Reload unterstützen, finden Sie unter Unterstützte .NET-App-Frameworks und -Szenarien.

Nicht unterstützte Bearbeitungsvorgänge

Wenn eine Datei geändert wird, bestimmt dotnet watch, ob für die App ein Hot Reload ausgeführt werden kann. Wenn kein Hot Reload durchgeführt werden kann, wird die Änderung als nicht unterstützte Bearbeitung bezeichnet, und dotnet watch fragt Sie, ob Sie die App neu starten möchten:

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)?
  • Ja: Die App wird neu gestartet.
  • Nein: Die App wird ohne Anwendung der Änderungen weiter ausgeführt.
  • Immer: Die App wird neu gestartet, und nicht unterstützte Bearbeitungen werden nicht mehr angefragt.
  • Nie: Die App wird ohne Anwendung der Änderungen weiter ausgeführt, und nicht unterstützte Bearbeitungen werden nicht mehr angefragt.

Informationen dazu, welche Arten von Änderungen als nicht unterstützte Bearbeitungen gelten, finden Sie unter Bearbeiten von Code und Fortsetzen des Debuggens und Nicht unterstützte Änderungen am Code.

Zum Deaktivieren von Hot Reloads bei der Ausführung von dotnet watch verwenden Sie die Option --no-hot-reload, wie im folgenden Beispiel gezeigt:

dotnet watch --no-hot-reload

Beispiele

  • dotnet run für das Projekt im aktuellen Verzeichnis bei jeder Quellcodeänderung ausführen:

    dotnet watch

    Oder:

    dotnet watch run

  • dotnet test für das Projekt im aktuellen Verzeichnis bei jeder Quellcodeänderung ausführen:

    dotnet watch test

  • dotnet run --project ./HelloWorld.csproj bei jeder Quellcodeänderung ausführen:

    dotnet watch run --project  ./HelloWorld.csproj

  • dotnet run -- arg0 für das Projekt im aktuellen Verzeichnis bei jeder Quellcodeänderung ausführen:

    dotnet watch run -- arg0

    Oder:

    dotnet watch -- run arg0

Weitere Informationen