نحوه ورژن حداقل API ها در ASP.NET Core 6

این مراحل را برای پیاده سازی نسخه API در حداقل نقاط انتهایی Web API با استفاده از ASP.NET Core 6 دنبال کنید.

ASP.NET Core 6 یک مدل میزبانی ساده را معرفی می کند که به ما امکان می دهد API های سبک وزن با حداقل وابستگی بسازیم. ما شروع با حداقل APIها، استفاده از ورود به سیستم و تزریق وابستگی با حداقل APIها و آزمایش حداقل APIها را در مقاله قبلی اینجا مورد بحث قرار داده ایم. در این مقاله، بررسی خواهیم کرد که چگونه می‌توانیم نسخه‌سازی را برای حداقل نقاط پایانی API خود پیاده‌سازی کنیم.

ما نشان می‌دهیم که چگونه می‌توانیم حداقل APIها را در ASP.NET 6 Core با دنبال کردن این دنباله از شش مرحله نسخه‌سازی کنیم:

1. یک پروژه ASP.NET 6 Core Minimal API در Visual Studio 2022 ایجاد کنید
2. بسته(های) NuGet لازم را نصب کنید
3. پشتیبانی از نسخه API را به پروژه خود اضافه کنید
4. یک مجموعه نسخه ایجاد کنید
5. نقاط پایانی API ایجاد کنید و مجموعه نسخه را مرتبط کنید
6. نقاط پایانی API را در Postman اجرا کنید

برای کار با نمونه کدهای ارائه شده در این مقاله، باید Visual Studio 2022 را در سیستم خود نصب کنید. اگر قبلاً نسخه‌ای ندارید، می‌توانید Visual Studio 2022 را از اینجا بارگیری کنید.

یک پروژه ASP.NET Core 6 مینیمال Web API در Visual Studio 2022 ایجاد کنید

ابتدا، اجازه دهید یک پروژه ASP.NET Core 6 در ویژوال استودیو ایجاد کنیم. با دنبال کردن این مراحل، یک پروژه ASP.NET Core 6 Web API جدید در Visual Studio 2022 ایجاد می شود:

1. Visual Studio 2022 IDE را راه اندازی کنید.
2. روی “ایجاد پروژه جدید” کلیک کنید.
3. در پنجره “ایجاد پروژه جدید”، “ASP.NET Core Web API” را از لیست الگوهای نمایش داده شده انتخاب کنید.
4. بعدی را کلیک کنید.
5. در پنجره “پیکربندی پروژه جدید خود”، نام و مکان پروژه جدید را مشخص کنید.
6. به صورت اختیاری، بسته به تنظیمات برگزیده خود، کادر انتخاب «قرار دادن راه حل و پروژه در یک فهرست راهنمای» را علامت بزنید.
7. بعدی را کلیک کنید.
8. در پنجره «اطلاعات اضافی» که در ادامه نشان داده شده است، علامت کادری را که می‌گوید «استفاده از کنترل‌کننده‌ها…» را بردارید، زیرا در این مثال از حداقل API استفاده خواهیم کرد. “نوع احراز هویت” را به عنوان “هیچ” (پیش‌فرض) بگذارید.
9. مطمئن شوید که چک باکس‌های «Enable Docker»، «Configure for HTTPS» و «Enable Open API Support» علامت نخورده باشند زیرا ما در اینجا از هیچ یک از این ویژگی‌ها استفاده نخواهیم کرد.
10. روی ایجاد کلیک کنید.

ما از این پروژه ASP.NET Core 6 Web API برای ایجاد حداقل نقاط پایانی API و پیاده سازی نسخه API در بخش های زیر استفاده خواهیم کرد.

بسته‌های NuGet را در نسخه API نصب کنید

حداقل APIهای ASP.NET Core 6 از نسخه‌سازی با استفاده از هر یک از این سه بسته پشتیبانی می‌کنند:

• Asp.Versioning.Http — برای ارائه پشتیبانی از نسخه‌سازی در حداقل APIها استفاده می‌شود.
• Asp.Versioning.Mvc — برای ارائه پشتیبانی از نسخه‌سازی در برنامه‌های MVC Core استفاده می‌شود.
• Asp.Versioning.Mvc.ApiExplorer — برای ارائه پشتیبانی در پسوندهای اکسپلورر API برای نسخه‌سازی ASP.NET Core API

اگر یک پروژه برنامه کاربردی وب ASP.NET Core 6 را در Visual Studio 2022 با موفقیت ایجاد کرده اید، کاری که باید انجام دهید این است که بسته های NuGet لازم را به پروژه خود اضافه کنید. برای انجام این کار، پروژه را در پنجره Solution Explorer انتخاب کنید، کلیک راست کرده و “Manage NuGet Packages…” را انتخاب کنید. در پنجره NuGet Package Manager، بسته زیر را جستجو کرده و آن را نصب کنید.

Asp.Versioning.Http

به‌طور متناوب، می‌توانید بسته را از طریق کنسول NuGet Package Manager مطابق شکل زیر نصب کنید.

PM> Install-Package Asp.Versioning.Http

پشتیبانی از نسخه API را به مجموعه خدمات در ASP.NET Core 6 اضافه کنید

برای افزودن پشتیبانی از نسخه‌سازی API در مجموعه خدمات برای حداقل API، باید کد زیر را در فایل Program.cs بنویسید:

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

