Membuat pustaka klien REST API
Aplikasi yang menggunakan REST API adalah skenario yang sangat umum. Biasanya, Anda perlu membuat kode klien yang dapat digunakan aplikasi Anda untuk memanggil REST API. Dalam tutorial ini, Anda akan mempelajari cara menghasilkan klien REST API secara otomatis selama proses build menggunakan MSBuild. Anda akan menggunakan NSwag, alat yang menghasilkan kode klien untuk REST API.
Kode sampel lengkap tersedia di pembuatan klien REST API di repositori sampel .NET pada GitHub.
Contoh menunjukkan aplikasi konsol yang menggunakan API Pet Store publik, yang menerbitkan spesifikasi OpenAPI.
Tutorial ini mengasumsikan pengetahuan dasar tentang istilah MSBuild seperti tugas, target, properti, atau runtime; untuk latar belakang yang diperlukan, lihat artikel Konsep MSBuild.
Saat Anda ingin menjalankan alat baris perintah sebagai bagian dari build, ada dua pendekatan yang perlu dipertimbangkan. Salah satunya adalah menggunakan tugas MSBuild Exec, yang memungkinkan Anda menjalankan alat baris perintah dan menentukan parameternya. Metode lainnya adalah membuat tugas kustom yang berasal dari ToolTask, yang memberi Anda kontrol yang lebih besar.
Prasyarat
Anda harus memiliki pemahaman tentang konsep MSBuild seperti tugas, target, dan properti. Lihat konsep MSBuild.
Contohnya memerlukan MSBuild, yang diinstal dengan Visual Studio, tetapi juga dapat diinstal secara terpisah. Lihat Mengunduh MSBuild tanpa Visual Studio.
Opsi 1: Tugas Exec
Tugas Exec hanya memanggil proses yang ditentukan dengan argumen yang ditentukan, menunggunya selesai, dan kemudian mengembalikan true
jika proses berhasil diselesaikan, dan false
jika terjadi kesalahan.
Pembuatan kode NSwag dapat digunakan dari MSBuild; lihat NSwag.MSBuild.
Kode lengkap ada di folder PetReaderExecTaskExample; Anda dapat mengunduh dan melihat. Dalam tutorial ini, Anda akan melalui langkah demi langkah dan mempelajari konsep dalam perjalanan.
Buat aplikasi konsol baru bernama
PetReaderExecTaskExample
. Gunakan .NET 6.0 atau yang lebih baru.Buat proyek lain dalam solusi yang sama:
PetShopRestClient
(Solusi ini akan berisi klien yang dihasilkan sebagai pustaka). Untuk proyek ini, gunakan .NET Standard 2.1. Klien yang dihasilkan tidak dikompilasi pada .NET Standard 2.0.Dalam proyek
PetReaderExecTaskExample
, dan tambahkan dependensi proyek ke proyekPetShopRestClient
.Dalam proyek
PetShopRestClient
, sertakan paket NuGet berikut:- Nswag.MSBuild, yang memungkinkan akses ke generator kode dari MSBuild
- Newtonsoft.Json, diperlukan untuk mengkompilasi klien yang dihasilkan
- System.ComponentModel.Annotations, diperlukan untuk mengompilasi klien yang dihasilkan
Dalam proyek
PetShopRestClient
, tambahkan folder (bernamaPetShopRestClient
) untuk pembuatan kode dan hapus Class1.cs yang dibuat secara otomatis.Membuat file teks dengan nama petshop-openapi-spec.json di akar proyek. Salin spesifikasi OpenApi dari sini dan simpan dalam file. Yang terbaik adalah menyalin snapshot spesifikasi alih-alih membacanya secara online selama build. Anda selalu menginginkan build yang dapat direproduksi secara konsisten yang hanya bergantung pada input. Mengonsumsi API secara langsung dapat mengubah build yang berfungsi hari ini ke build yang gagal besok dari sumber yang sama. Snapshot yang disimpan di petshop-openapi-spec.json akan memungkinkan kita untuk tetap memiliki versi yang dibuat bahkan jika spesifikasi berubah.
Selanjutnya, ubah PetShopRestClient.csproj dan tambahkan target MSBuild untuk menghasilkan klien selama proses build.
Pertama, tambahkan beberapa properti yang berguna untuk pembuatan klien:
<PropertyGroup> <PetOpenApiSpecLocation>petshop-openapi-spec.json</PetOpenApiSpecLocation> <PetClientClassName>PetShopRestClient</PetClientClassName> <PetClientNamespace>PetShopRestClient</PetClientNamespace> <PetClientOutputDirectory>PetShopRestClient</PetClientOutputDirectory> </PropertyGroup>
Tambahkan target berikut:
<Target Name="generatePetClient" BeforeTargets="CoreCompile" Inputs="$(PetOpenApiSpecLocation)" Outputs="$(PetClientOutputDirectory)\$(PetClientClassName).cs"> <Exec Command="$(NSwagExe) openapi2csclient /input:$(PetOpenApiSpecLocation) /classname:$(PetClientClassName) /namespace:$(PetClientNamespace) /output:$(PetClientOutputDirectory)\$(PetClientClassName).cs" ConsoleToMSBuild="true"> <Output TaskParameter="ConsoleOutput" PropertyName="OutputOfExec" /> </Exec> </Target> <Target Name="forceReGenerationOnRebuild" AfterTargets="CoreClean"> <Delete Files="$(PetClientOutputDirectory)\$(PetClientClassName).cs"></Delete> </Target>
Perhatikan bahwa target ini menggunakan atribut BeforeTarget dan AfterTarget sebagai cara untuk menentukan urutan build. Target pertama yang disebut
generatePetClient
akan dijalankan sebelum target kompilasi inti, sehingga sumber akan dibuat sebelum kompilator dijalankan. Parameter input dan output terkait dengan Build Bertambah Bertahap. MSBuild dapat membandingkan tanda waktu file input dengan tanda waktu file output dan menentukan apakah akan melewati, membangun, atau membangun kembali sebagian target.Setelah menginstal paket NuGet
NSwag.MSBuild
di proyek Anda, Anda dapat menggunakan variabel$(NSwagExe)
dalam file.csproj
Anda untuk menjalankan alat baris perintah NSwag dalam target MSBuild. Dengan cara ini, alat dapat dengan mudah diperbarui melalui NuGet. Di sini, Anda menggunakan tugas MSBuildExec
untuk menjalankan program NSwag dengan parameter yang diperlukan untuk menghasilkan Rest Api klien. Lihat perintah dan parameter NSwag.Anda dapat mengambil output dari
<Exec>
menambahkanConsoleToMsBuild="true"
ke tag<Exec>
Anda lalu menangkap output menggunakan parameterConsoleOutput
dalam tag<Output>
.ConsoleOutput
mengembalikan output sebagaiItem
. Spasi kosong dipangkas.ConsoleOutput
diaktifkan ketikaConsoleToMSBuild
benar.Target kedua yang disebut
forceReGenerationOnRebuild
menghapus kelas yang dihasilkan selama pembersihan untuk memaksa regenerasi kode yang dihasilkan selama eksekusi target pembangunan kembali. Target ini berjalan setelah target MSBuild yang telah ditentukan sebelumnyaCoreClean
.Jalankan pembangunan kembali solusi Visual Studio dan lihat klien yang dihasilkan pada folder
PetShopRestClient
.Sekarang, gunakan klien yang dihasilkan. Buka Program.cs klien, dan salin kode berikut:
using System; using System.Net.Http; namespace PetReaderExecTaskExample { internal class Program { private const string baseUrl = "https://petstore.swagger.io/v2"; static void Main(string[] args) { HttpClient httpClient = new HttpClient(); httpClient.BaseAddress = new Uri(baseUrl); var petClient = new PetShopRestClient.PetShopRestClient(httpClient); var pet = petClient.GetPetByIdAsync(1).Result; Console.WriteLine($"Id: {pet.Id} Name: {pet.Name} Status: {pet.Status} CategoryName: {pet.Category.Name}"); } } }
Catatan
Kode ini menggunakan
new HttpClient()
karena mudah untuk ditunjukkan, tetapi ini bukan praktik terbaik untuk kode dunia nyata. Praktik terbaik adalah menggunakanHttpClientFactory
untuk membuat objekHttpClient
yang mengatasi masalah permintaanHttpClient
yang diketahui seperti Kelelahan Sumber Daya atau Masalah DNS Kedaluarsa. Lihat Gunakan IHttpClientFactory untuk menerapkan permintaan HTTP yang tangguh.
Selamat! Sekarang, Anda dapat menjalankan program untuk melihat cara kerjanya.
Opsi 2: Tugas kustom yang berasal dari ToolTask
Dalam banyak kasus, menggunakan tugas Exec
ini cukup baik untuk menjalankan alat eksternal untuk melakukan sesuatu seperti pembuatan kode klien REST API, tetapi bagaimana jika Anda ingin mengizinkan pembuatan kode klien REST API jika dan hanya jika Anda tidak menggunakan jalur Windows absolut sebagai input? Atau bagaimana jika Anda perlu mengalkulasi dengan suatu cara di mana executable berada? Ketika ada situasi di mana Anda perlu menjalankan beberapa kode untuk melakukan pekerjaan ekstra, MSBuild Tool Task adalah solusi terbaik. Kelas ToolTask
ini adalah kelas abstrak yang berasal dari MSBuild Task
. Anda dapat menentukan subkelas konkret, yang membuat tugas MSBuild kustom. Pendekatan ini memungkinkan Anda menjalankan kode apa pun yang diperlukan untuk mempersiapkan eksekusi perintah. Anda harus membaca tutorial Membuat tugas kustom untuk pembuatan kode terlebih dahulu.
Anda akan membuat tugas kustom yang berasal dari MSBuild ToolTask yang akan menghasilkan klien REST API, tetapi akan dirancang untuk memancarkan kesalahan jika Anda mencoba mereferensikan spesifikasi OpenApi menggunakan alamat http. NSwag mendukung alamat http sebagai input spesifikasi OpenApi, tetapi untuk tujuan dari contoh ini, anggap saja ada persyaratan desain untuk melarangnya.
Kode lengkap ada di folder PetReaderToolTaskExample
ini; Anda dapat mengunduh dan melihat. Dalam tutorial ini, Anda akan melalui langkah demi langkah dan mempelajari beberapa konsep yang dapat Anda terapkan untuk skenario Anda sendiri.
Buat Visual Studio Project baru untuk tugas kustom. Panggil
RestApiClientGenerator
dan gunakan templat Pustaka Kelas (C#) dengan .NET Standard 2.0. Beri nama solusiPetReaderToolTaskExample
.Hapus Class1.cs, yang dibuat secara otomatis.
Tambahkan paket NuGet
Microsoft.Build.Utilities.Core
:Buat kelas bernama
RestApiClientGenerator
Warisi dari MSBuild
ToolTask
dan terapkan metode abstrak seperti yang ditunjukkan dalam kode berikut:using Microsoft.Build.Utilities; namespace RestApiClientGenerator { public class RestApiClientGenerator : ToolTask { protected override string ToolName => throw new System.NotImplementedException(); protected override string GenerateFullPathToTool() { throw new System.NotImplementedException(); } } }
Tambahkan parameter berikut:
- InputOpenApiSpec, di mana spesifikasinya
- ClientClassName, nama kelas yang dihasilkan
- ClientNamespaceName, namespace layanan tempat kelas dihasilkan
- FolderClientClass, jalur ke folder tempat kelas akan berada
- NSwagCommandFullPath, jalur lengkap ke direktori tempat NSwag.exe berada
[Required] public string InputOpenApiSpec { get; set; } [Required] public string ClientClassName { get; set; } [Required] public string ClientNamespaceName { get; set; } [Required] public string FolderClientClass { get; set; } [Required] public string NSwagCommandFullPath { get; set; }
Instal alat baris perintah NSwag. Anda akan memerlukan jalur lengkap ke direktori tempat NSwag.exe berada.
Terapkan metode abstrak:
protected override string ToolName => "RestApiClientGenerator"; protected override string GenerateFullPathToTool() { return $"{NSwagCommandFullPath}\\NSwag.exe"; }
Ada banyak metode yang dapat Anda ambil alih. Untuk implementasi saat ini, tentukan keduanya hal berikut:
- Tentukan parameter perintah:
protected override string GenerateCommandLineCommands() { return $"openapi2csclient /input:{InputOpenApiSpec} /classname:{ClientClassName} /namespace:{ClientNamespaceName} /output:{FolderClientClass}\\{ClientClassName}.cs"; }
- Validasi parameter:
protected override bool ValidateParameters() { //http address is not allowed var valid = true; if (InputOpenApiSpec.StartsWith("http:") || InputOpenApiSpec.StartsWith("https:")) { valid = false; Log.LogError("URL is not allowed"); } return valid; }
Catatan
Validasi sederhana ini dapat dilakukan dengan cara lain pada file MSBuild, tetapi disarankan untuk melakukannya dalam kode C# dan merangkum perintah dan logika.
Bangun proyek.
Membuat aplikasi konsol untuk menggunakan tugas MSBuild baru
Langkah selanjutnya adalah membuat aplikasi yang menggunakan tugas tersebut.
Buat proyek Aplikasi Konsol, dan sebut saja
PetReaderToolTaskConsoleApp
. Pilih .NET 6.0. Tandai sebagai proyek startup.Buat proyek Pustaka Kelas untuk menghasilkan kode, yang disebut
PetRestApiClient
. Gunakan .NET Standard 2.1.Dalam proyek
PetReaderToolTaskConsoleApp
, buat dependensi proyek kePetRestApiClient
.Dalam proyek
PetRestApiClient
, buat folderPetRestApiClient
. Folder ini akan berisi kode yang dihasilkan.Hapus Class1.cs, yang dibuat secara otomatis.
Pada
PetRestApiClient
, tambahkan paket NuGet berikut:- Newtonsoft.Json, diperlukan untuk mengkompilasi klien yang dihasilkan
- System.ComponentModel.Annotations, diperlukan untuk mengompilasi klien yang dihasilkan
Dalam proyek
PetRestApiClient
, buat file teks bernama petshop-openapi-spec.json (di folder proyek). Untuk menambahkan spesifikasi OpenApi, salin konten dari sini ke dalam file. Kita menyukai build yang dapat direproduksi yang hanya bergantung pada input, seperti yang dibahas sebelumnya. Dalam contoh ini, Anda akan memunculkan kesalahan build jika pengguna memilih URL sebagai input spesifikasi OpenApi.Penting
Rebuild umum tidak akan berfungsi. Anda akan melihat kesalahan yang menunjukkan tidak dapat menyalin atau menghapus
RestApiClientGenerator
.dll'. Ini karena bagian ini mencoba membangun tugas kustom MBuild dalam proses build yang sama yang menggunakannya. PilihPetReaderToolTaskConsoleApp
dan bangun kembali hanya proyek tersebut. Solusi lain adalah menempatkan tugas kustom dalam solusi Visual Studio yang sepenuhnya independen seperti yang Anda lakukan di Tutorial: Membuat contoh tugas kustom.Salin kode berikut ke dalam Program.cs:
using System; using System.Net.Http; namespace PetReaderToolTaskConsoleApp { internal class Program { private const string baseUrl = "https://petstore.swagger.io/v2"; static void Main(string[] args) { HttpClient httpClient = new HttpClient(); httpClient.BaseAddress = new Uri(baseUrl); var petClient = new PetRestApiClient.PetRestApiClient(httpClient); var pet = petClient.GetPetByIdAsync(1).Result; Console.WriteLine($"Id: {pet.Id} Name: {pet.Name} Status: {pet.Status} CategoryName: {pet.Category.Name}"); } } }
Ubah instruksi MSBuild untuk memanggil tugas dan menghasilkan kode. Edit PetRestApiClient.csproj dengan mengikuti langkah-langkah berikut:
Daftarkan penggunaan tugas kustom MSBuild:
<UsingTask TaskName="RestApiClientGenerator.RestApiClientGenerator" AssemblyFile="..\RestApiClientGenerator\bin\Debug\netstandard2.0\RestApiClientGenerator.dll" />
Tambahkan beberapa properti yang diperlukan untuk menjalankan tugas:
<PropertyGroup> <!--The place where the OpenApi spec is in--> <PetClientInputOpenApiSpec>petshop-openapi-spec.json</PetClientInputOpenApiSpec> <PetClientClientClassName>PetRestApiClient</PetClientClientClassName> <PetClientClientNamespaceName>PetRestApiClient</PetClientClientNamespaceName> <PetClientFolderClientClass>PetRestApiClient</PetClientFolderClientClass> <!--The directory where NSawg.exe is in--> <NSwagCommandFullPath>C:\Nsawg\Win</NSwagCommandFullPath> </PropertyGroup>
Penting
Pilih nilai
NSwagCommandFullPath
yang tepat berdasarkan lokasi penginstalan pada sistem Anda.Tambahkan target MSBuild untuk menghasilkan klien selama proses build. Target ini harus dijalankan sebelum
CoreCompile
dijalankan untuk menghasilkan kode yang digunakan dalam kompilasi.<Target Name="generatePetClient" BeforeTargets="CoreCompile" Inputs="$(PetClientInputOpenApiSpec)" Outputs="$(PetClientFolderClientClass)\$(PetClientClientClassName).cs"> <!--Calling our custom task derivated from MSBuild Tool Task--> <RestApiClientGenerator InputOpenApiSpec="$(PetClientInputOpenApiSpec)" ClientClassName="$(PetClientClientClassName)" ClientNamespaceName="$(PetClientClientNamespaceName)" FolderClientClass="$(PetClientFolderClientClass)" NSwagCommandFullPath="$(NSwagCommandFullPath)"></RestApiClientGenerator> </Target> <Target Name="forceReGenerationOnRebuild" AfterTargets="CoreClean"> <Delete Files="$(PetClientFolderClientClass)\$(PetClientClientClassName).cs"></Delete> </Target>
Input
danOutput
terkait dengan Build Inkremental, danforceReGenerationOnRebuild
target menghapus file yang dihasilkan setelahCoreClean
, yang memaksa klien untuk diregenerasi selama operasi pembangunan ulang.Pilih
PetReaderToolTaskConsoleApp
dan bangun kembali hanya proyek tersebut. Sekarang, kode klien dihasilkan dan kode dikompilasi. Anda dapat menjalankannya dan melihat cara kerjanya. Kode ini menghasilkan kode dari file, dan yang diizinkan.Dalam langkah ini, Anda akan mendemonstrasikan validasi parameter. Di PetRestApiClient.csproj, ubah properti
$(PetClientInputOpenApiSpec)
untuk menggunakan URL:<PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
Pilih
PetReaderToolTaskConsoleApp
dan bangun kembali hanya proyek tersebut. Anda akan mendapatkan kesalahan, "URL tidak diizinkan" sesuai dengan persyaratan desain.
Unduh kode
Instal alat baris perintah NSwag. Kemudian, Anda memerlukan jalur lengkap ke direktori tempat NSwag.exe berada. Setelah itu, edit PetRestApiClient.csproj dan pilih nilai $(NSwagCommandFullPath)
yang tepat berdasarkan jalur penginstalan di komputer Anda. Sekarang, pilih RestApiClientGenerator
dan bangun hanya proyek itu, dan akhirnya pilih dan bangun PetReaderToolTaskConsoleApp
kembali. Anda dapat menjalankan PetReaderToolTaskConsoleApp
. untuk memverifikasi bahwa semuanya berfungsi seperti yang diharapkan.
Langkah berikutnya
Anda mungkin ingin menerbitkan tugas kustom Anda sebagai paket NuGet.
Atau, pelajari cara menguji tugas kustom.
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk