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 Core 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 internetowy interfejs API z dwoma punktami końcowymi: jeden, który zwraca sumę i jeden, który zwraca produkt. Metoda produktu zawiera usterkę, która została naprawiona w tym samouczku.

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

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

dotnet run

Uwaga

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=5adresu . Powinien zostać wyświetlony 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ń interfejsu wiersza polecenia platformy .NET Core przy użyciu polecenia dotnet watch

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

Polecenie	Polecenie z zegarkiem
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 . Dane wyjściowe konsoli wskazują, że zostało uruchomione watch .

Uruchomienie dotnet watch run aplikacji internetowej powoduje uruchomienie przeglądarki, która przechodzi do adresu URL aplikacji po uzyskaniu gotowości. 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 wszystkich obserwowanych plików, w tym zawartości statycznej, takiej jak .html i .css pliki, powodują ponowne skompilowanie aplikacji.

dotnet watch:

• Tylko pliki, które mają wpływ na kompilacje domyślnie.
• 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

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

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 powrotu, MathController.cs aby zwrócić sumę. Zapisz plik.

2. W powłoce poleceń przejdź do folderu WebAppTests .

3. Uruchom polecenie dotnet restore.

4. Uruchom polecenie 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>

Rezygnacja z plików do obejrzenia

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 zmiennych środowiskowych. Dostępne zmienne to:

Ustawienie	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 optymalizuje kompilację, unikając niektórych operacji, dotnet watch takich jak uruchamianie przywracania lub ponowne ocenianie zestawu obserwowanych plików na 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 pomijane.
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 pomijane. To zachowanie jest również pomijane w przypadku DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER ustawienia.

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 niektórych scenariuszach, takich jak włączenie kompresji odpowiedzi przez aplikację, dotnet watch może nie być w stanie wstrzyknąć skryptu. 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 nowszej dotnet-watch program emituje znaki inne niż ASCII do konsoli podczas sesji ponownego ładowania. Na niektórych hostach konsoli, takich jak conhost systemu Windows, te znaki mogą być wyświetlane zwijać. Aby uniknąć zwijania znaków, należy wziąć pod uwagę jedno z następujących podejść:

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