dotnet watch

Artículo
06/03/2024

Este artículo se aplica a: ✔️ SDK de .NET Core 3.1 y versiones posteriores

Nombre

dotnet watch: reinicia o realiza la recarga activa de la aplicación especificada, o ejecuta un comando dotnet especificado, cuando se detectan cambios en el código fuente.

Sinopsis

dotnet watch [<command>]
  [--list]
  [--no-hot-reload] [--non-interactive]
  [--project <PROJECT>]
  [-q|--quiet] [-v|--verbose]
  [--version]
  [--] <forwarded arguments> 

dotnet watch -?|-h|--help

Descripción

El comando dotnet watch es un monitor de archivos. Cuando detecta un cambio, ejecuta el dotnet run comando o un comando especificado dotnet . Si ejecuta dotnet run, y la recarga activa, realiza esta operación en la aplicación especificada. Si no se admite el cambio, reinicia la aplicación. Este proceso permite un desarrollo iterativo rápido desde la línea de comandos.

Mientras ejecuta dotnet watch, puede forzar la recompilación y el reinicio de la aplicación presionando Ctrl+R en el shell de comandos. Esta característica solo está disponible mientras se ejecuta la aplicación. Por ejemplo, si se ejecuta dotnet watch en una aplicación de consola que termina antes de presionar Ctrl+R, esta acción no tiene ningún efecto. Sin embargo, en ese caso dotnet watch sigue viendo los archivos y reiniciará la aplicación si se actualiza un archivo.

Compresión de las respuestas

Si dotnet watch se ejecuta para una aplicación que usa la compresión de respuesta, la herramienta no puede insertar el script de actualización del explorador. En .NET 7 y versiones posteriores de la herramienta se muestra un mensaje de advertencia como el siguiente:

advertencia: Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]

No se ha podido configurar la inserción de scripts de actualización del explorador en la respuesta. Esto puede deberse a la codificación del contenido de la respuesta: "br". Considere la posibilidad de deshabilitar la compresión de la respuesta.

Como alternativa a deshabilitar la compresión de la respuesta, agregue manualmente la referencia de JavaScript de actualización del explorador a las páginas de la aplicación:

@if (Environment.GetEnvironmentVariable("__ASPNETCORE_BROWSER_TOOLS") is not null)
{
    <script src="/_framework/aspnetcore-browser-refresh.js"></script>
}

Argumentos

<command>

En el SDK de .NET 7 y versiones anteriores, dotnet watch puede ejecutar cualquier comando que se envíe a través del ejecutable, como comandos integrados de la dotnet CLI y herramientas globales. Si puede ejecutar dotnet <command>, puede ejecutar dotnet watch <command>.

En el SDK de .NET 8 y versiones posteriores, dotnet watch puede ejecutar dotnet run, dotnet buildo dotnet test. Especifique run, buildo test para <command>.

Si no se especifica el comando secundario, el valor predeterminado es run para dotnet run.
<forwarded arguments>

Los argumentos proporcionados después de pasar un guión doble (--) al proceso secundario dotnet . Si ejecuta dotnet watch run, estos argumentos son opciones para dotnet run. Si está ejecutando dotnet watch test, estos argumentos son opciones para dotnet test.

Opciones

--list

Enumera todos los archivos detectados sin iniciar el monitor.
--no-hot-reload

Suprime la recarga activa para las aplicaciones compatibles.
--non-interactive

Ejecuta dotnet watch en modo no interactivo. Use esta opción para evitar que se solicite la entrada de la consola. Cuando se habilita la recarga activa y se detecta una edición superficial, dotnet watch reinicia la aplicación. Disponible a partir del SDK de .NET 7.
--project <PATH>

Especifica la ruta de acceso del archivo de proyecto que se va a ejecutar (solo la carpeta o se incluye el nombre del archivo del proyecto). Si no se especifica, se toma como predeterminado el directorio actual.
-q|--quiet

Suprime toda la salida generada por el comando dotnet watch, excepto advertencias y errores. La opción no se pasa a comandos secundarios. Por ejemplo, se sigue generando la salida de dotnet restore y dotnet run.
-v|--verbose

Muestra la salida detallada de la depuración.
--version

Muestra la versión de dotnet watch.
--

La opción de doble guion ("--") se puede usar para delimitar las opciones dotnet watch de los argumentos que se pasarán al proceso secundario. Su uso es opcional. Cuando no se usa la opción de doble guion, dotnet watch considera que el primer argumento no reconocido es el principio de los argumentos que se deben pasar al proceso dotnet secundario.

Variables de entorno

dotnet watch usa las siguientes variables de entorno:

DOTNET_HOTRELOAD_NAMEDPIPE_NAME

Este valor se configura con dotnet watch cuando se va a iniciar la aplicación, y especifica la canalización con nombre.
DOTNET_USE_POLLING_FILE_WATCHER

Si se establece en 1 o true, dotnet watch usa un monitor de archivo de sondeo en lugar de System.IO.FileSystemWatcher. El sondeo es necesario en algunos sistemas de archivos, como los recursos compartidos de red, los volúmenes montados de Docker y otros sistemas de archivos virtuales. La clase PhysicalFileProvider utiliza DOTNET_USE_POLLING_FILE_WATCHER para determinar si el método PhysicalFileProvider.Watch se basará en PollingFileChangeToken.
DOTNET_WATCH

dotnet watch establece esta variable en 1 en todos los procesos secundarios que se inician.
DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

Como parte de dotnet watch, el mecanismo del servidor de actualización del explorador lee este valor para determinar el entorno de host de WebSocket. El valor 127.0.0.1 se reemplaza por localhost, y los esquemas http:// y https:// se reemplazan por ws:// y wss:// respectivamente.
DOTNET_WATCH_ITERATION