توجه داشته باشید که چگونه نسخه پیش‌فرض API مشخص شده است. ویژگی ApiVersionReader برای تعیین کلیدی که توسط کلاینت برای ارسال نسخه API هنگام فراخوانی نقاط پایانی API استفاده می شود، استفاده می شود. وقتی مقدار خاصیت AssumeDefaultVersionWhenUnspecified درست باشد، اگر کلاینت نسخه API را تعیین نکرده باشد، از نسخه پیش‌فرض API استفاده می‌شود.

توجه داشته باشید که می‌توانید HeaderApiVersionReader و QueryStringApiVersionReader را ترکیب کنید تا مشتریان بتوانند اطلاعات نسخه را به روش‌های مختلف هنگام فراخوانی نقاط پایانی API مشخص کنند.

services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader =
    ApiVersionReader.Combine(
       new HeaderApiVersionReader("Api-Version"),
       new QueryStringApiVersionReader("Query-String-Version"));
});

نسخه های API را با استفاده از نسخه مجموعه ای در ASP.NET Core 6 اضافه کنید

اکنون یک مجموعه نسخه جدید برای API خود با استفاده از کد زیر تعریف کنید.

var versionSet = app.NewApiVersionSet()
                    .HasApiVersion(1.0)
                    .HasApiVersion(2.0)
                    .ReportApiVersions()
                    .Build();

ما از این نسخه در بخش بعدی برای ایجاد نقاط پایانی API خود استفاده خواهیم کرد.

حداقل نقطه پایانی API را در ASP.NET Core 6 ایجاد کنید

ما در اینجا دو نقطه پایانی ایجاد می‌کنیم تا آن را ساده نگه داریم و روی نسخه‌سازی حداقل API‌هایمان تمرکز کنیم. کد زیر را در فایل Program.cs بنویسید تا دو نقطه پایانی ایجاد شود.

app.MapGet("/GetMessage", () => "This is an example of a minimal API").WithApiVersionSet(versionSet).MapToApiVersion(1.0);
app.MapGet("/GetText", () => "This is yet another example of a minimal API").WithApiVersionSet(versionSet).WithApiVersionSet(versionSet)
.IsApiVersionNeutral();

توجه داشته باشید که چگونه مجموعه نسخه‌ای را که در بخش قبلی ایجاد کرده‌ایم مرتبط کرده‌ایم. روش MapToApiVersion یک نقطه پایانی خاص را به یک نسخه خاص نگاشت می کند. روش IsApiVersionNeutral یک نقطه پایانی را به عنوان خنثی برای نسخه‌سازی API علامت‌گذاری می‌کند.

در اینجا کد منبع کامل فایل Program.cs برای مرجع شما آمده است:

using Asp.Versioning;
using Asp.Versioning.Conventions;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});
var app = builder.Build();
var versionSet = app.NewApiVersionSet()
                    .HasApiVersion(1.0)
                    .HasApiVersion(2.0)
                    .ReportApiVersions()
                    .Build();
// Configure the HTTP request pipeline.
app.MapGet("/GetMessage", () => "This is an example of a minimal API").WithApiVersionSet(versionSet).HasApiVersion(new ApiVersion(2, 0));
app.MapGet("/GetText", () => "This is another example of a minimal API").WithApiVersionSet(versionSet).IsApiVersionNeutral();
app.Run();

حداقل نقاط پایانی API را اجرا کنید

اکنون کلید F5 را در Visual Studio 2022 IDE فشار دهید تا برنامه اجرا شود. تصویر زیر (شکل ۱) خطایی را نشان می دهد که اگر نقطه پایانی /getmessage را بدون تعیین کلید نسخه API در هدر درخواست فراخوانی کنید، با آن مواجه خواهید شد.

شکل ۱. نقطه پایانی /getmessage یک خطا ایجاد می کند زیرا هیچ نسخه API مشخص نشده است.

تصویر صفحه بعدی (شکل ۲) نشان می دهد که وقتی کلید نسخه API را در سرصفحه درخواست مشخص می کنید و دوباره نقطه پایانی /getmessage را فرا می خوانید، خروجی چگونه به نظر می رسد.

شکل ۲. نقطه پایانی /getmessage با موفقیت اجرا می شود زیرا کلید نسخه API در سرصفحه درخواست مشخص شده است.

از آنجایی که نقطه پایانی /gettext به‌عنوان نسخه خنثی API علامت‌گذاری شده است، لازم نیست هنگام فراخوانی این نقطه پایانی، نسخه API را مشخص کنید. هنگامی که نقطه پایانی /gettext را اجرا می‌کنید، پاسخ به شکلی خواهد بود که در تصویر (شکل ۳) زیر نشان داده شده است.

شکل ۳. روش /gettext بدون نیاز به تعیین یک نسخه API در هدر درخواست اجرا می‌شود.

این یک پیاده سازی حداقلی است، ما از یک زمینه داده، پایگاه داده، کلاس مخزن یا حتی هیچ کلاس مدلی استفاده نکرده ایم. ما فقط دو نقطه پایانی API ساده تعریف کرده‌ایم تا نشان دهیم چگونه می‌توانیم حداقل APIها را در ASP.NET Core 6 نسخه کنیم.