Partilhar via

relógio dotnet

Este artigo aplica-se a: ✔️ .NET 6 SDK 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>]
  [--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 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>
}

Arguments

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

  • --artifacts-path <ARTIFACTS_DIR>

    Todos os arquivos de saída de compilação do comando executado irão em subpastas sob o 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 quaisquer servidores de compilação persistentes. Essa opção fornece uma maneira consistente de desabilitar todo o uso do cache de compilação, o que força uma compilação do zero. Uma compilação que não depende de caches é útil quando os caches podem estar corrompidos ou incorretos por algum motivo. Disponível desde .NET 7 SDK.

  • --list

    Lista todos os arquivos descobertos sem iniciar o inspetor.

  • --no-self-contained

    Publique a sua candidatura como uma aplicação dependente do framework. Um tempo de execução .NET compatível deve ser instalado na máquina de destino para executar seu aplicativo.

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

  • --sc|--self-contained

    Publique o tempo de execução do .NET com seu aplicativo para que o tempo de execução não precise ser instalado na máquina de destino.

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

  • -?|-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 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.confige .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>

Ignore ficheiros e pastas especificados

Use o Watch="false" atributo para ignorar ficheiros especificados. Use a DefaultItemExcludes propriedade para ignorar pastas ou ficheiros que não estão a ser vigiados.

Para evitar dotnet watch ver ficheiros, use os Compile itens e EmbeddedResource com o Watch="false" atributo, como mostrado no exemplo seguinte:

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

dotnet watch ignora referências de projetos que têm o Watch="false" atributo, como mostrado no exemplo seguinte:

<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 ficheiros de serem monitorizados por dotnet watch. Esta abordagem é útil quando se querem excluir ficheiros que não são relevantes para compilação ou ficheiros que desencadeiam reinicios ou recargas indesejados.

Por exemplo, ficheiros na App_Data pasta de ASP.NET aplicações Core podem mudar enquanto a aplicação está a correr, causando recargas desnecessárias de página. Exclua esta pasta de ser vigiada:

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

Exclua múltiplos 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 itens por defeito, como Compile e EmbeddedResource. O Watch="false" atributo proporciona um controlo mais fino sobre ficheiros específicos ou referências de projetos.

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

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 instantânea

A partir do SDK 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

Examples

  • 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

  • Last updated on