dotnet watch

  • Articolo

Questo articolo si applica a: ✔️ .NET Core 3.1 SDK e versioni successive

Nome

dotnet watch - Riavvia o ricarica l'applicazione specificata oppure esegue un comando dotnet specificato quando vengono rilevate modifiche nel codice sorgente.

Riepilogo

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

dotnet watch -?|-h|--help

Descrizione

Il comando dotnet watch è un watcher di file. Quando rileva una modifica, esegue il comando dotnet run o un comando dotnet specificato. Se viene eseguito dotnet run e la modifica è supportata per il ricaricamento rapido, ricarica l'applicazione specificata. Se la modifica non è supportata, riavvia l'applicazione. Questo processo consente uno sviluppo iterativo rapido dalla riga di comando.

Durante l'esecuzione di dotnet watch, è possibile forzare la ricompilazione e il riavvio dell'app premendo CTRL+R nella shell dei comandi. Questa funzionalità è disponibile solo durante l'esecuzione dell'app. Ad esempio, se si esegue dotnet watch in un'app console che termina prima di premere CTRL+R, premere CTRL+R non ha alcun effetto. Tuttavia, in questo caso dotnet watch è ancora in corso il controllo dei file e riavvia l'app se un file viene aggiornato.

Compressione delle risposte

Se dotnet watch viene eseguito per un'app che usa la compressione delle risposte, lo strumento non può inserire lo script di aggiornamento del browser. La versione .NET 7 e successiva dello strumento visualizza un messaggio di avviso simile al seguente:

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

Impossibile configurare l'inserimento di script di aggiornamento del browser nella risposta. Ciò potrebbe essere stato causato dalla codifica del contenuto della risposta: 'br'. Valutare la possibilità di disabilitare la compressione delle risposte.

In alternativa alla disabilitazione della compressione delle risposte, aggiungere manualmente il riferimento JavaScript di aggiornamento del browser alle pagine dell'app:

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

Argomenti

  • command

    dotnet watch possibile eseguire qualsiasi comando inviato tramite l'eseguibile dotnet, ad esempio comandi dell'interfaccia della riga di comando predefiniti e strumenti globali. Se è possibile eseguire dotnet <command>, è possibile eseguire dotnet watch <command>. Se il comando figlio non è specificato, il valore predefinito è run per dotnet run.

  • forwarded arguments

    Gli argomenti forniti dopo un trattino doppio (--) vengono passati al processo figlio dotnet. Se si esegue dotnet watch run, questi argomenti sono opzioni per dotnet run. Se si esegue dotnet watch test, questi argomenti sono opzioni per il test dotnet.

Opzioni

  • --list

    Elenca tutti i file individuati senza avviare il watcher.

  • --no-hot-reload

    Eliminare il ricaricamento rapido per le app supportate.

  • --non-interactive

    Viene eseguito dotnet watch in modalità non interattiva. Usare questa opzione per impedire che venga richiesto l'input della console. Quando il ricaricamento rapido è abilitato e viene rilevata una modifica non applicabile, dotnet watch riavvia l'app. Disponibile da .NET 7 SDK.

  • --project <PATH>

    Specifica il percorso del file di progetto da eseguire (solo cartella o incluso il nome del file di progetto). Se non specificato, per impostazione predefinita il percorso corrisponde alla directory corrente.

  • -q|--quiet

    Elimina tutti gli output generati dal comando dotnet watch ad eccezione di avvisi ed errori. L'opzione non viene passata ai comandi figlio. Ad esempio, l'output da dotnet restore e dotnet run continua a essere restituito.

  • -v|--verbose

    Mostra l'output dettagliato per il debug.

  • --version

    Mostra la versione di dotnet watch.

  • --

    L'opzione double-dash ('--') può essere usata per delimitare le opzioni dotnet watch dagli argomenti che verranno passati al processo figlio. Il suo uso è facoltativo. Quando l'opzione a trattino doppio non viene usata, dotnet watch considera il primo argomento non riconosciuto come l'inizio degli argomenti che deve passare al processo figlio dotnet.

Variabili di ambiente

dotnet watch usa le variabili di ambiente seguenti:

  • DOTNET_HOTRELOAD_NAMEDPIPE_NAME

    Questo valore viene configurato da dotnet watch quando l'app deve essere avviata e specifica la named pipe.

  • DOTNET_USE_POLLING_FILE_WATCHER

    Se impostato su 1 o true, dotnet watch usa un watcher di file di polling anziché System.IO.FileSystemWatcher. Il polling è necessario per alcuni file system, ad esempio condivisioni di rete, volumi montati Docker e altri file system virtuali. La classe PhysicalFileProvider usa DOTNET_USE_POLLING_FILE_WATCHER per determinare se il metodo PhysicalFileProvider.Watch si baserà sul PollingFileChangeToken.

  • DOTNET_WATCH

    dotnet watch imposta questa variabile su 1 in tutti i processi figlio che vengono avviati.

  • DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

    Come parte di dotnet watch, il meccanismo del server di aggiornamento del browser legge questo valore per determinare l'ambiente host WebSocket. Il valore 127.0.0.1 viene sostituito da localhoste gli schemi http:// e https:// vengono sostituiti rispettivamente con ws:// e wss://.

  • DOTNET_WATCH_ITERATION

    dotnet watch imposta questa variabile su 1 e incrementa di uno ogni volta che un file viene modificato e il comando riavvia o ricarica rapidamente l'applicazione.

  • DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

    Se impostato su 1 o true, dotnet watch non aggiornerà i browser quando rileva le modifiche apportate ai file.

  • DOTNET_WATCH_SUPPRESS_EMOJIS

    Con .NET SDK 6.0.300 e versioni successive, dotnet watch genera caratteri non ASCII nella console, come illustrato nell'esempio seguente:

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

    In alcuni host della console, questi caratteri potrebbero apparire incomprensibili. Per evitare di visualizzare caratteri incomprensibili, impostare questa variabile su 1 o true.

  • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

    Se impostato su 1 o true, dotnet watch non avvierà o aggiornerà i browser per le app Web che hanno launchBrowser configurato in launchSettings.json.

  • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

    Per impostazione predefinita, dotnet watch ottimizza la compilazione evitando determinate operazioni, ad esempio l'esecuzione del ripristino o la rivalutazione del set di file watched in ogni modifica del file. Se questa variabile è impostata su 1 o true, queste ottimizzazioni sono disabilitate.

  • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

    Se impostato su 1 o true, dotnet watch non eseguirà una gestione speciale per i file di contenuto statici. dotnet watch imposta la proprietà MSBuild DotNetWatchContentFiles su false.

  • DOTNET_WATCH_RESTART_ON_RUDE_EDIT

    Se impostato su 1 o true, dotnet watch verrà sempre riavviato in caso di modifiche non applicabili invece di chiedere.

