Membuat pustaka klien REST API

Artikel
06/19/2023

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 proyek PetShopRestClient.
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 (bernama PetShopRestClient) 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 MSBuild Exec untuk menjalankan program NSwag dengan parameter yang diperlukan untuk menghasilkan Rest Api klien. Lihat perintah dan parameter NSwag.

Anda dapat mengambil output dari <Exec> menambahkan ConsoleToMsBuild="true" ke tag <Exec> Anda lalu menangkap output menggunakan parameter ConsoleOutput dalam tag <Output>. ConsoleOutput mengembalikan output sebagai Item. Spasi kosong dipangkas. ConsoleOutput diaktifkan ketika ConsoleToMSBuild 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 sebelumnya CoreClean.
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 menggunakan HttpClientFactory untuk membuat objek HttpClient yang mengatasi masalah permintaan HttpClient 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 solusi PetReaderToolTaskExample.
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 ke PetRestApiClient.
Dalam proyek PetRestApiClient, buat folder PetRestApiClient. 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. Pilih PetReaderToolTaskConsoleApp 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 dan Output terkait dengan Build Inkremental, danforceReGenerationOnRebuild target menghapus file yang dihasilkan setelah CoreClean, 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.

Tutorial: Membuat tugas kustom

Atau, pelajari cara menguji tugas kustom.

Menguji tugas MSBuild kustom