dotnet watch

Artigo
05/10/2023

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

Name

dotnet watch - Reinicia ou recarrega frequentemente a aplicação especificada ou executa um comando dotnet especificado, quando são detetadas alterações no código fonte.

Sinopse

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

dotnet watch -?|-h|--help

Description

O dotnet watch comando é um observador de ficheiros. Quando deteta uma alteração, executa o dotnet run comando ou um comando especificado dotnet . Se executar dotnet rune a alteração for suportada para recarregamento frequente, recarrega frequentemente a aplicação especificada. Se a alteração não for suportada, reinicia a aplicação. Este processo permite um desenvolvimento iterativo rápido a partir da linha de comandos.

Ao executar dotnet watcho , pode forçar a aplicação a reconstruir e reiniciar ao premir Ctrl+R na shell de comandos. Esta funcionalidade só está disponível enquanto a aplicação estiver em execução. Por exemplo, se executar dotnet watch numa aplicação de consola que termine antes de premir Ctrl+R, premir Ctrl+R não terá qualquer efeito. No entanto, nesse caso dotnet watch , ainda está a ver ficheiros e reiniciará a aplicação se um ficheiro for atualizado.

Compressão de resposta

Se dotnet watch for executada para uma aplicação que utiliza compressão de resposta, a ferramenta não consegue injetar o script de atualização do browser. A versão .NET 7 e posterior da ferramenta apresenta uma mensagem de aviso semelhante à seguinte:

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

Não é possível configurar a injeção do script de atualização do browser na resposta. Isto pode ter sido causado pela Codificação de Conteúdo da resposta: "br". Considere desativar a compressão de resposta.

Como alternativa à desativação da compressão de resposta, adicione manualmente a referência JavaScript de atualização do browser às páginas da aplicação:

@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 que seja enviado através do dotnet executável, como comandos incorporados da CLI e ferramentas globais. Se conseguir executar dotnet <command>, pode executar dotnet watch <command>. Se o comando subordinado não for especificado, a predefinição é run para dotnet run.
forwarded arguments

Os argumentos fornecidos após um travessão duplo (--) são transmitidos para o processo subordinado dotnet . Se estiver a executar dotnet watch runo , estes argumentos são opções para a execução do dotnet. Se estiver a executar dotnet watch testo , estes argumentos são opções para o teste dotnet.

Opções

--list

Lista todos os ficheiros detetados sem iniciar o observador.
--no-hot-reload

Suprimir o recarregamento frequente para aplicações suportadas.
--non-interactive

É executado dotnet watch no modo não interativo. Utilize esta opção para impedir que a entrada da consola seja pedida. Quando o recarregamento frequente é ativado e é detetada uma edição rude, o dotnet watch reinicia a aplicação. Disponível desde o SDK .NET 7.
--project <PATH>

Especifica o caminho do ficheiro de projeto a executar (apenas pasta ou incluindo o nome do ficheiro do projeto). Se não for especificado, a predefinição é o diretório atual.
-q|--quiet

Suprime todos os resultados gerados pelo dotnet watch comando, exceto avisos e erros. A opção não é transmitida para comandos subordinados. Por exemplo, a saída de dotnet restore e dotnet run continua a ser saída.
-v|--verbose

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

Mostra a versão do dotnet watch.
--

A opção de traço duplo ('--') pode ser utilizada para delimitar dotnet watch opções de argumentos que serão transmitidos para o processo subordinado. A sua utilização é opcional. Quando a opção de traço duplo não é utilizada, dotnet watch considera que o primeiro argumento não reconhecido é o início dos argumentos que deve passar para o processo subordinado dotnet .

Variáveis de ambiente

dotnet watch utiliza as seguintes variáveis de ambiente:

DOTNET_HOTRELOAD_NAMEDPIPE_NAME

Este valor é configurado por dotnet watch quando a aplicação vai ser iniciada e especifica o pipe nomeado.
DOTNET_USE_POLLING_FILE_WATCHER

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

dotnet watch define esta variável como 1 em todos os processos subordinados que inicia.
DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

Como parte do , o mecanismo do servidor de dotnet watchatualização do browser lê este valor para determinar o ambiente anfitrião do WebSocket. O valor 127.0.0.1 é substituído por localhoste os http:// esquemas e https:// são substituídos ws:// por e wss:// , respetivamente.
DOTNET_WATCH_ITERATION

dotnet watch define esta variável como 1 e incrementa uma vez cada vez que um ficheiro é alterado e o comando reinicia ou recarrega a aplicação frequentemente.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

Quando definido como 1 ou true, dotnet watch não atualiza os browsers quando deteta alterações de ficheiros.
DOTNET_WATCH_SUPPRESS_EMOJIS

