Desenvolver aplicativos ASP.NET Core usando um observador de arquivo

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 uma compilação, execução de teste ou uma implantação.

Este tutorial usa um aplicativo de API Web existente com dois pontos de extremidade: um que retorna uma soma e outro que retorna um produto. O método de 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

O resultado do console mostra mensagens semelhantes à seguinte (indicando que o aplicativo está em execução e aguarda 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 para o API do produto (http://localhost:<port number>/api/math/product?a=4&b=5). Ele retorna 9, não 20, conforme o esperado. Esse problema é corrigido mais adiante 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:

Executar dotnet watch run na pasta WebApp. O resultado do console indica que watch foi iniciado.

Fazer alterações com dotnet watch

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

Corrija o bug no método Product do MathController.cs para que retorne o produto e não a soma:

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

Salve o arquivo. O resultado do console indica que o 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 o dotnet watch

1. Altere o método Product de MathController.cs de volta para 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. Seu resultado indica que um teste falhou e que o observador está aguardando as alterações de arquivo:

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

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

dotnet watch detecta a alteração de arquivo e executa os testes novamente. O resultado do console indica a aprovação nos testes.

Personalizar lista de arquivos a observar

Por padrão, o dotnet-watch controla todos os arquivos que correspondem aos seguintes padrões glob:

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

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

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

Recusa de arquivos a serem observados

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

<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 inspeção personalizados

dotnet-watch não é restrito a projetos C#. Projetos de inspeção personalizados podem ser criados para lidar com cenários diferentes. Considere o layout de projeto a seguir:

• test/
  • UnitTests/UnitTests.csproj
  • IntegrationTests/IntegrationTests.csproj

Se a meta é observar ambos os projetos, crie um arquivo de projeto personalizados configurado para observar os dois 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 arquivo em ambos os projetos, mude para a pasta de teste. Execute o comando a seguir:

dotnet watch msbuild /t:Test

O VSTest é executado quando há qualquer mudança de arquivo no projeto de teste.

Configuração de 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:

Atualização de 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 pode não ser capaz de 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 e posterior inclui o SDK do .NET 6.0.300 e posterior. Com o SDK do .NET e 6.0.300 e 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 embaralhados. Para evitar caracteres embaralhados, considere uma das seguintes abordagens:

• Configure a variável de ambiente DOTNET_WATCH_SUPPRESS_EMOJIS=1 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.