dotnet watch establece esta variable en 1 y se incrementa en uno cada vez que un archivo cambia y el comando se reinicia o se realiza la recarga activa de la aplicación.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

Cuando se establece en 1 o true, dotnet watch no actualizará los exploradores cuando se detecten cambios en el archivo.
DOTNET_WATCH_SUPPRESS_EMOJIS

Con el SDK de .NET 6.0.300 y versiones posteriores, dotnet watch emite caracteres que no son ASCII a la consola, como se muestra en el ejemplo siguiente:
```
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...
```
En determinados hosts de consola, estos caracteres pueden parecer indescifrables. Para evitar ver caracteres indescifrables, establezca esta variable en 1 o true.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

Cuando se establece en 1 o true, dotnet watch no iniciará ni actualizará los exploradores de las aplicaciones web que tengan configurado launchBrowser en launchSettings.json.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

De forma predeterminada, dotnet watch optimiza la compilación evitando ciertas operaciones, como ejecutar la restauración o volver a evaluar el conjunto de archivos inspeccionados con cada cambio de archivo. Si esta variable se establece en 1 o true, estas optimizaciones se deshabilitan.
DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

Cuando se establece en 1 o true, dotnet watch no hará un control especial de los archivos de contenido estático. dotnet watch establece la propiedad DotNetWatchContentFiles de MSBuild en false.
DOTNET_WATCH_RESTART_ON_RUDE_EDIT

Cuando se establezca en 1 o true, dotnet watch siempre se reiniciará en ediciones superficiales, en lugar de preguntar.

Archivos inspeccionados de forma predeterminada

dotnet watch inspecciona todos los elementos del grupo de elementos Watch del archivo de proyecto. De forma predeterminada, este grupo incluye todos los elementos de los grupos Compile y EmbeddedResource. dotnet watch también examina todo el grafo de referencias del proyecto r inspecciona todos los archivos de esos proyectos.

De forma predeterminada, los grupos Compile y EmbeddedResource incluyen todos los archivos que coinciden con los siguientes patrones globales:

**/*.cs
*.csproj
**/*.resx
Archivos de contenido en aplicaciones web: wwwroot/**

De forma predeterminada, los archivos .config y .json no desencadenan un reinicio dotnet watch porque el sistema de configuración tiene sus propios mecanismos para controlar los cambios de configuración.

Los archivos se pueden agregar a la lista de inspección o se pueden quitar de la lista editando el archivo del proyecto. Los elementos se pueden especificar individualmente o usando patrones globales.

Inspección de archivos adicionales

Se pueden inspeccionar más archivos agregando elementos al grupo Watch. Por ejemplo, el marcado siguiente amplía ese grupo para incluir archivos JavaScript:

<ItemGroup>
  <Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>

Omisión de los archivos especificados

dotnet watch omitirá los elementos Compile y EmbeddedResource que tienen el atributo Watch="false", como se muestra en el ejemplo siguiente:

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

dotnet watch omitirá las referencias de proyecto que tienen el atributo Watch="false", como se muestra en el ejemplo siguiente:

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

Configuración avanzada

dotnet watch realiza una compilación en tiempo de diseño para buscar elementos que se van a inspeccionar. Cuando se ejecuta esta compilación, dotnet watch establece la propiedad DotNetWatchBuild=true. Esta propiedad se puede usar como se muestra en el ejemplo siguiente:

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

Recarga activa

A partir de .NET 6, dotnet watch incluye compatibilidad con la recarga activa. La recarga activa es una característica que permite aplicar cambios a una aplicación en ejecución sin tener que recompilarla y reiniciarla. Los cambios pueden ser en archivos de código o recursos estáticos, como archivos de hoja de estilos y archivos JavaScript. Esta característica simplifica la experiencia de desarrollo local, ya que proporciona comentarios inmediatos al modificar la aplicación.

Para información sobre los tipos de aplicaciones y las versiones de .NET que admiten la recarga activa, consulte Escenarios y marcos de aplicaciones .NET compatibles.

Ediciones superficiales

Cuando se modifica un archivo, dotnet watch determina si la aplicación se puede recargar de forma activa. Si no se puede volver a realizar la recarga activa, el cambio se denomina edición superficial y dotnet watch le pregunta si desea reiniciar la aplicación:

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)?

Sí: reinicia la aplicación.
No: deja que se ejecute la aplicación sin aplicar los cambios.
Siempre: reinicia la aplicación y ya no solicita ediciones superficiales.
Nunca: deja que se ejecute la aplicación sin aplicar los cambios y ya no se solicitan ediciones superficiales.

Para información sobre los tipos de cambios que se consideran ediciones superficiales, consulte Editar código y continuar con la depuración y Cambios no admitidos en el código.

Para deshabilitar la recarga activa al ejecutar dotnet watch, use la opción --no-hot-reload, como se muestra en el ejemplo siguiente:

dotnet watch --no-hot-reload

Ejemplos

Ejecute dotnet run para el proyecto en el directorio actual cada vez que cambie el código fuente:
```
dotnet watch
```
O:
```
dotnet watch run
```
Ejecute dotnet test para el proyecto en el directorio actual cada vez que cambie el código fuente:
```
dotnet watch test
```
Ejecute dotnet run --project ./HelloWorld.csproj cada vez que cambie el código fuente:
```
dotnet watch run --project  ./HelloWorld.csproj
```
Ejecute dotnet run -- arg0 para el proyecto en el directorio actual cada vez que cambie el código fuente:
```
dotnet watch run -- arg0
```
O:
```
dotnet watch -- run arg0
```

Compartir a través de