Tworzenie aplikacji ASP.NET Core przy użyciu obserwatora plików

Przez Rick Anderson i Victor Hurdugaci

dotnet watch to narzędzie uruchamiające polecenie interfejsu wiersza polecenia platformy .NET po zmianie plików źródłowych. Na przykład zmiana pliku może wyzwolić kompilację, wykonanie testu lub wdrożenie.

W tym samouczku jest używany istniejący interfejs API z dwoma punktami końcowymi: jeden zwracający sumę i jeden zwracający produkt. Metoda produkcji zawiera usterkę, która została naprawiona w tym samouczku.

Pobierz przykładową aplikację . Składa się z dwóch projektów: WebApp (ASP.NET Core web API) i WebAppTests (testy jednostkowe internetowego interfejsu API).

W powłoce poleceń przejdź do folderu WebApp . Uruchom następujące polecenie:

dotnet run

Uwaga / Notatka

Możesz użyć dotnet run --project <PROJECT> polecenia , aby określić projekt do uruchomienia. Na przykład uruchomienie dotnet run --project WebApp z poziomu katalogu głównego przykładowej aplikacji spowoduje również uruchomienie projektu aplikacji internetowej .

Dane wyjściowe konsoli zawierają komunikaty podobne do następujących (wskazujących, że aplikacja jest uruchomiona i oczekuje na żądania):

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

W przeglądarce internetowej przejdź do http://localhost:<port number>/api/math/sum?a=4&b=5. Powinieneś zobaczyć wynik 9.

Przejdź do interfejsu API produktu (http://localhost:<port number>/api/math/product?a=4&b=5). Zwraca wartość 9, a nie 20 zgodnie z oczekiwaniami. Ten problem został rozwiązany w dalszej części samouczka.

Uruchamianie poleceń .NET CLI przy użyciu dotnet watch

Każde polecenie interfejsu wiersza polecenia platformy .NET można uruchomić za pomocą polecenia dotnet watch. Przykład:

Komenda	Polecenie z funkcją "watch"
dotnet run	dotnet watch run
dotnet run -f netcoreapp3.1	dotnet watch run -f netcoreapp3.1
dotnet run -f netcoreapp3.1 -- --arg1	dotnet watch run -f netcoreapp3.1 -- --arg1
dotnet test	dotnet watch test

Uruchom polecenie dotnet watch run w folderze WebApp . Wynik konsoli wskazuje, że watch zostało uruchomione.

Uruchomienie dotnet watch run na aplikacji internetowej powoduje otwarcie przeglądarki, która przechodzi do adresu URL aplikacji, gdy jest gotowa. dotnet watch Robi to, odczytując dane wyjściowe konsoli aplikacji i czekając na gotowy komunikat wyświetlany przez WebHost.

dotnet watch odświeża przeglądarkę po wykryciu zmian w obserwowanych plikach. W tym celu polecenie watch wprowadza oprogramowanie pośredniczące do aplikacji, która modyfikuje odpowiedzi HTML utworzone przez aplikację. Oprogramowanie pośredniczące dodaje do strony blok skryptu JavaScript, który umożliwia dotnet watch poinstruowanie przeglądarki o odświeżeniu. Obecnie zmiany we wszystkich obserwowanych plikach, w tym zawartości statycznej, takich jak pliki .html i .css, powodują ponowne skompilowanie aplikacji.

dotnet watch:

• Domyślnie monitoruje tylko pliki, które mają wpływ na kompilacje.
• Wszystkie dodatkowo obserwowane pliki (za pośrednictwem konfiguracji) nadal są wynikiem kompilacji.

Aby uzyskać więcej informacji na temat konfiguracji, zobacz dotnet-watch configuration w tym dokumencie.

Uwaga / Notatka

Możesz użyć dotnet watch --project <PROJECT>, aby określić projekt do obejrzenia. Na przykład uruchomienie dotnet watch --project WebApp run z katalogu głównego aplikacji przykładowej spowoduje również uruchomienie i monitorowanie projektu WebApp.

Wprowadzanie zmian za pomocą polecenia dotnet watch

Upewnij się, że dotnet watch działa.

Napraw usterkę w Product metodzie , MathController.cs aby zwracała produkt, a nie sumę:

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

Zapisz plik. Dane wyjściowe konsoli wskazują, że dotnet watch wykryto zmianę pliku i uruchomiono ponownie aplikację.

Funkcja Verify http://localhost:<port number>/api/math/product?a=4&b=5 zwraca prawidłowy wynik.

Uruchamianie testów przy użyciu dotnet watch

1. Zmień metodę Product w MathController.cs z powrotem, aby zwracała sumę. Zapisz plik.

2. W konsoli poleceń przejdź do folderu WebAppTests.

3. Uruchom dotnet restore.

4. Uruchom program dotnet watch test. Jego dane wyjściowe wskazują, że test zakończył się niepowodzeniem i że obserwator oczekuje na zmiany w pliku:

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

5. Napraw kod metody, Product aby zwracał produkt. Zapisz plik.

dotnet watch wykrywa zmianę pliku i uruchamia ponownie testy. Dane wyjściowe konsoli wskazują, że testy zostały pomyślnie wykonane.

Dostosowywanie listy plików do obejrzenia

Domyślnie dotnet-watch śledzi wszystkie pliki pasujące do następujących wzorców globu:

• **/*.cs
• *.csproj
• **/*.resx
• Pliki zawartości: wwwroot/**, , **/*.config**/*.json

Więcej elementów można dodać do listy obserwowanych, edytując .csproj plik. Elementy można określić indywidualnie lub za pomocą wzorców globu.

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

Wyklucz pliki z monitorowania

dotnet-watch Można skonfigurować tak, aby ignorować jego ustawienia domyślne. Aby zignorować określone pliki, dodaj Watch="false" atrybut do definicji elementu w .csproj pliku:

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

Projekty zegarków niestandardowych

dotnet-watch nie jest ograniczona do projektów w języku C#. Niestandardowe projekty zegarków można tworzyć w celu obsługi różnych scenariuszy. Rozważmy następujący układ projektu:

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

Jeśli celem jest obserwowanie obu projektów, utwórz niestandardowy plik projektu skonfigurowany do oglądania obu projektów:

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

Aby rozpocząć oglądanie plików w obu projektach, przejdź do folderu testowego . Wykonaj następujące polecenie:

dotnet watch msbuild /t:Test

Program VSTest jest wykonywany, gdy dowolny plik ulegnie zmianie w dowolnym projekcie testowym.

konfiguracja dotnet-watch

Niektóre opcje konfiguracji można przekazać do dotnet watch za pomocą zmiennych środowiskowych. Dostępne zmienne to:

Ustawienia	Opis
DOTNET_USE_POLLING_FILE_WATCHER	W przypadku ustawienia wartości "1" lub "true" dotnet watch użyje obserwatora FileSystemWatcherplików sondowania zamiast elementu CoreFx. Używany podczas oglądania plików w udziałach sieciowych lub woluminach zainstalowanych na platformie Docker.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Domyślnie, dotnet watch optymalizuje proces budowania, unikając niektórych operacji, takich jak przywrócenie lub ponowna ocena zestawu obserwowanych plików przy każdej zmianie pliku. W przypadku ustawienia wartości "1" lub "true" te optymalizacje są wyłączone.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run próbuje uruchomić przeglądarki dla aplikacji internetowych ze skonfigurowanym launchBrowser w programie launchSettings.json. Jeśli ustawiono wartość "1" lub "true", to zachowanie jest wyłączane.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run program próbuje odświeżyć przeglądarki, gdy wykryje zmiany plików. Jeśli ustawiono wartość "1" lub "true", to zachowanie jest wyłączane. To zachowanie jest również blokowane, jeśli DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER jest ustawione.

Odświeżanie przeglądarki

dotnet watch wprowadza skrypt do aplikacji, który umożliwia jej odświeżenie przeglądarki po zmianie zawartości. W pewnych scenariuszach, takich jak włączenie kompresji odpowiedzi przez aplikację, dotnet watch może nie być w stanie wstrzyknąć skrypt. W takich przypadkach podczas programowania ręcznie wstrzyknąć skrypt do aplikacji. Aby na przykład skonfigurować aplikację internetową w celu ręcznego wstrzyknięcia skryptu, zaktualizuj plik układu, aby zawierał polecenie _framework/aspnet-browser-refresh.js:

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

Znaki inne niż ASCII

Program Visual Studio 17.2 lub nowszy zawiera zestaw .NET SDK 6.0.300 lub nowszy. W przypadku zestawu .NET SDK i wersji 6.0.300 lub nowszej dotnet-watch wyświetla znaki inne niż ASCII na konsoli podczas sesji ponownego ładowania. Na niektórych hostach konsoli, takich jak conhost systemu Windows, te znaki mogą być wyświetlane nieczytelnie. Aby uniknąć zniekształconych znaków, rozważ jedno z następujących podejść:

• Skonfiguruj zmienną środowiskową, DOTNET_WATCH_SUPPRESS_EMOJIS=1 aby pominąć emitowanie tych wartości.
• Przełącz się na inny terminal, taki jak https://github.com/microsoft/terminal, który obsługuje renderowanie znaków innych niż ASCII.