Cara menggunakan versi API di ASP.NET Core

Semasa mengembangkan API, anda harus ingat satu perkara: Perubahan tidak dapat dielakkan. Apabila API anda telah mencapai tahap di mana anda perlu menambahkan lebih banyak tanggungjawab, anda harus mempertimbangkan untuk memformat API anda. Oleh itu, anda memerlukan strategi versi.

Terdapat beberapa pendekatan untuk membuat API versi, dan masing-masing mempunyai kelebihan dan kekurangan. Artikel ini akan membincangkan tantangan versi API dan bagaimana anda dapat bekerja dengan pakej Versi ASP.NET Core MVC Microsoft ke versi RESTful API yang dibina dalam ASP.NET Core. Anda boleh membaca lebih lanjut mengenai versi API Web dalam artikel saya sebelumnya di sini. 

Buat projek ASP.NET Core 3.1 API

Pertama, mari buat projek Teras ASP.NET di Visual Studio. Dengan mengandaikan Visual Studio 2019 dipasang di sistem anda, ikuti langkah-langkah yang digariskan di bawah untuk membuat projek Teras ASP.NET baru di Visual Studio.

  1. Lancarkan ID Studio Visual.
  2. Klik pada "Buat projek baru."
  3. Di tetingkap "Buat projek baru", pilih "Aplikasi Web Inti ASP.NET" dari senarai templat yang dipaparkan.
  4. Klik Seterusnya.
  5. Di tetingkap "Konfigurasikan projek baru anda" yang ditunjukkan di sebelah, tentukan nama dan lokasi untuk projek baru.
  6. Klik Buat.
  7. Di tetingkap "Buat Aplikasi Web Teras ASP.NET Teras", pilih .NET Core sebagai runtime dan ASP.NET Core 3.1 (atau lebih baru) dari senarai juntai bawah di bahagian atas. Saya akan menggunakan ASP.NET Core 3.1 di sini.
  8. Pilih "API" sebagai templat projek untuk membuat aplikasi ASP.NET Core API baru. 
  9. Pastikan bahawa kotak centang "Aktifkan Docker Support" dan "Configure for HTTPS" tidak dicentang kerana kami tidak akan menggunakan fitur tersebut di sini.
  10. Pastikan bahawa Pengesahan ditetapkan sebagai "Tanpa Pengesahan" kerana kami juga tidak akan menggunakan pengesahan.
  11. Klik Buat. 

Ini akan membuat projek ASP.NET Core API baru di Visual Studio. Pilih folder penyelesaian Pengawal di tetingkap Penyelesaian Penyelesaian dan klik "Tambah -> Pengawal ..." untuk membuat pengawal baru bernama DefaultController.

Ganti kod sumber kelas DefaultController dengan kod berikut.

    [Laluan ("api / [pengawal]")]

    [ApiController]

    kelas awam DefaultController: ControllerBase

    {

        rentetan [] pengarang = rentetan baru []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        awam IEnumerable Get ()

        {

            pengarang kembali;

        }

    }

Kami akan menggunakan alat kawalan ini di bahagian seterusnya artikel ini.

Untuk melaksanakan versi API dalam ASP.NET Core, anda perlu melakukan perkara berikut:

  1. Pasang pakej ASP.NET Core MVC Versioning.
  2. Konfigurasikan versi API di kelas Permulaan.
  3. Nyatakan pengawal dan tindakan dengan atribut yang sesuai.

Pasang pakej ASP.NET Core MVC Versioning

ASP.NET Core memberikan sokongan untuk pemformatan API di luar kotak. Untuk memanfaatkan versi API, yang perlu anda lakukan ialah memasang pakej Microsoft.AspNetCore.Mvc.Versioning dari NuGet. Anda boleh melakukannya sama ada melalui pengurus pakej NuGet di dalam Visual Studio 2019 IDE, atau dengan melaksanakan perintah berikut di konsol pengurus pakej NuGet:

Pasang-Pakej Microsoft.AspNetCore.Mvc.Versioning

Perhatikan bahawa jika anda menggunakan ASP.NET Web API, anda harus menambahkan pakej Microsoft.AspNet.WebApi.Versioning.

Konfigurasikan versi API dalam ASP.NET Core

Sekarang bahawa pakej yang diperlukan untuk memformat API anda telah dipasang di projek anda, anda dapat mengkonfigurasi versi API dalam kaedah ConfigureServices dari kelas Startup. Coretan kod berikut menggambarkan bagaimana ini dapat dicapai.

kekosongan awam ConfigureServices (perkhidmatan IServiceCollection)

{

  perkhidmatan.AddControllers ();

  perkhidmatan.AddApiVersioning ();

}

Apabila anda membuat permintaan Get ke API, anda akan diberi kesalahan yang ditunjukkan dalam Gambar 1.

