Mengembangkan aplikasi ASP.NET Core menggunakan pengamat file

Oleh Rick Anderson dan Victor Hurdugaci

dotnet watch adalah alat yang menjalankan perintah .NET CLI saat file sumber berubah. Misalnya, perubahan file dapat memicu kompilasi, eksekusi pengujian, atau penyebaran.

Tutorial ini menggunakan API web yang ada dengan dua titik akhir: yang mengembalikan jumlah dan yang mengembalikan produk. Metode produk memiliki bug, yang diperbaiki dalam tutorial ini.

Unduh aplikasi sampel . Ini terdiri dari dua proyek: WebApp (API web ASP.NET Core) dan WebAppTests (pengujian unit untuk API web).

Di shell perintah, navigasikan ke folder WebApp . Jalankan perintah berikut:

dotnet run

Note

Anda dapat menggunakan dotnet run --project <PROJECT> untuk menentukan proyek yang akan dijalankan. Misalnya, menjalankan dotnet run --project WebApp dari akar aplikasi sampel juga akan menjalankan proyek WebApp .

Output konsol menampilkan pesan yang mirip dengan yang berikut (menunjukkan bahwa aplikasi sedang berjalan dan menunggu permintaan):

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

Di browser web, arahkan ke http://localhost:<port number>/api/math/sum?a=4&b=5. Anda seharusnya melihat hasil dari 9.

