Desenvolver aplicativos do ASP.NET Core usando um observador de arquivos

Por Rick Anderson e Victor Hurdugaci

dotnet watch é uma ferramenta que executa um comando da CLI do .NET quando os arquivos de origem são alterados. Por exemplo, uma alteração de arquivo pode disparar compilação, execução de teste ou implantação.

Este tutorial usa uma API Web existente com dois pontos de extremidade: um que retorna uma soma e outra que retorna um produto. O método do produto tem um bug, que é corrigido neste tutorial.

Baixe o aplicativo de exemplo. Ele consiste em dois projetos: WebApp (uma API Web ASP.NET Core) e WebAppTests (testes de unidade para a API Web).

Em um shell de comando, navegue até a pasta WebApp . Execute o comando a seguir:

dotnet run

Observação

Você pode usar dotnet run --project <PROJECT> para especificar um projeto a ser executado. Por exemplo, a execução dotnet run --project WebApp na raiz do aplicativo de exemplo também executará o projeto WebApp .

A saída do console mostra mensagens semelhantes às seguintes (indicando que o aplicativo está em execução e aguardando solicitações):

$ dotnet run
Hosting environment: Development
Content root path: C:/Docs/aspnetcore/tutorials/dotnet-watch/sample/WebApp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

Em um navegador web, navegue até http://localhost:<port number>/api/math/sum?a=4&b=5. Você deve ver o resultado de 9.

Navegue até a API do produto (http://localhost:<port number>/api/math/product?a=4&b=5). Ele retorna 9, não 20 como você esperaria. Esse problema é corrigido posteriormente no tutorial.

Executar comandos da CLI do .NET usando dotnet watch

Qualquer comando da CLI do .NET pode ser executado com dotnet watch. Por exemplo:

Comando	Comando com monitoramento
execução dotnet	execução do relógio dotnet
dotnet run -f netcoreapp3.1	dotnet watch run -f netcoreapp3.1
dotnet run -f netcoreapp3.1 -- --arg1	dotnet watch run -f netcoreapp3.1 -- --arg1
teste dotnet	teste de inspeção dotnet

Execute dotnet watch run no diretório WebApp . A saída do console indica que o processo watch foi iniciado.

A execução dotnet watch run em um aplicativo Web inicia um navegador que navega até a URL do aplicativo uma vez pronto. dotnet watch faz isso lendo a saída do console do aplicativo e aguardando a mensagem pronta exibida por WebHost.

dotnet watch atualiza o navegador quando ele detecta alterações nos arquivos assistidos. Para fazer isso, o comando watch injeta um middleware no aplicativo que modifica as respostas HTML criadas pelo aplicativo. O middleware adiciona um bloco de script JavaScript à página que permite dotnet watch instruir o navegador a atualizar. Atualmente, as alterações em todos os arquivos assistidos, incluindo conteúdo estático, como arquivos .html e .css, fazem com que o aplicativo seja reconstruído.

dotnet watch:

• Só observa arquivos que afetam compilações por padrão.
• Os arquivos observados adicionalmente (por meio da configuração) ainda resultam em um build em andamento.

Para obter mais informações sobre a configuração, consulte a configuração do dotnet-watch neste documento.

Observação

Você pode usar dotnet watch --project <PROJECT> para especificar um projeto a ser observado. Por exemplo, a execução dotnet watch --project WebApp run a partir da raiz do aplicativo de exemplo também será executado e monitorará o projeto WebApp.

Fazer alterações com dotnet watch

Verifique se dotnet watch está em execução.

Corrija o bug no método Product de MathController.cs, para que ele retorne o produto em vez da soma.

public static int Product(int a, int b)
{
    return a * b;
}

Salve o arquivo. A saída do console indica que dotnet watch detectou uma alteração de arquivo e reiniciou o aplicativo.

Verifique se http://localhost:<port number>/api/math/product?a=4&b=5 retorna o resultado correto.

Executar testes usando dotnet watch

1. Altere o método Product de MathController.cs para voltar a retornar a soma. Salve o arquivo.

2. Em um shell de comando, navegue até a pasta WebAppTests .

3. Execute dotnet restore.

4. Execute dotnet watch test. Sua saída indica que um teste falhou e que o observador está aguardando alterações de arquivo:

   Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.
   Test Run Failed.
   

5. Corrija o código do Product método para que ele retorne o produto. Salve o arquivo.

dotnet watch detecta a alteração de arquivo e executa novamente os testes. A saída do console indica os testes aprovados.

Personalizar a lista de arquivos para assistir

Por padrão, dotnet-watch monitora todos os arquivos que correspondem aos seguintes padrões globais.

• **/*.cs
• *.csproj
• **/*.resx
• Arquivos de conteúdo: wwwroot/**, , **/*.config**/*.json

Mais itens podem ser adicionados à lista de observação editando o .csproj arquivo. Os itens podem ser especificados individualmente ou usando padrões globais.

<ItemGroup>
    <!-- extends watching group to include *.js files -->
    <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>

Desativar arquivos a serem observados

dotnet-watch pode ser configurado para ignorar suas configurações padrão. Para ignorar arquivos específicos, adicione o Watch="false" atributo à definição de um item no .csproj arquivo:

<ItemGroup>
    <!-- exclude Generated.cs from dotnet-watch -->
    <Compile Include="Generated.cs" Watch="false" />

    <!-- exclude Strings.resx from dotnet-watch -->
    <EmbeddedResource Include="Strings.resx" Watch="false" />

    <!-- exclude changes in this referenced project -->
    <ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>

<ItemGroup>
     <!-- Exclude all Content items from being watched. -->
    <Content Update="@(Content)" Watch="false" />
</ItemGroup>

Projetos de relógios personalizados

dotnet-watch não está restrito a projetos em C#. Projetos de relógios personalizados podem ser criados para lidar com diferentes cenários. Considere o seguinte layout de projeto:

• teste/
  • UnitTests/UnitTests.csproj
  • IntegrationTests/IntegrationTests.csproj

Se o objetivo for observar ambos os projetos, crie um arquivo de projeto personalizado configurado para observar ambos os projetos:

<Project>
    <ItemGroup>
        <TestProjects Include="**\*.csproj" />
        <Watch Include="**\*.cs" />
    </ItemGroup>

    <Target Name="Test">
        <MSBuild Targets="VSTest" Projects="@(TestProjects)" />
    </Target>

    <Import Project="$(MSBuildExtensionsPath)\Microsoft.Common.targets" />
</Project>

Para iniciar a observação de arquivos em ambos os projetos, altere para a pasta test. Execute o comando a seguir:

dotnet watch msbuild /t:Test

O VSTest é executado quando qualquer arquivo é alterado em qualquer projeto de teste.

Configuração dotnet-watch

Algumas opções de configuração podem ser passadas para dotnet watch por meio de variáveis de ambiente. As variáveis disponíveis são:

Configurações	Descrição
DOTNET_USE_POLLING_FILE_WATCHER	Se definido como "1" ou "true", dotnet watch usará um monitor de arquivos de sondagem em vez do CoreFx. FileSystemWatcher Usado ao monitorar arquivos em volumes montados do Docker ou em compartilhamentos de rede.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Por padrão, dotnet watch otimiza a compilação evitando determinadas ações, como executar a restauração ou reavaliar o conjunto de arquivos monitorados em cada alteração de arquivo. Se definido como "1" ou "true", essas otimizações serão desabilitadas.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run tenta iniciar navegadores para aplicativos Web com launchBrowser configurado em launchSettings.json. Se definido como "1" ou "true", esse comportamento será suprimido.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run tenta atualizar navegadores quando detecta alterações de arquivo. Se definido como "1" ou "true", esse comportamento será suprimido. Esse comportamento também será suprimido se DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER estiver definido.

Atualização do navegador

dotnet watch injeta um script no aplicativo que permite que ele atualize o navegador quando o conteúdo for alterado. Em alguns cenários, como quando o aplicativo habilita a compactação de resposta, dotnet watch talvez não poderá injetar o script. Para esses casos em desenvolvimento, injete manualmente o script no aplicativo. Por exemplo, para configurar o aplicativo Web para injetar manualmente o script, atualize o arquivo de layout para incluir _framework/aspnet-browser-refresh.js:

@* _Layout.cshtml *@
<environment names="Development">
    <script src="/_framework/aspnetcore-browser-refresh.js"></script>
</environment>

Caracteres não ASCII

O Visual Studio 17.2 ou posterior inclui o SDK do .NET 6.0.300 ou posterior. Com o SDK do .NET e 6.0.300 posteriores, dotnet-watch emite caracteres não ASCII para o console durante uma sessão de recarregamento frequente. Em determinados hosts de console, como o conhost do Windows, esses caracteres podem aparecer corrompidos. Para evitar caracteres embaralhados, considere uma das seguintes abordagens:

• Configure a variável de DOTNET_WATCH_SUPPRESS_EMOJIS=1 ambiente para suprimir a emissão desses valores.
• Alterne para um terminal diferente, como https://github.com/microsoft/terminal, que dá suporte à renderização de caracteres não ASCII.