نحوه استفاده از binding پارامتر در حداقل API در ASP.NET Core

از اتصال پارامتر در ASP.NET Core 7 برای تبدیل داده های درخواستی به پارامترهای قوی تایپ شده استفاده کنید و عملکرد برنامه و قابلیت نگهداری کد را بهبود بخشید.

Minimal API نوعی از API در ASP.NET Core است که حداقل فایل‌ها، ویژگی‌ها و وابستگی‌ها را شامل می‌شود. API های حداقل به شما این امکان را می دهند که نقاط پایانی REST کاملاً کاربردی را با حداقل کدگذاری و پیکربندی بسازید. یکی از بسیاری از پیشرفت‌های جدید در ASP.NET Core 7 پشتیبانی آن از اتصال پارامتر در حداقل APIها است.

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

یک پروژه Web API حداقل در Visual Studio 2022 ایجاد کنید

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

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

ما از این پروژه ASP.NET Core Web API برای کار با binding پارامتر در بخش‌های زیر استفاده خواهیم کرد.

پیوند پارامتر چیست؟

پیوند پارامتر شامل نگاشت داده‌های درخواست HTTP ورودی به پارامترهای روش عمل است، و به توسعه‌دهندگان اجازه می‌دهد تا درخواست‌ها را پردازش کنند و به روشی ساختاریافته و کارآمد پاسخ دهند.

Parameter binding فرآیند رسیدگی به درخواست‌های HTTP را ساده می‌کند و به توسعه‌دهندگان اجازه می‌دهد تا روی ایجاد منطق نقاط پایانی API خود تمرکز کنند. API های حداقل در ASP.NET Core 7 انواع مختلفی از اتصال پارامترها از جمله FromQuery، FromRoute، FromHeader و FromBody را ارائه می دهند.

چرا از binding پارامتر استفاده کنیم؟

در اینجا چند دلیل وجود دارد که چرا باید از binding پارامتر در حداقل APIها استفاده کنید.

• برای ساده‌سازی کد: با استفاده از اتصال پارامتر، توسعه‌دهندگان می‌توانند کد دیگ بخار مورد نیاز برای رسیدگی به درخواست‌های HTTP ورودی را کاهش دهند. به جای تجزیه دستی پارامترهای رشته جستجو، داده‌های مسیر و بدنه‌های درخواست، اتصال پارامتر به توسعه‌دهندگان اجازه می‌دهد تا پارامترهای روش عمل را تعریف کنند و چارچوب فرآیند اتصال را به‌طور خودکار مدیریت کند.
• برای بهبود قابلیت نگهداری کد: با استفاده از اتصال پارامترها در حداقل API، توسعه‌دهندگان می‌توانند کد قابل نگهداری بیشتری ایجاد کنند که درک و اصلاح آن در طول زمان آسان‌تر باشد. فرآیند اتصال استاندارد و قابل پیش‌بینی است، و توسعه‌دهندگان را آسان‌تر می‌کند که چگونه داده‌ها را بین مشتری و سرور منتقل می‌کنند.
• برای افزایش عملکرد برنامه: اتصال پارامتر همچنین می‌تواند با کاهش پردازش داده‌های غیرضروری در برنامه به بهبود عملکرد کمک کند. به عنوان مثال، با اتصال یک بدنه درخواست به یک نوع پارامتر خاص، چارچوب می‌تواند از سربار تجزیه و جداسازی کل بدنه درخواست جلوگیری کند، در عوض فقط بر روی داده‌های مربوطه مورد نیاز برنامه تمرکز کند.
• برای مدیریت انواع داده‌های پیچیده: از پیوند پارامتر می‌توان برای مدیریت انواع داده‌های پیچیده مانند اشیاء تودرتو، آرایه‌ها و مجموعه‌ها استفاده کرد. با استفاده از مکانیسم‌های داخلی برای اتصال انواع داده‌های پیچیده، توسعه‌دهندگان می‌توانند APIهایی ایجاد کنند که طیف وسیعی از قالب‌های داده را بدون نیاز به نوشتن کد اضافی نشان می‌دهند.

پیوند پارامتر چگونه کار می کند؟

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

پیوند پارامتر با رشته های پرس و جو

برای استفاده از اتصال پارامتر در حداقل APIها در ASP.NET Core 7، توسعه دهندگان باید متدهای عملی را تعریف کنند که پارامترها را بپذیرند. به عنوان مثال، قطعه کد زیر یک نقطه پایانی API حداقلی را تعریف می کند که پارامتری را از رشته پرس و جو می پذیرد.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", ([FromQuery] string name) =>
{
   return $"Hello {name}";
});
app.Run();

در این مثال، ویژگی [FromQuery] به چارچوب می‌گوید که پارامتر نام را به مقدار پارامتر رشته query name در درخواست HTTP متصل کند.

پیوند پارامتر با تزریق وابستگی

با ASP.NET Core 7، می‌توانید از مزایای تزریق وابستگی برای اتصال پارامترها در روش‌های عمل کنترل‌کننده‌های API خود استفاده کنید. اگر نوع به عنوان یک سرویس پیکربندی شده است، دیگر نیازی به افزودن ویژگی [FromServices] به پارامترهای روش خود ندارید. قطعه کد زیر را در نظر بگیرید.

[Route("[controller]")]
[ApiController]
public class MyDemoController : ControllerBase
{
    public ActionResult Get(IDateTime dateTime) => Ok(dateTime.Now);
}