File guardati per impostazione predefinita

dotnet watch controlla tutti gli elementi nel gruppo di elementi Watch nel file di progetto. Per impostazione predefinita, questo gruppo include tutti gli elementi nei gruppi Compile e EmbeddedResource. dotnet watch analizza anche l'intero grafico dei riferimenti al progetto e controlla tutti i file all'interno di tali progetti.

Per impostazione predefinita, i gruppi Compile e EmbeddedResource includono tutti i file corrispondenti ai modelli GLOB seguenti:

  • **/*.cs
  • *.csproj
  • **/*.resx
  • File di contenuto nelle app Web: wwwroot/**

Per impostazione predefinita, file con estensione .config e .json non attivano un riavvio dotnet watch perché il sistema di configurazione dispone di meccanismi specifici per la gestione delle modifiche di configurazione.

I file possono essere aggiunti all'elenco espressioni di controllo o rimossi dall'elenco modificando il file di progetto. I file possono essere specificati singolarmente o usando modelli GLOB.

Guarda altri file

Altri file possono essere visualizzati aggiungendo elementi al gruppo di Watch. Ad esempio, il markup seguente estende il gruppo in modo da includere i file JavaScript:

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

Ignorare i file specificati

dotnet watch ignorerà gli elementi Compile e EmbeddedResource con l'attributo Watch="false", come illustrato nell'esempio seguente:

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

dotnet watch ignorerà i riferimenti al progetto con l'attributo Watch="false", come illustrato nell'esempio seguente:

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

Configurazione avanzata

dotnet watch esegue una compilazione in fase di progettazione per trovare gli elementi da controllare. Quando questa compilazione viene eseguita, dotnet watch imposta la proprietà DotNetWatchBuild=true. Questa proprietà può essere utilizzata come illustrato nell'esempio seguente:

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

Ricaricamento rapido

A partire da .NET 6, dotnet watch include il supporto per il ricaricamento rapido. Ricaricamento rapido è una funzionalità che consente di applicare modifiche a un'app in esecuzione senza dover ricompilarla e riavviarla. Le modifiche possono essere apportate ai file di codice o agli asset statici, ad esempio file del foglio di stile e file JavaScript. Questa funzionalità semplifica l'esperienza di sviluppo locale, perché fornisce un feedback immediato quando si modifica l'app.

Per informazioni sui tipi di app e sulle versioni .NET che supportano il ricaricamento rapido, vedere Framework e scenari di app .NET supportati.

Modifica non applicabile

Quando un file viene modificato, dotnet watch determina se l'app può essere ricaricata rapidamente. Se non può essere ricaricato rapidamente, la modifica viene chiamata modifica non applicabile e dotnet watch chiede se si vuole riavviare l'app:

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)?
  • Sì: riavvia l'app.
  • No: lascia l'app in esecuzione senza le modifiche applicate.
  • Sempre: riavvia l'app e non richiede più modifiche non applicabili.
  • Mai: lascia l'app in esecuzione senza le modifiche applicate e non richiede più modifiche non applicabili.

Per informazioni sui tipi di modifiche considerati modifiche non applicabili, vedere Modificare il codice e continuare il debug e Modifiche al codice non supportate.

Per disabilitare il ricaricamento rapido quando si esegue dotnet watch, usare l'opzione --no-hot-reload, come illustrato nell'esempio seguente:

dotnet watch --no-hot-reload

Esempi

  • Eseguire dotnet run per il progetto nella directory corrente ogni volta che viene modificato il codice sorgente:

    dotnet watch

    Oppure:

    dotnet watch run

  • Eseguire dotnet test per il progetto nella directory corrente ogni volta che viene modificato il codice sorgente:

    dotnet watch test

  • Eseguire dotnet run --project ./HelloWorld.csproj ogni volta che cambia il codice sorgente:

    dotnet watch run --project  ./HelloWorld.csproj

  • Eseguire dotnet run -- arg0 per il progetto nella directory corrente ogni volta che viene modificato il codice sorgente:

    dotnet watch run -- arg0

    Oppure:

    dotnet watch -- run arg0

Vedi anche