dotnet watch

  • Статья

Эта статья относится к: ✔️ пакету SDK для .NET Core 3.1 и более поздних версий

Имя.

dotnet watch— Перезапуск или горячая перезагрузка указанного приложения или выполнение указанной команды dotnet при обнаружении изменений в исходном коде.

Краткие сведения

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

dotnet watch -?|-h|--help

Description

Команда dotnet watch — это наблюдатель за файлами. При обнаружении изменения выполняется dotnet run команда или указанная dotnet команда. Если оно выполняется dotnet run, а изменение поддерживается для горячей перезагрузки, оно перезагрузит указанное приложение. Если изменение не поддерживается, он перезапускает приложение. Этот процесс обеспечивает быструю итеративную разработку из командной строки.

Во время выполнения dotnet watchможно принудительно перестроить и перезапустить приложение, нажав клавиши CTRL+R в командной оболочке. Эта функция доступна только во время работы приложения. Например, если вы запускаете dotnet watch консольное приложение, которое заканчивается перед нажатием клавиш CTRL+R, нажатие клавиш CTRL+R не влияет. Однако в этом случае dotnet watch все еще просматривает файлы и перезапустит приложение, если файл обновлен.

Сжатие ответов

Если dotnet watch выполняется для приложения, использующего сжатие ответов, средство не может внедрить скрипт обновления браузера. В .NET 7 и более поздней версии средства отображается предупреждение, как показано ниже:

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

Не удается настроить внедрение скрипта обновления браузера в ответе. Это может быть вызвано кодировкой содержимого ответа: br. Рассмотрите возможность отключения сжатия ответов.

В качестве альтернативы отключению сжатия ответов вручную добавьте ссылку на JavaScript на страницы приложения:

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

Аргументы

  • <command>

    В пакете SDK для .NET 7 и более ранних dotnet watch версий можно выполнить любую команду, которая отправляется через исполняемый dotnet файл, например встроенные команды CLI и глобальные средства. Если вы можете запустить dotnet <command>, можно запустить dotnet watch <command>.

    В пакете SDK для .NET 8 и более поздних dotnet watch версий может выполняться dotnet runилиdotnet builddotnet test. Укажите run, buildили test для <command>.

    Если дочерняя команда не указана, используется rundotnet runзначение по умолчанию.

  • <forwarded arguments>

    Аргументы, предоставленные после двойного дефиса (--) передаются дочернему dotnet процессу. Если вы работаете dotnet watch run, эти аргументы являются вариантами выполнения dotnet. Если вы работаете dotnet watch test, эти аргументы являются вариантами для dotnet test.