اگر نوع به عنوان یک سرویس پیکربندی شده است، نیازی به استفاده از ویژگی [FromServices] برای اتصال پارامترها ندارید. در عوض، می‌توانید از کد زیر برای اتصال پارامترها با استفاده از تزریق وابستگی استفاده کنید.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IDateTime, SystemDateTime>();
var app = builder.Build();
app.MapGet("/",   (IDateTime dateTime) => dateTime.Now);
app.MapGet("/demo", ([FromServices] IDateTime dateTime) => dateTime.Now);
app.Run();

پیوند پارامتر صریح در حداقل APIها

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

این در شرایطی مفید است که رفتار الزام آور را نمی توان به تنهایی از نام یا نوع پارامتر استنباط کرد. در ASP.NET Core 7 حداقل API، توسعه دهندگان می توانند از ویژگی های زیر برای تعیین صریح منبع داده برای یک پارامتر استفاده کنند:

• [FromQuery] مشخص می‌کند که مقدار پارامتر باید از رشته جستجوی HTTP مشتق شود.
• [FromRoute] مشخص می‌کند که مقدار پارامتر باید از داده‌های مسیر درخواست HTTP مشتق شود.
• [FromHeader] مشخص می‌کند که مقدار پارامتر باید از سرصفحه درخواست HTTP گرفته شود.
• [FromBody] مشخص می‌کند که مقدار پارامتر باید از بدنه درخواست HTTP باشد.

به عنوان مثال، حداقل نقطه پایانی API زیر را در نظر بگیرید که نمونه‌ای از نوع Author را در بدنه درخواست می‌پذیرد.

app.MapPost("/demo", ([FromBody] Author author) =>
{
  // Write your code here to process the author object
});

در این مورد، ویژگی [FromBody] به فریمورک می‌گوید که پارامتر را به داده‌های بدنه درخواست متصل کند. اگر این ویژگی مشخص نشده باشد، چارچوب سعی می‌کند پارامتر را با استفاده از منابع موجود دیگر، مانند رشته جستجو یا داده‌های مسیر، متصل کند، که احتمالاً آن چیزی نیست که در این سناریو می‌خواهیم.

توجه داشته باشید که می‌توانید از ویژگی [AsParameters] برای نگاشت پارامترهای پرس و جو مستقیماً به یک شی، بدون نیاز به استفاده از روش‌های BindAsync یا TryParse استفاده کنید.

app.MapGet("/display", ([AsParameters] Author author) =>
{
    return $"First Name: {author.FirstName}, Last Name: {author.LastName}";
});

پیوند مدل سفارشی در حداقل APIها

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

در ASP.NET Core 7 Minimal API، اتصال مدل سفارشی با پیاده سازی رابط IModelBinder یا با استفاده از رابط IModelBinderProvider برای ارائه یک پیاده سازی سفارشی از رابط IModelBinder برای یک نوع داده خاص به دست می آید.

برای ایجاد یک کلاسور مدل سفارشی، باید رابط IModelBinder را پیاده سازی کنید و روش BindModelAsync را لغو کنید. این روش یک پارامتر BindingContext را می گیرد که حاوی اطلاعاتی در مورد درخواست و مدلی است که محدود می شود.

در روش BindModelAsync، می‌توانید هرگونه تبدیل داده یا اعتبارسنجی لازم را قبل از برگرداندن مدل محدود انجام دهید. در زیر نمونه‌ای از یک کلاسور مدل سفارشی است که یک بار JSON ورودی را به یک شیء مشتری متصل می‌کند.

public class CustomerModelBinder : IModelBinder
{
    public async Task BindModelAsync(ModelBindingContext bindingContext)
    {
        var json = await new
        StreamReader(bindingContext.HttpContext.Request.Body).
        ReadToEndAsync();
        var customer = JsonConvert.DeserializeObject<Customer>(json);
        bindingContext.Result = ModelBindingResult.Success(customer);
    }
}

در این مثال، کلاس CustomerModelBinder رابط IModelBinder را پیاده سازی می کند و یک پیاده سازی سفارشی از متد BindModelAsync ارائه می دهد. این روش بار JSON را از بدنه درخواست HTTP می خواند و آن را با استفاده از کتابخانه Newtonsoft.Json به یک شی مشتری تبدیل می کند. سپس شیء مشتری به‌عنوان یک ModelBindingResult موفق برگردانده می‌شود.

برای استفاده از این کلاسور مدل سفارشی در یک نقطه پایانی حداقل API، می‌توانید از ویژگی [ModelBinder] در پارامتر استفاده کنید.

app.MapPost("/demo", ([ModelBinder(typeof(CustomerModelBinder))] Customer customer) =>
{
    // Write your code here to process the Customer object
});

در مثال کد قبلی، ویژگی [ModelBinder] مشخص می‌کند که پارامتر Customer باید با استفاده از کلاس CustomerModelBinder محدود شود.

Parameter binding نوشتن کد را برای رسیدگی به درخواست های HTTP ساده می کند. این به توسعه دهندگان اجازه می دهد تا به راحتی انواع داده های پیچیده را مدیریت کنند، در حالی که کد را ساده می کند و قابلیت نگهداری کد را بهبود می بخشد، در حالی که منطق نقاط پایانی API خود را ایجاد می کند. با بهره‌گیری از اتصال پارامترها در حداقل API، توسعه‌دهندگان می‌توانند APIهای کارآمد، قابل نگهداری و مقیاس‌پذیر ایجاد کنند که نیازهای برنامه‌ها و کاربرانشان را برآورده کند.