relógio dotnet

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

Nome

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

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 inspetor de arquivos. Quando deteta uma alteração, executa o dotnet run comando ou um comando especificado dotnet . Se ele for executado dotnet rune a alteração for suportada para recarga a quente, ela recarregará o aplicativo especificado. Se a alteração não for suportada, ela reinicia o aplicativo. Este processo permite o desenvolvimento iterativo rápido a partir da linha de comando.

Durante a execução dotnet watchdo , você pode forçar o aplicativo a reconstruir e reiniciar pressionando Ctrl+R no shell de comando. Este recurso está disponível apenas 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.

Compressã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 exibe uma mensagem de aviso como a seguinte:

aviso: 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 desativar a compactação de resposta.

Como alternativa para desativar 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>

  No SDK do .NET 7 e versões anteriores, dotnet watch é possível executar qualquer comando enviado por meio do dotnet executável, como comandos internos da CLI e ferramentas globais. Se você pode executar dotnet <command>, você pode executar dotnet watch <command>.

  No SDK do .NET 8 e posterior, dotnet watch pode executar dotnet run, dotnet buildou dotnet test. Especifique run, build, ou test para <command>.

  Se o comando filho não for especificado, o padrão será run para dotnet 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 são opções para executar dotnet. Se você estiver executando dotnet watch test, esses argumentos são opções para o teste dotnet.

Opções

• --list

  Lista todos os arquivos descobertos sem iniciar o inspetor.

• --no-hot-reload

  Suprima a recarga a quente para aplicações suportadas.

• --non-interactive

  É executado dotnet watch em modo não interativo. Use esta opção para impedir que a entrada do console seja solicitada. Quando a recarga a quente está ativada e uma edição rude é detetada, o relógio dotnet reinicia o aplicativo. Disponível desde .NET 7 SDK.

• --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 for especificado, o padrão será 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

  Mostra a versão do 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. A sua utilização é 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 por dotnet watch quando 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 inspetor 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 no 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 iniciados.

• DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

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

• DOTNET_WATCH_ITERATION

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

• DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

  Quando definido como 1 ou true, dotnet watch não atualizará os navegadores quando detetar alterações de arquivos.

• DOTNET_WATCH_SUPPRESS_EMOJIS

  Com o .NET SDK 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 parecer ilegíveis. Para evitar ver caracteres ilegíveis, 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 a compilação evitando determinadas operações, como executar a restauração ou reavaliar o conjunto de arquivos observados em cada alteração de arquivo. Se essa variável estiver definida como 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 DotNetWatchContentFiles MSBuild como false.

• DOTNET_WATCH_RESTART_ON_RUDE_EDIT

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

Arquivos observados por padrão

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

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

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

Por padrão, os arquivos .config e .json não acionam 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.

Ver ficheiros 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 especificados

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

<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 a seguir:

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

Configuração avançada

dotnet watch Executa uma compilação em tempo de design para encontrar itens para assistir. Quando essa compilação é executada, dotnet watch define a propriedade DotNetWatchBuild=true. Essa propriedade pode ser usada como mostrado no exemplo a seguir:

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

Recarga a quente

A partir do .NET 6, dotnet watch inclui suporte para recarga a quente. Hot reload é um recurso que permite aplicar alterações a um aplicativo em execução sem ter que reconstruí-lo e reiniciá-lo. As alterações podem ser em arquivos de código ou ativos estáticos, como arquivos de folha de estilo e arquivos JavaScript. Esse recurso simplifica a experiência de desenvolvimento local, pois fornece feedback imediato quando você modifica seu aplicativo.

Para obter informações sobre tipos de aplicativos e versões do .NET que oferecem suporte a recarga a quente, consulte Estruturas e cenários de aplicativos .NET suportados.

Edições rudes

Quando um arquivo é modificado, dotnet watch determina se o aplicativo pode ser recarregado a quente. Se não puder ser recarregado a quente, a alteração é chamada de edição rude e dotnet watch pergunta 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 mal-educadas.

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

Para desativar o hot reload quando você executa dotnet watcho , use a --no-hot-reload opção, 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

• Tutorial: Desenvolver aplicativos ASP.NET Core usando um inspetor de arquivos
• Recarga a quente no Visual Studio
• Aplicações suportadas para recarga a quente
• Alterações de código suportadas por recarga a quente
• Execução do teste de recarga a quente
• Suporte de recarga a quente para ASP.NET Core