Com o SDK .NET 6.0.300 e posterior, dotnet watch emite carateres não ASCII para a consola, conforme mostrado no exemplo seguinte:
```
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 anfitriões de consola, estes carateres podem aparecer ilegíveis. Para evitar ver carateres ilegíveis, defina esta variável como 1 ou true.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

Quando definido como 1 ou true, dotnet watch não inicia nem atualiza browsers para aplicações Web configuradas launchBrowser em launchSettings.json.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

Por predefinição, dotnet watch otimiza a compilação ao evitar determinadas operações, como executar o restauro ou reavaliar o conjunto de ficheiros observados em cada alteração de ficheiro. Se esta variável estiver definida como 1 ou true, estas otimizações serão desativadas.
DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

Quando definido como 1 ou true, dotnet watch não irá realizar um processamento especial para ficheiros de conteúdo estático. dotnet watch define a propriedade DotNetWatchContentFiles MSBuild como false.
DOTNET_WATCH_RESTART_ON_RUDE_EDIT

Quando definido como 1 ou true, dotnet watch será sempre reiniciado em edições rudes em vez de perguntar.

Ficheiros observados por predefinição

dotnet watch observa todos os itens no Watch grupo de itens no ficheiro de projeto. Por predefinição, este grupo inclui todos os itens nos Compile grupos e EmbeddedResource . dotnet watch também analisa todo o gráfico de referências de projetos e observa todos os ficheiros nesses projetos.

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

**/*.cs
*.csproj
**/*.resx
Ficheiros de conteúdo em aplicações Web: wwwroot/**

Por predefinição, os ficheiros .config, e .json não acionam um reinício de watch dotnet porque o sistema de configuração tem os seus próprios mecanismos para processar alterações de configuração.

Os ficheiros podem ser adicionados à lista de watch ou removidos da lista ao editar o ficheiro do projeto. Os ficheiros podem ser especificados individualmente ou através de padrões glob.

Ver ficheiros adicionais

Pode ver mais ficheiros ao adicionar itens ao Watch grupo. Por exemplo, a seguinte markup expande esse grupo para incluir ficheiros JavaScript:

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

Ignorar ficheiros especificados

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

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

dotnet watch ignorará as referências de projeto que têm o Watch="false" atributo, conforme mostrado no exemplo seguinte:

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

Configuração avançada

dotnet watchexecuta uma compilação de tempo de conceção para localizar itens para watch. Quando esta compilação é executada, dotnet watch define a propriedade DotNetWatchBuild=true. Esta propriedade pode ser utilizada conforme mostrado no exemplo seguinte:

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

Recarregamento Frequente

A partir do .NET 6, dotnet watch inclui suporte para recarregamento frequente. O recarregamento frequente é uma funcionalidade que lhe permite aplicar alterações a uma aplicação em execução sem ter de recompilá-la e reiniciá-la. As alterações podem ser para ficheiros de código ou recursos estáticos, como ficheiros de folha de estilos e ficheiros JavaScript. Esta funcionalidade simplifica a experiência de desenvolvimento local, uma vez que fornece feedback imediato quando modifica a sua aplicação.

Para obter informações sobre tipos de aplicações e versões .NET que suportam o recarregamento frequente, veja Cenários e arquiteturas de aplicações .NET suportados.

Edições rudes

Quando um ficheiro é modificado, dotnet watch determina se a aplicação pode ser recarregada frequentemente. Se não puder ser recarregada frequentemente, a alteração é chamada de edição rude e dotnet watch pergunta se pretende reiniciar a aplicação:

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

Sim: reinicia a aplicação.
Não: deixa a aplicação em execução sem as alterações aplicadas.
Sempre: reinicia a aplicação e já não pede edições rudes.
Nunca: deixa a aplicação em execução sem as alterações aplicadas e já não pede edições rudes.

Para obter informações sobre que tipos de alterações são consideradas edições rudes, consulte Editar código e continuar a depurar e Alterações não suportadas ao código.

Para desativar o recarregamento frequente quando executar dotnet watch, utilize a opção --no-hot-reload , conforme mostrado no exemplo seguinte:

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 dotnet test o projeto no diretório atual sempre que o código fonte for alterado:
```
dotnet watch test
```
Executar dotnet run --project ./HelloWorld.csproj sempre que o código fonte for alterado:
```
dotnet watch run --project  ./HelloWorld.csproj
```
Execute dotnet run -- arg0 o projeto no diretório atual sempre que o código fonte for alterado:
```
dotnet watch run -- arg0
```
Ou:
```
dotnet watch -- run arg0
```