Untuk menyelesaikan ralat ini, anda dapat menentukan versi lalai ketika menambahkan perkhidmatan versi API ke wadah. Anda mungkin juga ingin menggunakan versi lalai jika versi tidak ditentukan dalam permintaan. Coretan kod berikut menunjukkan bagaimana anda dapat menetapkan versi lalai sebagai 1.0 menggunakan harta AssumeDefaultVersionWhenUnspecified jika maklumat versi tidak tersedia dalam permintaan.

perkhidmatan.AddApiVersioning (config =>

{

   config.DefaultApiVersion = ApiVersion baru (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = benar;

});

Perhatikan bagaimana versi utama dan versi kecil diserahkan kepada pembangun kelas ApiVersion pada saat menetapkan versi lalai. Properti AssumeDefaultVersionWhenUnspecified boleh menyimpan nilai benar atau salah. Sekiranya benar, versi lalai yang ditentukan ketika mengkonfigurasi versi API akan digunakan jika tidak ada informasi versi yang tersedia.

Kod sumber lengkap kaedah ConfigureServices diberikan di bawah untuk rujukan anda.

kekosongan awam ConfigureServices (perkhidmatan IServiceCollection)

{

    perkhidmatan.AddControllers ();

    perkhidmatan.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = ApiVersion baru (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = benar;

    });

}

Oleh kerana anda belum menentukan maklumat versi, semua titik akhir akan mempunyai versi 1.0 lalai.

Laporkan semua versi API yang disokong

Anda mungkin ingin memberi tahu klien API semua versi yang disokong. Untuk melakukan ini, anda harus memanfaatkan properti ReportApiVersions seperti yang ditunjukkan dalam coretan kod yang diberikan di bawah.

