dotnet watch

Artigo
03/28/2023

Este artigo se aplica a: ✔️ SDK do .NET Core 3.1 e versões posteriores

Nome

dotnet watch - Reinicia ou recarrega o aplicativo especificado na camada de acesso frequente ou executa um comando dotnet especificado quando as alterações no código-fonte são detectadas.

Sinopse

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

dotnet watch -?|-h|--help

Descrição

O comando dotnet watch é um observador de arquivos. Quando detecta uma alteração, ele executa o comando dotnet run ou um comando especificado dotnet. Se executar dotnet run e a alteração for compatível com a recarga na camada de acesso frequente, ele fará a recarga do aplicativo especificado na camada de acesso frequente. Se não houver para a alteração, ele reiniciará o aplicativo. Esse processo permite o desenvolvimento iterativo rápido a partir da linha de comando.

Durante a execução de dotnet watch, você pode forçar o aplicativo a recompilar e reiniciar pressionando Ctrl+R no shell de comando. Esse recurso só está disponível enquanto o aplicativo está em execução. Por exemplo, se você executar dotnet watch em um aplicativo de console que termina antes de pressionar Ctrl+R, pressionar Ctrl+R não terá efeito. No entanto, nesse caso, dotnet watch ainda está observando arquivos e reiniciará o aplicativo se um arquivo for atualizado.

Compactação de resposta

Se dotnet watch for executado para um aplicativo que usa compactação de resposta, a ferramenta não poderá injetar o script de atualização do navegador. O .NET 7 e versão posterior da ferramenta exibem uma mensagem de aviso como a seguinte:

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

Não é possível configurar a injeção de script de atualização do navegador na resposta. Isso pode ter sido causado pela codificação de conteúdo da resposta: 'br'. Considere desabilitar a compactação de resposta.

Como alternativa para desabilitar a compactação de resposta, adicione manualmente a referência JavaScript de atualização do navegador às páginas do aplicativo:

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

Argumentos

command

dotnet watch pode executar qualquer comando expedido por meio do executável dotnet, como comandos da CLI internos e ferramentas globais. Se você pode executar dotnet <command>, você pode executar dotnet watch <command>. Se o comando filho não for especificado, o padrão será run para dotnet run.
forwarded arguments

Argumentos fornecidos após um traço duplo (--) são passados para o processo filho dotnet. Se você está executando dotnet watch run, esses argumentos são opções para dotnet run. Se você está executando dotnet watch test, esses argumentos são opções para dotnet test.

Opções

--list

Lista todos os arquivos descobertos sem iniciar o observador.
--no-hot-reload

Suprime o recarregamento de camada de acesso frequente para aplicativos com suporte.
--non-interactive

Executa dotnet watch no modo não interativo. Use essa opção para impedir que a entrada do console seja solicitada. Quando a recarga ativada é habilitada e uma rude edit é detectada, o relógio dotnet reinicia o aplicativo. Disponível desde o SDK do .NET 7.
--project <PATH>

Especifica o caminho do arquivo de projeto a ser executado (somente pasta ou incluindo o nome do arquivo de projeto). Se não é especificado, ele usa como padrão o diretório atual.
-q|--quiet

Suprime toda a saída gerada pelo comando dotnet watch, exceto avisos e erros. A opção não é passada para comandos filho. Por exemplo, saída de dotnet restore e dotnet run continua a ser saída.
-v|--verbose

Mostra a saída detalhada para depuração.
--version

Obtém a versão de dotnet watch.
--

A opção de traço duplo ('--') pode ser usada para delimitar opções de argumentos dotnet watch que serão passados para o processo filho. O uso é opcional. Quando a opção de traço duplo não é usada, dotnet watch considera o primeiro argumento não reconhecido como o início dos argumentos que ele deve passar para o processo filho dotnet .

Variáveis de ambiente

dotnet watch usa as seguintes variáveis de ambiente:

DOTNET_HOTRELOAD_NAMEDPIPE_NAME

Esse valor é configurado quando o aplicativo dotnet watch deve ser iniciado e especifica o pipe nomeado.
DOTNET_USE_POLLING_FILE_WATCHER

Quando definido para 1 ou true, dotnet watch usa um observador de arquivo de sondagem em vez de System.IO.FileSystemWatcher. A sondagem é necessária para alguns sistemas de arquivos, como compartilhamentos de rede, volumes montados do Docker e outros sistemas de arquivos virtuais. A classe PhysicalFileProvider usa DOTNET_USE_POLLING_FILE_WATCHER para determinar se o método PhysicalFileProvider.Watch dependerá do PollingFileChangeToken.
DOTNET_WATCH

dotnet watch define essa variável para 1 todos os processos filho que ele inicia.
DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

Como parte de dotnet watch, o mecanismo de servidor de atualização do navegador lê esse valor para determinar o ambiente do host WebSocket. O valor 127.0.0.1 é substituído por localhost, e os esquemas http:// e https://são substituídos ws:// e wss://, respectivamente.
DOTNET_WATCH_ITERATION

dotnet watch define essa variável como 1 e incrementa em uma cada vez que um arquivo é alterado e o comando reinicia ou recarrega o aplicativo.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

Quando definido como 1 ou true, dotnet watch não atualizará navegadores quando detectar alterações de arquivo.
DOTNET_WATCH_SUPPRESS_EMOJIS

Com o SDK do .NET 6.0.300 e posterior, dotnet watch emite caracteres não ASCII para o console, conforme mostrado no exemplo a seguir:
```
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...
```
Em determinados hosts de console, esses caracteres podem aparecer embaralhados. Para evitar ver caracteres embaralhados, defina essa variável como 1 ou true.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

Quando definido como 1 ou true, dotnet watch não iniciará ou atualizará navegadores para aplicativos Web que foram launchBrowser configurados em launchSettings.json.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

Por padrão, dotnet watch otimiza o build evitando determinadas operações, como executar a restauração ou reavaliar o conjunto de arquivos assistidos em cada alteração de arquivo. Se essa variável estiver definida para 1 ou true, essas otimizações serão desabilitadas.
DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

Quando definido como 1 ou true, dotnet watch não fará tratamento especial para arquivos de conteúdo estático. dotnet watch define a propriedade MSBuild DotNetWatchContentFiles para false.
DOTNET_WATCH_RESTART_ON_RUDE_EDIT

Quando definidos como 1 ou true, dotnet watch sempre serão reiniciados em edições rudes, em vez de perguntar.

Arquivos assistidos por padrão

dotnet watch observa todos os itens no grupo de itens Watch no arquivo do projeto. Por padrão, esse grupo inclui todos os itens nos grupos Compile e EmbeddedResource. dotnet watch também examina todo o grafo de referências de projeto e observa todos os arquivos dentro desses projetos.

Por padrão, os grupos Compile e EmbeddedResource incluem todos os arquivos que correspondem aos seguintes padrões glob:

**/*.cs
*.csproj
**/*.resx
Arquivos de conteúdo em aplicativos Web: wwwroot/**

Por padrão, .confige arquivos .json não disparam uma reinicialização do relógio dotnet porque o sistema de configuração tem seus próprios mecanismos para lidar com alterações de configuração.

Os arquivos podem ser adicionados à lista de observação ou removidos da lista editando o arquivo de projeto. Os arquivos podem ser especificados individualmente ou usando padrões glob.

Arquivos de inspeção adicionais

Mais arquivos podem ser observados adicionando itens ao grupo Watch. Por exemplo, a marcação a seguir estende esse grupo para incluir arquivos JavaScript:

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

Arquivos especificados pelo usuário

dotnet watch ignorará itens Compile e EmbeddedResource que têm o atributo Watch="false", conforme mostrado no exemplo a seguir:

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

dotnet watch ignorará itens referências do projeto que têm o atributo Watch="false", conforme mostrado no exemplo a seguir:

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

Configuração avançada

dotnet watch executa um build de tempo de design para localizar itens a serem observados. Quando essa build é executada, dotnet watch define a propriedade DotNetWatchBuild=true. Essa propriedade pode usada conforme mostrado no exemplo a seguir:

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

Hot Reload

A partir do .NET 6, dotnet watch inclui suporte para recarregamento de camada de acesso frequente. O recarregamento de camada de acesso frequente é um recurso que permite aplicar alterações a um aplicativo em execução sem precisar recompilá-lo e reiniciá-lo. As alterações podem ser arquivos de código ou ativos estáticos, como arquivos de folha de estilos e arquivos JavaScript. Esse recurso simplifica a experiência de desenvolvimento local, pois fornece comentários imediatos quando você modifica seu aplicativo.

Para obter informações sobre tipos de aplicativo e versões do .NET que dão suporte à recarga ativa, consulte Estruturas e cenários de aplicativos .NET com suporte.

Edições rudes

Quando um arquivo é modificado, dotnet watch determina se o aplicativo pode ser recarregado. Se ele não puder ser recarregado a quente, a alteração será chamada de edição rude e dotnet watch perguntará se você deseja reiniciar o aplicativo:

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)?

Yes: reinicia o aplicativo.
No: deixa o aplicativo em execução sem as alterações aplicadas.
Always: reinicia o aplicativo e não solicita mais edições rudes.
Never: deixa o aplicativo em execução sem as alterações aplicadas e não solicita mais edições rudes.

Para obter informações sobre quais tipos de alterações são consideradas edições rudes, consulte Editar código e continuar depurando e alterações sem suporte no código.

Para desabilitar a recarga ativa ao executar dotnet watch, use a opção --no-hot-reload, conforme mostrado no exemplo a seguir:

dotnet watch --no-hot-reload

Exemplos

Execute dotnet run o projeto no diretório atual sempre que o código-fonte for alterado:
```
dotnet watch
```
Ou:
```
dotnet watch run
```
Execute o projeto dotnet test no diretório atual sempre que o código-fonte for alterado:
```
dotnet watch test
```
Execute dotnet run --project ./HelloWorld.csproj sempre que o código-fonte for alterado:
```
dotnet watch run --project  ./HelloWorld.csproj
```
Execute o projeto dotnet run -- arg0 no diretório atual sempre que o código-fonte for alterado:
```
dotnet watch run -- arg0
```
Ou:
```
dotnet watch -- run arg0
```