Tutorial: Membuat 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 membuat 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 di GitHub.

Contoh menunjukkan aplikasi konsol yang menggunakan API Pet Storepublik , yang menerbitkan spesifikasi OpenAPI .

Tutorial 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 Unduh MSBuild tanpa Visual Studio.

Opsi 1: Tugas eksekusi

Tugas Exec hanya memanggil proses yang ditentukan dengan argumen yang ditentukan, menunggunya selesai, lalu 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 selama proses.

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.
Buat file teks bernama petshop-openapi-spec.json di akar proyek. Salin spesifikasi OpenAPI dari di sini dan simpan dalam file. Yang terbaik adalah menyalin salinan dokumen spesifikasi alih-alih membacanya secara online selama proses pembangunan. Anda selalu menginginkan build yang dapat direproduksi secara konsisten yang hanya bergantung pada input. Menggunakan API secara langsung dapat mengubah build yang berfungsi hari ini ke build yang gagal besok dari sumber yang sama. Cuplikan yang disimpan di petshop-openapi-spec.json memungkinkan kita tetap memiliki versi yang dapat dibangun 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 pengkompilasi dijalankan. Parameter input dan output tersebut terkait dengan Pembangunan Inkremental. MSBuild dapat membandingkan tanda waktu file input dengan tanda waktu file output dan menentukan apakah akan melewati, membangun, atau membangun ulang 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 Exec MSBuild untuk menjalankan program NSwag dengan parameter yang diperlukan guna menghasilkan API Rest 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. Ruang kosong dipotong. ConsoleOutput diaktifkan saat ConsoleToMSBuild benar.

Target kedua yang disebut forceReGenerationOnRebuild menghapus kelas yang dihasilkan selama pembersihan untuk memaksa regenerasi kode yang dihasilkan selama eksekusi target pembangunan ulang. Target ini berjalan setelah target CoreClean MSBuild yang sudah ditetapkan sebelumnya.
Jalankan pembangunan ulang Visual Studio Solution dan lihat klien yang dihasilkan pada folder PetShopRestClient.

Sekarang, gunakan klien yang dihasilkan. Buka klien Program.cs, 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}");
       }
   }
}

Nota

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 yang diketahui dari permintaan HttpClient seperti Kelelahan Sumber Daya atau Masalah DNS Kedaluarsa. Lihat Menggunakan IHttpClientFactory untuk menerapkan permintaan HTTP yang tangguh.

Selamat! Sekarang, Anda dapat menjalankan program untuk melihat cara kerjanya.

Opsi 2: Tugas kustom berasal dari ToolTask

Dalam banyak kasus, menggunakan tugas Exec 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 menentukan letak di mana executable ditempatkan? Ketika ada situasi di mana Anda perlu menjalankan beberapa kode untuk melakukan pekerjaan ekstra, MSBuild Tool Task adalah solusi terbaik. Kelas ToolTask 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 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 ke skenario Anda sendiri.

Buat Proyek Visual Studio baru untuk tugas kustom. Sebut saja RestApiClientGenerator dan gunakan templat Class Library (C#) dengan .NET Standard 2.0. Beri nama solusi PetReaderToolTaskExample.
Hapus Class1.cs, yang dibuat secara otomatis.

Tambahkan paket NuGet Microsoft.Build.Utilities.Core:

Membuat kelas yang disebut 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 spesifikasi diberikan
ClientClassName, nama kelas yang dihasilkan
ClientNamespaceName, namespace 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:

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

Nota

Validasi sederhana ini dapat dilakukan dengan cara lain pada file MSBuild, tetapi disarankan 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.

Buat proyek Aplikasi Konsol, dan beri nama PetReaderToolTaskConsoleApp. Pilih versi .NET yang diinginkan. Tandai sebagai proyek startup.
Buat proyek Pustaka Kelas untuk menghasilkan kode yang dinamakan PetRestApiClient. Gunakan .NET Standard.
Dalam proyek PetReaderToolTaskConsoleApp, buat dependensi proyek untuk 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 di sini ke dalam file. Kami menyukai build yang dapat direproduksi yang hanya bergantung pada input, seperti yang dibahas sebelumnya. Dalam contoh ini, Anda akan menimbulkan kesalahan build jika pengguna memilih URL sebagai input spesifikasi OpenAPI.

Penting

Pembangunan ulang secara umum tidak efektif. Anda akan melihat kesalahan yang menunjukkan ketidakmampuan untuk menyalin atau menghapus RestApiClientGenerator.dll'. Ini karena mencoba membangun tugas kustom MBuild dalam proses build yang sama yang menggunakannya. Pilih PetReaderToolTaskConsoleApp dan membangun ulang hanya proyek tersebut. Solusi lain adalah menempatkan tugas kustom dalam solusi Visual Studio yang sepenuhnya independen seperti yang Anda lakukan di Tutorial : Membuat tugas kustom contoh.

Salin kode berikut ke 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, dan target forceReGenerationOnRebuild menghapus file yang dihasilkan setelah CoreClean, yang memaksa klien untuk diregenerasi selama operasi kompilasi ulang.

Pilih PetReaderToolTaskConsoleApp dan membangun ulang hanya proyek tersebut. Sekarang, kode klien dihasilkan dan kode dikompilasi. Anda dapat menjalankannya dan melihat cara kerjanya. Kode ini menghasilkan kode dari file, dan hal itu diperbolehkan.
Dalam langkah ini, Anda akan menunjukkan validasi parameter. Di PetRestApiClient.csproj, ubah properti $(PetClientInputOpenApiSpec) untuk menggunakan URL:
```
  <PetClientInputOpenApiSpec>https://petstore.swagger.io/v2/swagger.json</PetClientInputOpenApiSpec>
```
Pilih PetReaderToolTaskConsoleApp dan membangun ulang hanya proyek tersebut. Anda akan mendapatkan kesalahan, "URL tidak diizinkan" sesuai dengan persyaratan desain.

Mengunduh 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 kembali PetReaderToolTaskConsoleApp. 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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-12