Desarrollar aplicaciones ASP.NET Core con un monitor de archivos

Por Rick Anderson y Victor Hurdugaci

dotnet watch es una herramienta que ejecuta un comando de la CLI de .NET cuando se modifican los archivos de código fuente. Por ejemplo, un cambio en un archivo puede desencadenar una compilación, una ejecución de prueba o una implementación.

En este tutorial usaremos una API web existente con dos puntos de conexión: uno que devuelve una suma y otro que devuelve un producto. El método Product contiene un error, que se ha corregido en este tutorial.

Descargue la aplicación de ejemplo. Consta de dos proyectos: WebApp (API web de ASP.NET Core) y WebAppTests (pruebas unitarias para la API web).

En un shell de comandos, desplácese hasta la carpeta WebApp. Ejecute el siguiente comando:

dotnet run

La salida de la consola muestra mensajes similares al siguiente (indicando que la aplicación se ejecuta y espera solicitudes):

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

En un explorador web, vaya a http://localhost:<port number>/api/math/sum?a=4&b=5. Debería ver el resultado de 9.

Navegue a la API del producto (http://localhost:<port number>/api/math/product?a=4&b=5). Devuelve 9, no 20 tal como se esperaría. Ese problema se corregirá más adelante en el tutorial.

Ejecutar los comandos de la CLI de .NET con dotnet watch

Cualquier comando de la CLI de .NET se puede ejecutar con dotnet watch. Por ejemplo:

Ejecute dotnet watch run en la carpeta WebApp. La salida de la consola indica que se ha iniciado watch.

Realizar cambios con dotnet watch

Asegúrese de que dotnet watch se está ejecutando.

Corrija el error del método Product de MathController.cs para que devuelva el producto y no la suma:

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

Guarde el archivo. La salida de la consola muestra que dotnet watch ha detectado un cambio de archivo y ha reiniciado la aplicación.

Compruebe que http://localhost:<port number>/api/math/product?a=4&b=5 devuelve el resultado correcto.

Ejecutar pruebas con dotnet watch

1. Vuelva a cambiar el método Product de MathController.cs para devolver la suma. Guarde el archivo.

2. En un shell de comandos, desplácese hasta la carpeta WebAppTests.

3. Ejecute dotnet restore.

4. Ejecute dotnet watch test. La salida que indica que se ha producido un error en una prueba y que el monitor espera cambios de archivos:

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

5. Corrija el código del método Product para que devuelva el producto. Guarde el archivo.

dotnet watch detecta el cambio de archivo y vuelve a ejecutar las pruebas. La salida de la consola indica que se han superado las pruebas.

Personalizar la lista de archivos que inspeccionar

dotnet-watch realiza un seguimiento de forma predeterminada de todos los archivos que coincidan con los siguientes patrones globales:

• **/*.cs
• *.csproj
• **/*.resx
• Archivos de contenido: wwwroot/**, **/*.config y **/*.json

Se pueden agregar más elementos a la lista de control inspección editando el archivo .csproj. Los elementos se pueden especificar individualmente o usando patrones globales.

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

Descartar archivos de la inspección

dotnet-watch se puede configurar para pasar por alto su configuración predeterminada. Para omitir archivos concretos, agregue el atributo Watch="false" a la definición de un elemento en el archivo .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>

Proyectos de inspección personalizados

dotnet-watch no queda restringido exclusivamente a proyectos de C#, sino que se pueden crear proyectos de inspección personalizados para controlar distintos escenarios. Veamos el siguiente diseño de proyecto:

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

Si el objetivo es inspeccionar los dos proyectos, cree un archivo de proyecto personalizado configurado para supervisar ambos proyectos:

<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 empezar a inspeccionar archivos en ambos proyectos, cambie a la carpeta test. Ejecute el siguiente comando:

dotnet watch msbuild /t:Test

VSTest se ejecuta cuando un archivo de cualquiera de los proyectos de prueba cambie.

configuración de dotnet-watch

Algunas opciones de configuración se pueden pasar a dotnet watch a través de variables de entorno. Las variables disponibles son:

Actualización del explorador

dotnet watch inserta un script en la aplicación que le permite actualizar el explorador cuando cambia el contenido. En algunos escenarios, como cuando la aplicación habilita la compresión de respuesta, es posible que dotnet watchno pueda insertar el script. En estos casos de desarrollo, inserte de forma manual el script en la aplicación. Por ejemplo, a fin de configurar la aplicación web para insertar manualmente el script, actualice el archivo de diseño para incluir _framework/aspnet-browser-refresh.js:

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

Caracteres que no son ASCII

En Visual Studio 17.2 y versiones posteriores se incluye el SDK de .NET 6.0.300 y posterior. Con el SDK de .NET 6.0.300 y posteriores, dotnet-watch emite caracteres que no son ASCII a la consola durante una sesión de recarga activa. En determinados hosts de consola, como conhost de Windows, estos caracteres pueden parecer indescifrables. Para evitar caracteres indescifrables, considere uno de los enfoques siguientes:

• Configure la variable de entorno DOTNET_WATCH_SUPPRESS_EMOJIS=1 para suprimir la emisión de estos valores.
• Cambie a otro terminal, como https://github.com/microsoft/terminal, que admite la representación de caracteres no ASCII.