perkhidmatan.AddApiVersioning (config =>

{

  config.DefaultApiVersion = ApiVersion baru (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = benar;

  config.ReportApiVersions = benar;

});

Gunakan versi dalam kaedah pengawal dan tindakan

Sekarang mari kita tambahkan beberapa versi yang disokong ke pengawal kami menggunakan atribut seperti yang ditunjukkan dalam coretan kod yang diberikan di bawah.

    [Laluan ("api / [pengawal]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    kelas awam DefaultController: ControllerBase

    {

        rentetan [] pengarang = rentetan baru []

        {"Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        awam IEnumerable Get ()

        {

            pengarang kembali;

        }

    }

Apabila anda membuat permintaan Get dari klien HTTP seperti Postman, berikut adalah bagaimana versi akan dilaporkan.

Anda juga boleh melaporkan versi yang tidak digunakan lagi. Untuk melakukan ini, anda harus meneruskan parameter tambahan ke kaedah ApiVersion seperti yang ditunjukkan dalam potongan kode yang diberikan di bawah.

[ApiVersion ("1.0", Tidak digunakan lagi = benar)]

Petakan ke versi tertentu dari kaedah tindakan

Terdapat satu lagi sifat penting bernama MapToApiVersion. Anda dapat menggunakannya untuk memetakan ke versi tertentu dari kaedah tindakan. Coretan kod berikut menunjukkan bagaimana ini dapat dicapai.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

rentetan awam Dapatkan (int id)

{

   pengarang kembali [id];

}

Lengkapkan contoh versi API dalam ASP.NET Core

Berikut adalah kod sumber lengkap DefaultController untuk rujukan anda.

[Laluan ("api / [pengawal]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

kelas awam DefaultController: ControllerBase

{

  rentetan [] pengarang = rentetan baru []

  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  awam IEnumerable Get ()

  {

      pengarang kembali;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  rentetan awam Dapatkan (int id)

  {

     pengarang kembali [id];

  }

}

Strategi versi API di ASP.NET Core

Terdapat beberapa cara di mana anda dapat membuat versi API anda di ASP.NET Core. Di bahagian ini kita akan menerokai masing-masing.

Lulus maklumat versi sebagai parameter QueryString

Dalam kes ini, anda biasanya akan menyampaikan maklumat versi sebagai sebahagian daripada rentetan pertanyaan seperti yang ditunjukkan dalam URL yang diberikan di bawah.

//localhost:25718/api/default?api-version=1.0

Lulus maklumat versi dalam tajuk HTTP

Sekiranya anda ingin menyampaikan maklumat versi dalam tajuk HTTP, anda harus menyiapkannya dalam kaedah ConfigureServices seperti yang ditunjukkan dalam coretan kod yang diberikan di bawah.

perkhidmatan.AddApiVersioning (config =>

{

   config.DefaultApiVersion = ApiVersion baru (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = benar;

   config.ReportApiVersions = benar;

   config.ApiVersionReader = HeaderApiVersionReader baru ("api-version");

});

Setelah ini disiapkan, Anda dapat menggunakan metode tindakan yang berkaitan dengan versi tertentu dari API seperti yang ditunjukkan pada Gambar 3.

Lulus maklumat versi dalam URL

Kaedah lain untuk menyebarkan maklumat versi adalah menyampaikan maklumat versi sebagai sebahagian daripada laluan. Ini adalah kaedah termudah untuk memformat API anda tetapi ada peringatan tertentu. Pertama, jika anda menggunakan strategi ini, klien anda perlu mengemas kini URL setiap kali versi baru API dilepaskan. Oleh itu, pendekatan ini melanggar prinsip asas REST yang menyatakan bahawa URL sumber tertentu tidak boleh berubah.

Untuk melaksanakan strategi versi ini, anda harus menentukan maklumat laluan di pengawal anda seperti yang ditunjukkan di bawah.

[Laluan ("api / v {versi: apiVersion} / [pengawal]")]

Penyenaraian kod berikut menunjukkan bagaimana anda boleh menetapkannya di kelas pengawal anda.

[Laluan ("api / v {versi: apiVersion} / [pengawal]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

kelas awam DefaultController: ControllerBase

    {

        rentetan [] pengarang = rentetan baru []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        awam IEnumerable Get ()

        {

            pengarang kembali;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        rentetan awam Dapatkan (int id)

        {

            pengarang kembali [id];

        }

    }

Inilah cara anda memanggil HTTP lalai untuk mendapatkan kaedah kelas DefaultController.

//localhost:25718/api/v1.0/ lalai

Untuk menggunakan kaedah HTTP GET yang lain, yaitu, yang menerima parameter, tentukan yang berikut sama ada di penyemak imbas web atau klien HTTP seperti Postman.

//localhost:25718/api/v2.0/default/1

Tidak menggunakan satu atau lebih versi API anda

Andaikan anda mempunyai banyak versi API tetapi anda ingin menghentikan satu atau lebih daripadanya. Anda boleh melakukannya dengan mudah - anda hanya perlu menentukan sifat Tidak digunakan dari kelas ApiVersionAttribute menjadi benar seperti yang ditunjukkan dalam potongan kod yang diberikan di bawah.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", Tidak digunakan lagi = benar)]

[ApiVersion ("2.0")]

kelas awam DefaultController: ControllerBase

{

     // Kod biasa

}

Versi API dalam ASP.NET Core kini lancar berkat pengenalan pakej Microsoft.AspNetCore.Mvc.Versioning. Terdapat beberapa cara untuk membuat versi API anda - anda hanya perlu memutuskan strategi terbaik berdasarkan keperluan anda. Anda juga boleh menggunakan beberapa skema versi untuk API anda. Ini menambahkan banyak fleksibiliti kerana pelanggan dapat memilih salah satu skema versi yang disokong.

Cara melakukan lebih banyak perkara dalam ASP.NET Core:

  • Cara menggunakan Objek Pemindahan Data dalam ASP.NET Core 3.1
  • Cara mengatasi ralat 404 dalam ASP.NET Core MVC
  • Cara menggunakan suntikan kebergantungan dalam penapis tindakan dalam ASP.NET Core 3.1
  • Cara menggunakan corak pilihan dalam ASP.NET Core
  • Cara menggunakan penghalaan titik akhir dalam ASP.NET Core 3.0 MVC
  • Cara mengeksport data ke Excel dalam ASP.NET Core 3.0
  • Cara menggunakan LoggerMessage dalam ASP.NET Core 3.0
  • Cara menghantar e-mel dalam ASP.NET Core
  • Cara log data ke SQL Server di ASP.NET Core
  • Cara menjadualkan pekerjaan menggunakan Quartz.NET di ASP.NET Core
  • Cara mengembalikan data dari ASP.NET Core Web API
  • Cara memformat data tindak balas dalam ASP.NET Core
  • Cara menggunakan API Web Teras ASP.NET menggunakan RestSharp
  • Cara melakukan operasi async menggunakan Dapper
  • Cara menggunakan bendera ciri dalam ASP.NET Core
  • Cara menggunakan atribut FromServices di ASP.NET Core
  • Cara bekerja dengan kuki di ASP.NET Core
  • Cara bekerja dengan fail statik di ASP.NET Core
  • Cara menggunakan Middleware Menulis Semula URL di ASP.NET Core
  • Cara melaksanakan pembatasan kadar di ASP.NET Core
  • Cara menggunakan Wawasan Aplikasi Azure di ASP.NET Core
  • Menggunakan ciri NLog canggih dalam ASP.NET Core
  • Cara menangani ralat dalam API Web ASP.NET
  • Cara melaksanakan pengendalian pengecualian global di ASP.NET Core MVC
  • Cara menangani nilai null di ASP.NET Core MVC
  • Versi lanjutan dalam ASP.NET Core Web API
  • Cara bekerja dengan perkhidmatan pekerja di ASP.NET Core
  • Cara menggunakan API Perlindungan Data di ASP.NET Core
  • Cara menggunakan middleware bersyarat dalam ASP.NET Core
  • Cara bekerja dengan keadaan sesi di ASP.NET Core
  • Cara menulis pengawal yang cekap dalam ASP.NET Core