relógio dotnet

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

Nome

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

Sinopse

dotnet watch [<command>]
  [--artifacts-path <ARTIFACTS_DIR>] [--disable-build-servers]
  [--list] [--no-hot-reload] [--no-self-contained]
  [--non-interactive] [--project <PROJECT>] [--sc|--self-contained]
  [-q|--quiet] [-v|--verbose] [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Description

O dotnet watch comando é um observador de arquivos. Quando detecta uma alteração, ele executa o dotnet run comando ou um comando especificado dotnet . Se ele for executado dotnet rune a alteração for suportada para recarregamento frequente, ele recarrega o aplicativo especificado. Se a alteração não tiver suporte, ela reiniciará o aplicativo. Esse processo permite o desenvolvimento iterativo rápido da linha de comando.

Durante a execução 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á assistindo arquivos e reiniciará o aplicativo se um arquivo for atualizado.

Compactação de resposta

Se dotnet watch for executada 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 a 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>
}

Arguments

<command>

No SDK do .NET 7 e anteriores, dotnet watch é possível executar qualquer comando que seja expedido por meio do dotnet executável, como comandos internos da CLI e ferramentas globais. Se você puder executar dotnet <command>, poderá executar dotnet watch <command>.

No SDK do .NET 8 e posterior, dotnet watch pode ser executado dotnet run, dotnet buildou dotnet test. Especificar run, buildou test para <command>.

Se o comando filho não for especificado, o padrão será rundotnet run.
<forwarded arguments>

Os argumentos fornecidos após um traço duplo (--) são passados para o processo filho dotnet . Se você estiver executando dotnet watch run, esses argumentos serão opções para execução do dotnet. Se você estiver executando dotnet watch test, esses argumentos serão opções para teste de dotnet.

Opções

--artifacts-path <ARTIFACTS_DIR>

Todos os arquivos de saída de compilação do comando executado irão para subpastas no caminho especificado, separados por projeto. Para obter mais informações, consulte Layout de saída de artefatos. Disponível desde o SDK do .NET 8.
--disable-build-servers

Força o comando a ignorar todos os servidores de build persistentes. Essa opção fornece uma maneira consistente de desabilitar todo o uso do cache de build, o que força um build do zero. Um build que não depende de caches é útil quando os caches podem estar corrompidos ou incorretos por algum motivo. Disponível desde o SDK do .NET 7.
--list

Lista todos os arquivos descobertos sem iniciar o observador.
--no-self-contained

Publique seu aplicativo como um aplicativo dependente da estrutura. Um runtime do .NET compatível deve ser instalado no computador de destino para executar seu aplicativo.
--no-hot-reload

Suprimir o recarregamento frequente para aplicativos com suporte.
--non-interactive

É executado 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 edição rude é 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.
--sc|--self-contained

Publique o runtime do .NET com seu aplicativo para que o runtime não precise ser instalado no computador de destino.
-q|--quiet

Suprime toda a saída gerada pelo dotnet watch comando, 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

Mostra a versão de dotnet watch.
--

A opção de traço duplo ('--') pode ser usada para delimitar dotnet watch opções de argumentos que serão passados para o processo filho. Seu 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 .
-?|-h|--help

Imprime uma descrição de como usar o comando.

Variáveis de ambiente

dotnet watch usa as seguintes variáveis de ambiente:

DOTNET_HOTRELOAD_NAMEDPIPE_NAME

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

Quando definido como 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 PhysicalFileProvider classe usa DOTNET_USE_POLLING_FILE_WATCHER para determinar se o PhysicalFileProvider.Watch método dependerá do PollingFileChangeToken.
DOTNET_WATCH

dotnet watch define essa variável como 1 em todos os processos filho que ela inicia.
DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

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

dotnet watch define essa variável 1 como e incrementa por um 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 configurados launchBrowser no 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 1 como 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 DotNetWatchContentFiles MSBuild como false.
DOTNET_WATCH_RESTART_ON_RUDE_EDIT

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

Arquivos assistidos por padrão

dotnet watch observa todos os itens no Watch grupo de itens no arquivo de projeto. Por padrão, esse grupo inclui todos os itens e CompileEmbeddedResource grupos. 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 e os Compile grupos 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.

Assista a arquivos adicionais

Mais arquivos podem ser observados adicionando itens ao Watch grupo. 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>

Ignorar arquivos e pastas especificados

Use o Watch="false" atributo para ignorar os arquivos especificados. Use a DefaultItemExcludes propriedade para ignorar pastas ou arquivos de serem observados.

Para impedir dotnet watch a observação de arquivos, use o atributo e EmbeddedResource os Compile itensWatch="false", conforme mostrado no exemplo a seguir:

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

dotnet watch ignora as referências de projeto que têm o Watch="false" atributo, conforme mostrado no exemplo a seguir:

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

A partir do .NET 10, use a DefaultItemExcludes propriedade para excluir pastas inteiras ou padrões de arquivo de serem observados por dotnet watch. Essa abordagem é útil quando você deseja excluir arquivos que não são relevantes para compilação ou arquivos que disparam reinicializações ou recarregamentos indesejados.

Por exemplo, arquivos App_Data na pasta de aplicativos do ASP.NET Core podem ser alterados enquanto o aplicativo é executado, causando recarregamentos desnecessários de página. Exclua essa pasta de ser observada:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/App_Data/**</DefaultItemExcludes>
</PropertyGroup>

Exclua vários padrões separando-os com ponto-e-vírgula:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/App_Data/**;**/temp/**;**/*.log</DefaultItemExcludes>
</PropertyGroup>

A DefaultItemExcludes propriedade afeta todos os tipos de item padrão, como Compile e EmbeddedResource. O Watch="false" atributo fornece um controle mais fino sobre arquivos específicos ou referências de projeto.

Para obter mais informações, consulte a referência DefaultItemExcludes.

Configuração avançada

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

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

Recarga Dinâmica

A partir do SDK do .NET 6, dotnet watch inclui suporte para recarregamento frequente. Recarregamento 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 ao modificar seu aplicativo.

Para obter informações sobre tipos de aplicativo e versões do .NET que dão suporte ao recarregamento frequente, consulte os cenários e estruturas de aplicativos do .NET compatíveis.

Edições rudes

Quando um arquivo é modificado, dotnet watch determina se o aplicativo pode ser recarregado. Se não puder ser recarregado, 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)?

Sim: reinicia o aplicativo.
Não: deixa o aplicativo em execução sem as alterações aplicadas.
Sempre: reinicia o aplicativo e não solicita mais edições rudes.
Nunca: 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 o recarregamento frequente 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 dotnet test o projeto 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 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
```

Consulte também

Comentários

Esta página foi útil?

Last updated on 2025-12-12