Navigasikan ke API produk (http://localhost:<port number>/api/math/product?a=4&b=5). Ini mengembalikan 9, tidak 20 seperti yang Anda harapkan. Masalah tersebut diperbaiki nanti dalam tutorial.

Jalankan perintah .NET CLI menggunakan dotnet watch

Setiap perintah .NET CLI dapat dijalankan dengan dotnet watch. For example:

Command	Perintah dengan jam tangan
dotnet run	dotnet watch run
dotnet menjalankan -f netcoreapp3.1	dotnet menjalankan pantauan -f netcoreapp3.1
dotnet jalankan -f netcoreapp3.1 -- --arg1	dotnet watch berjalan -f netcoreapp3.1 -- --arg1
dotnet test	pantau uji dotnet

Jalankan dotnet watch run di folder WebApp . Output konsol menunjukkan bahwa watch telah dimulai.

Saat menjalankan dotnet watch run pada aplikasi berbasis web, akan meluncurkan browser yang menavigasi ke URL aplikasi setelah siap. dotnet watch lakukan ini dengan membaca output konsol aplikasi dan menunggu pesan siap yang ditampilkan oleh WebHost.

dotnet watch me-refresh browser saat mendeteksi perubahan pada file yang ditonton. Untuk melakukan ini, perintah watch menyuntikkan middleware ke aplikasi yang memodifikasi respons HTML yang dibuat oleh aplikasi. Middleware menambahkan blok skrip JavaScript ke halaman yang memungkinkan dotnet watch untuk menginstruksikan browser untuk di-refresh. Saat ini, perubahan pada semua file yang ditonton, termasuk konten statis seperti .html dan .css file menyebabkan aplikasi dibangun kembali.

dotnet watch:

• Hanya memantau file yang memengaruhi build secara default.
• File yang dipantau secara tambahan (melalui konfigurasi) tetap menyebabkan proses build berlangsung.

Untuk informasi selengkapnya tentang konfigurasi, lihat konfigurasi dotnet-watch dalam dokumen ini.

Note

Anda dapat menggunakan dotnet watch --project <PROJECT> untuk menentukan proyek yang akan ditonton. Misalnya, menjalankan dotnet watch --project WebApp run dari akar aplikasi sampel juga akan menjalankan dan memantau proyek WebApp.

Membuat perubahan dengan dotnet watch

Pastikan dotnet watch berjalan.

Perbaiki bug dalam Product metode MathController.cs sehingga mengembalikan produk dan bukan jumlahnya:

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

Simpan file tersebut. Output konsol menunjukkan bahwa dotnet watch mendeteksi perubahan file dan memulai ulang aplikasi.

Verifikasi http://localhost:<port number>/api/math/product?a=4&b=5 mengembalikan hasil yang benar.

Menjalankan pengujian menggunakan dotnet watch

1. Ubah metode Product dari MathController.cs kembali menjadi mengembalikan jumlah. Simpan file tersebut.

2. Di shell perintah, navigasikan ke folder WebAppTests .

3. Jalankan dotnet restore.

4. Jalankan dotnet watch test. Outputnya menunjukkan bahwa pengujian gagal dan pengamat menunggu perubahan file:

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

5. Product Perbaiki kode metode sehingga mengembalikan produk. Simpan file tersebut.

dotnet watch mendeteksi perubahan file dan menjalankan ulang pengujian. Keluaran konsol menunjukkan pengujian berhasil.

Menyesuaikan daftar file untuk ditonton

Secara default, dotnet-watch melacak semua file yang cocok dengan pola glob berikut:

• **/*.cs
• *.csproj
• **/*.resx
• File konten: wwwroot/**, **/*.config, **/*.json

Lebih banyak item dapat ditambahkan ke daftar tonton dengan mengedit .csproj file. Item dapat ditentukan satu per satu atau dengan menggunakan pola glob.

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

Menolak file yang akan ditonton

dotnet-watch dapat dikonfigurasi untuk mengabaikan pengaturan defaultnya. Untuk mengabaikan file tertentu, tambahkan Watch="false" atribut ke definisi item dalam .csproj file:

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

Proyek jam tangan kustom

dotnet-watch tidak dibatasi untuk proyek C#. Proyek jam tangan kustom dapat dibuat untuk menangani skenario yang berbeda. Pertimbangkan tata letak proyek berikut:

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

Jika tujuannya adalah untuk menonton kedua proyek, buat file proyek kustom yang dikonfigurasi untuk menonton kedua proyek:

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

Untuk memulai pengamatan file di kedua proyek, ubah ke folder pengujian . Jalankan perintah berikut:

dotnet watch msbuild /t:Test

VSTest dijalankan ketika ada perubahan file di salah satu proyek pengujian.

dotnet-watch configuration

Beberapa opsi konfigurasi dapat diteruskan ke dotnet watch melalui variabel lingkungan. Variabel yang tersedia adalah:

Setting	Description
DOTNET_USE_POLLING_FILE_WATCHER	Jika diatur ke "1" atau "true", dotnet watch menggunakan pengamat file polling alih-alih CoreFx FileSystemWatcher. Digunakan saat memantau file pada berbagi jaringan atau volume yang dimount Docker.
DOTNET_WATCH_SUPPRESS_MSBUILD_INCREMENTALISM	Secara default, dotnet watch mengoptimalkan build dengan menghindari operasi tertentu seperti menjalankan pemulihan atau mengevaluasi kembali kumpulan file yang ditonton pada setiap perubahan file. Jika diatur ke "1" atau "true", pengoptimalan ini dinonaktifkan.
DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER	dotnet watch run mencoba meluncurkan browser untuk aplikasi web dengan launchBrowser dikonfigurasi di launchSettings.json. Jika diatur ke "1" atau "true", perilaku ini dihentikan.
DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH	dotnet watch run mencoba memuat ulang browser ketika mendeteksi perubahan file. Jika diatur ke "1" atau "true", perilaku ini dihentikan. Perilaku ini juga tidak berlaku jika DOTNET_WATCH_SUPPRESS_LAUNCH_BROWSER disetel.

Browser refresh

dotnet watch menyuntikkan skrip ke dalam aplikasi yang memungkinkannya untuk me-refresh browser saat konten berubah. Dalam beberapa skenario, seperti ketika aplikasi mengaktifkan kompresi respons, dotnet watch mungkin tidak dapat menyuntikkan skrip. Untuk kasus tersebut dalam pengembangan, masukkan skrip secara manual ke dalam aplikasi. Misalnya, untuk mengonfigurasi aplikasi web untuk menyuntikkan skrip secara manual, perbarui file tata letak untuk menyertakan _framework/aspnet-browser-refresh.js:

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

Non-ASCII characters

Visual Studio 17.2 atau yang lebih baru menyertakan .NET SDK 6.0.300 atau yang lebih baru. Dengan .NET SDK versi 6.0.300 atau yang lebih baru, dotnet-watch mengeluarkan karakter non-ASCII ke konsol selama sesi isi ulang panas. Pada host konsol tertentu, seperti conhost Windows, karakter ini mungkin tampak kacau. Untuk menghindari karakter kacau, pertimbangkan salah satu pendekatan berikut:

• Konfigurasikan DOTNET_WATCH_SUPPRESS_EMOJIS=1 variabel lingkungan untuk menekan pemancaran nilai-nilai ini.
• Beralih ke terminal yang berbeda, seperti https://github.com/microsoft/terminal, yang mendukung penyajian karakter non-ASCII.