Параметры

  • --list

    Выводит список всех обнаруженных файлов без запуска наблюдателя.

  • --no-hot-reload

    Отключение горячей перезагрузки для поддерживаемых приложений.

  • --non-interactive

    Выполняется dotnet watch в неинтерактивном режиме. Используйте этот параметр, чтобы запретить запрашивать входные данные консоли. Если включена горячая перезагрузка и обнаружена грубое изменение , dotnet watch перезапускает приложение. Доступно с пакета SDK для .NET 7.

  • --project <PATH>

    Указывает путь к файлу проекта для запуска (только папка или имя файла проекта). Если значение не задано, по умолчанию используется текущий каталог.

  • -q|--quiet

    Подавляет все выходные данные, созданные командой dotnet watch , за исключением предупреждений и ошибок. Параметр не передается дочерним командам. Например, выходные данные из dotnet restore и dotnet run дальше будут выводиться.

  • -v|--verbose

    Отображает подробные выходные данные для отладки.

  • --version

    Показывает версию dotnet watch.

  • --

    Параметр double-dash ('--) можно использовать для разделителя dotnet watch параметров от аргументов, которые будут переданы дочернему процессу. Его использование является необязательным. Если параметр двойного дефиса не используется, dotnet watch считает первый нераспознанный аргумент началом аргументов, которые он должен передать в дочерний dotnet процесс.

Переменные среды

dotnet watch использует следующие переменные среды:

  • DOTNET_HOTRELOAD_NAMEDPIPE_NAME

    Это значение настраивается dotnet watch при запуске приложения и указывает именованный канал.

  • DOTNET_USE_POLLING_FILE_WATCHER

    Если задано 1 значение или trueиспользуется dotnet watch наблюдатель за файлами опроса, а не System.IO.FileSystemWatcher. Опрос требуется для некоторых файловых систем, таких как сетевые ресурсы, подключенные тома Docker и другие виртуальные файловые системы. Класс PhysicalFileProvider использует DOTNET_USE_POLLING_FILE_WATCHER для определения зависимости метода PhysicalFileProvider.Watch от PollingFileChangeToken.

  • DOTNET_WATCH

    dotnet watch Задает эту переменную 1 для всех дочерних процессов, которые он запускает.

  • DOTNET_WATCH_AUTO_RELOAD_WS_HOSTNAME

    В рамках dotnet watchмеханизма обновления браузера считывает это значение, чтобы определить среду узла WebSocket. Значение 127.0.0.1 заменяется на localhost, а схемы http:// и https:// заменяются на ws:// и wss://, соответственно.

  • DOTNET_WATCH_ITERATION

    dotnet watch задает эту переменную 1 и увеличивается по одному при каждом изменении файла, а команда перезапускает или перезагружает приложение.

  • DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH

    Если задано 1 значение или trueне dotnet watch обновляет браузеры при обнаружении изменений файлов.

  • DOTNET_WATCH_SUPPRESS_EMOJIS

    При использовании пакета SDK для .NET версии 6.0.300 и более поздних dotnet watch версий в консоль отправляется символы, отличные от ASCII, как показано в следующем примере:

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

    На определенных узлах консоли эти символы могут отображаться с развязкой. Чтобы избежать просмотра символов с грифом, задайте для этой переменной 1 значение или true.

  • DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER

    Если задано 1 значение или trueне dotnet watch будет запускать или обновлять браузеры для веб-приложений, launchBrowser настроенных в launchSettings.json.

  • DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM

    По умолчанию оптимизирует сборку, dotnet watch избегая определенных операций, таких как выполнение восстановления или повторное вычисление набора отслеживаемых файлов при каждом изменении файла. Если эта переменная задана 1 или trueотключена, эти оптимизации отключены.

  • DOTNET_WATCH_SUPPRESS_STATIC_FILE_HANDLING

    Если задано 1 значение или trueне dotnet watch будет выполнять специальную обработку статических файлов содержимого. dotnet watch задает для свойства MSBuild значение DotNetWatchContentFilesfalse.

  • DOTNET_WATCH_RESTART_ON_RUDE_EDIT

    Если задано 1 значение или true, dotnet watch всегда перезапускается при грубых изменениях вместо запроса.

Файлы, отслеживаемые по умолчанию

dotnet watch просматривает все элементы в Watch группе элементов в файле проекта. По умолчанию эта группа содержит все элементы в группах Compile и EmbeddedResource группах. dotnet watch также сканирует весь график ссылок на проект и просматривает все файлы в этих проектах.

По умолчанию группы CompileEmbeddedResource включают все файлы, соответствующие следующим шаблонам глобов:

  • **/*.cs
  • *.csproj
  • **/*.resx
  • Файлы содержимого в веб-приложениях: wwwroot/**

По умолчанию config и .json файлы не активируют перезапуск dotnet watch, так как система конфигурации имеет собственные механизмы обработки изменений конфигурации.

Файлы можно добавить в список наблюдения или удалить из списка, изменив файл проекта. Файлы можно указать по отдельности или с помощью шаблонов glOB-объектов.

Просмотр дополнительных файлов

Дополнительные файлы можно просмотреть, добавив элементы в группу Watch . Например, следующая разметка расширяет группу для включения файлов JavaScript:

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

Игнорировать указанные файлы

dotnet watch будет игнорироваться Compile и EmbeddedResource элементы с атрибутом Watch="false" , как показано в следующем примере:

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

dotnet watch Будет игнорировать ссылки на проекты, имеющие Watch="false" атрибут, как показано в следующем примере:

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

Расширенная конфигурация

dotnet watch выполняет сборку во время разработки, чтобы найти элементы для просмотра. При выполнении dotnet watch этой сборки задает свойство DotNetWatchBuild=true. Это свойство можно использовать, как показано в следующем примере:

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

Горячая перезагрузка

Начиная с .NET 6, dotnet watch включает поддержку горячей перезагрузки. Горячая перезагрузка — это функция, которая позволяет применять изменения к работающему приложению без необходимости перестроить и перезапустить его. Изменения могут быть в файлах кода или статических ресурсах, таких как файлы таблицы стилей и файлы JavaScript. Эта функция упрощает локальную разработку, так как она дает немедленную обратную связь при изменении приложения.

Сведения о типах приложений и версиях .NET, поддерживающих горячую перезагрузку, см. в статье "Поддерживаемые платформы и сценарии приложений .NET".

Грубые изменения

При изменении файла определяет, dotnet watch можно ли перезагрузить приложение. Если это не может быть горячей перезагрузкой, изменение называется грубым изменением и dotnet watch спрашивает, хотите ли вы перезапустить приложение:

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)?
  • Да: перезапускает приложение.
  • Нет. Оставляет приложение запущенным без изменений.
  • Всегда: перезапускает приложение и больше не запрашивает грубые изменения.
  • Никогда: оставляет приложение запущенным без изменений, и больше не запрашивает грубые изменения.

Сведения о том, какие типы изменений считаются грубыми изменениями, см. в статье "Изменение кода" и продолжение отладки и неподдерживаемых изменений в коде.

Чтобы отключить горячую --no-hot-reload перезагрузку при запускеdotnet watch, используйте этот параметр, как показано в следующем примере:

dotnet watch --no-hot-reload

Примеры

  • Запустите dotnet run проект в текущем каталоге всякий раз, когда изменяется исходный код:

    dotnet watch

    Или сделайте так:

    dotnet watch run

  • Запустите dotnet test проект в текущем каталоге всякий раз, когда изменяется исходный код:

    dotnet watch test

  • Запустите dotnet run --project ./HelloWorld.csproj каждый раз, когда изменяется исходный код:

    dotnet watch run --project  ./HelloWorld.csproj

  • Запустите dotnet run -- arg0 проект в текущем каталоге всякий раз, когда изменяется исходный код:

    dotnet watch run -- arg0

    Или сделайте так:

    dotnet watch -- run arg0

См. также