C# Academy · Pelajaran

Mengonfigurasi Asp.Versioning

Siapkan pemberian versi di ASP.NET Core.

Mengonfigurasi Asp.Versioning adalah pelajaran C# Academy gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar C# Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus C# Academy mencakup 4 pelajaran total.

Paket Asp.Versioning

Pembuatan versi API ASP.NET Core tersedia dalam paket Asp.Versioning yang dikelola komunitas (penerus Microsoft.AspNetCore.Mvc.Versioning).

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

AddApiVersioning

Daftarkan pembuatan versi dengan AddApiVersioning. Opsi-opsinya mengatur versi bawaan dan cara menangani versi yang tidak ada.

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

ReportApiVersions

ReportApiVersions = true menambahkan tajuk respons api-supported-versions dan api-deprecated-versions, sehingga klien dapat mengetahui apa yang tersedia.

// Response headers:
// api-supported-versions: 1.0, 2.0
// api-deprecated-versions: 1.0

Memilih Pembaca Versi

ApiVersionReader menentukan dari mana versi dibaca. UrlSegmentApiVersionReader membacanya dari jalur rute.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Menggabungkan Pembaca

Terima versi dari beberapa tempat sekaligus dengan ApiVersionReader.Combine.

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new HeaderApiVersionReader("X-Api-Version"),
    new QueryStringApiVersionReader("api-version"));

Menambahkan Penjelajah API

Rangkai AddApiExplorer agar pembuatan versi terintegrasi dengan OpenAPI. Format teks mengatur tampilan nama grup versi.

builder.Services
    .AddApiVersioning(options => { /* ... */ })
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });

Membuat Versi pada Pengontrol

Beri anotasi pada pengontrol dengan [ApiVersion] dan letakkan penanda versi dalam templat rute.

[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new { version = "1.0" });
}

Versi Kedua

Pengontrol terpisah melayani versi 2 pada templat rute yang sama. Segmen {version:apiVersion} mengarahkan permintaan ke pengontrol yang tepat.

[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() =>
        Ok(new { version = "2.0", extra = true });
}

Beberapa Versi pada Satu Pengontrol

Satu pengontrol dapat melayani beberapa versi dengan memetakan setiap aksi menggunakan [MapToApiVersion].

[ApiVersion(1.0)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
    [HttpGet, MapToApiVersion(1.0)]
    public IActionResult GetV1() => Ok("v1");

    [HttpGet, MapToApiVersion(2.0)]
    public IActionResult GetV2() => Ok("v2");
}

Menandai Versi sebagai Usang

Tandai suatu versi sebagai usang untuk mengumumkan penghentian penggunaannya sambil tetap mempertahankan fungsinya.

[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase { }

Membuat Versi untuk API Minimal

API Minimal menggunakan kumpulan versi yang dibuat dengan NewApiVersionSet, lalu melampirkan versi ke setiap titik akhir.

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

app.MapGet("/api/v{version:apiVersion}/ping", () => "pong")
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(2.0);

Pemeriksaan Singkat

Pastikan kegunaan AddApiExplorer.

Rekapitulasi

Anda mengonfigurasi Asp.Versioning:

AddApiVersioning menetapkan versi bawaan dan pelaporan.
ApiVersionReader.Combine membaca versi dari URL, header, atau kueri.
[ApiVersion] dan {version:apiVersion} merutekan permintaan; [MapToApiVersion] menargetkan aksi.
API Minimal menggunakan kumpulan versi.

Berikutnya: membuat dokumen OpenAPI.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Mengonfigurasi Asp.Versioning” gratis?

Ya — teks lengkap “Mengonfigurasi Asp.Versioning” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus C# Academy, upgrade ke CoddyKit PRO. Kursus C# Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Mengonfigurasi Asp.Versioning”?

Siapkan pemberian versi di ASP.NET Core. Kamu berlatih C# Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai C# Academy?

Tidak diperlukan pengalaman sebelumnya. C# Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Mengonfigurasi Asp.Versioning” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran C# Academy ini?

Ya. Setiap pelajaran C# Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

← Kembali ke C# Academy