فکر کنم شما رفتار پیش فرض ASP.NET Core و ASP.NET رو با NET Core. و NET. اشتباه گرفتید.
اگه من با NET Core. یه برنامه WPF بزنم، رفتاری که میگید رخ می‌ده؟
In the new .NET 8 Preview 3, Microsoft introduced initial support for native Ahead-of-Time (AOT) compilation in the framework's web-dev component, ASP.NET Core.
In this post, let's go through another feature that got introduced to ASP.NET Core in .NET 6 Preview 4. That is Async Streaming.
آیا تا به حال مجبور به نوشتن کدی شبیه قطعه کد زیر شده اید؟
var store = GetStore(); string postCode = null; if (store != null && store.Address != null && store.Address.PostCode != null) postCode = store.Address.PostCode.ToString();
بله! من مطمئن هستم برای شما هم پیش آمده است.
هدف بازیابی و یا محاسبه یک مقدار است، اما برای انجام این کار می‌بایست به چندین شیء میانی دسترسی پیدا کنیم که البته ممکن است در حالت پیش فرض خود قرار داشته باشند و حاوی هیچ مقداری نباشند. بنابراین برای جلوگیری از وقوع NullException ، مجبوریم تمامی اشیائی که در مسیر قرار دارند را بررسی کنیم که null نباشند. مثال بالا کاملا گویا ست. گاهی اوقات حتی ممکن است فراخوانی یک متد، تبدیل نوع با استفاده از as و یا دسترسی به عناصر یک مجموعه وجود داشته باشد. متاسفانه مدیریت تمامی این حالات باعث حجیم شدن کدها و در نتیجه کاهش خوانایی آنها می‌شود. بنابراین باید به دنبال یک راه حل مناسب بود.
استفاده از یک متد الحاقی شرطی (Conditional extensions)
از نظر بسیاری از برنامه نویس‌ها راه حل، استفاده از یک متد الحاقی شرطی است. اگر عبارت "c# deep null check" را گوگل کنید، پیاده سازی‌های متنوعی را پیدا خواهید کرد. اگر چه این متدها نام‌های متفاوتی دارند اما همه آنها از یک ایده کلی مشترک استفاده می‌کنند:
public static TResult IfNotNull<TResult, TSource>(
this TSource source,
Func<TSource, TResult> onNotDefault)
where TSource : class
{
if (onNotDefault == null) throw new ArgumentNullException("onNotDefault");
return source == null ? default(TResult) : onNotDefault(source);
} همانطور که می‌بینید این متد الحاقی مقداری از نوع TResult را بر می‌گرداند. اگر source که در اینجا با توجه به الحاقی بودن متد به معنای شی جاری است، null باشد مقدار پیش فرض نوع خروجی(TResult) بازگردانده می‌شود و در غیر این صورت دیلیگیت onNotDefault فراخوانی می‌گردد.
بعد از افزودن متد الحاقی IfNotNull به پروژه میتوانیم مثال ابتدای مطلب را به صورت زیر بنویسیم :
var postCode = GetStore() .IfNotNull(x => x.Address) .IfNotNull(x => x.PostCode) .IfNotNull(x => x.ToString());
این روش مزایای بسیاری دارد اما در موارد پیچیده دچار مشکل می‌شویم. برای مثال در نظر بگیرید قصد داریم در طول مسیر، متدی را فراخوانی کنیم و مقدار بازگشتی را در یک متغیر موقتی ذخیره کنیم و بر اساس آن ادامه مسیر را طی کنیم. متاسفانه این کار‌ها هم اکنون امکان پذیر نیست. پس به نظر می‌رسد باید کمی متد الحاقی IfNotNull را بهبود ببخشیم.
برای بهبود عملکرد متد الحاقی IfNotNull علاوه بر موارد ذکر شده حداقل دو مورد به نظر من می‌رسد:
- این متد فقط با انواع ارجاعی (reference types) کار میکند و می‌بایست برای کار با انواع مقداری (value types) اصلاح شود.
- با انواع داده ای مثل string چه باید کرد؟ در مورد این نوع داده‌ها تنها مطمئن شدن از null نبودن کافی نیست. برای مثال در مورد string ، گاهی اوقات ما می‌خواهیم از خالی نبودن آن نیز مطمئن شویم. و یا در مورد collectionها تنها null نبودن کافی نیست بلکه زمانی که نیاز به محاسبه مجموع و یا یافتن بزرگترین عضو است، باید از خالی نبودن مجموعه و وجود حداقل یک عضو در آن مطمئن باشیم.
برای حل این مشکلات میتوانیم متد الحاقی IfNotNull را به متد الحاقی IfNotDefault تبدیل کنیم:
public static TResult IfNotDefault<TResult, TSource>(
this TSource source,
Func<TSource, TResult> onNotDefault,
Predicate<TSource> isNotDefault = null)
{
if (onNotDefault == null) throw new ArgumentNullException("onNotDefault");
var isDefault = isNotDefault == null
? EqualityComparer<TSource>.Default.Equals(source, default(TSource))
: !isNotDefault(source);
return isDefault ? default(TResult) : onNotDefault(source);
} تعریف این متد خیلی با تعریف متد قبلی متفاوت نیست. به منظور پشتیبانی از struct ها، قید where TSource : class حذف شده است. بنابراین دیگر نمی‌توان از مقایسه‌ی ساده null با استفاده از عملگر == استفاده کرد چراکه structها nullable نیستند. پس مجبوریم از EqualityComparer<TSource>.Default بخواهیم که این کار را انجام دهد. متد الحاقی IfNotDefault همچنین شامل یک predicate اختیاری با نام isNotDefault است. در صورتی که مقایسه پیش فرض کافی نبود میتوان از این predicate استفاده کرد.
در انتها اجازه بدهید چند مثال کاربردی را مرور کنیم:
1- انجام یک سری اعمال بر روی string در صورتی که رشته خالی نباشد:
return person . IfNotDefault(x => x.Name) . IfNotDefault(SomeOperation, x => !string.IsNullOrEmpty(x));
محاسبه‌ی مقدار میانگین. متد الحاقی IfNotDefault به زیبایی در یک زنجیره‌ی LINQ کار میکند:
var avg = students .Where(IsNotAGraduate) .FirstOrDefault() .IfNotDefault(s => s.Grades) .IfNotDefault(g => g.Average(), g => g != null && g.Length > 0);
برای مطالعه بیشتر
Get rid of deep null checks
Chained null checks and the Maybe monad
Maybe or IfNotNull using lambdas for deep expressions
Dynamically Check Nested Values for IsNull Values
راه‌کاری وجود ندارد؛ از این جهت که پوشه‌ی توسعه‌ی برنامه‌های ASP.NET Core به همراه تمام فایل‌های لازم برای ارائه‌ی توسط IIS نیست. به همین جهت publish آن ضروری است. ضمن اینکه همانطور که در متن توضیح داده شد، برنامه‌های ASP.NET Core اصلا وابستگی به IIS ندارند و در پروسه‌ی IIS اجرا نمی‌شوند. این برنامه‌ها در پروسه‌ی کنسول مجزایی که توسط Kestrel web server ارائه می‌شود، توسط IIS در معرض دید عموم قرار می‌گیرند. بنابراین اگر قصد توزیع محلی آن‌را دارید، فرمان dotnet run را در ریشه‌ی پروژه اجرا کنید تا برنامه بر روی پورت 5000 در اختیار عموم قرار گیرد. یا dotnet watch run را اجرا کنید تا اگر در همان لحظه تغییری را اعمال کردید، به صورت خودکار برنامه مجددا کامپایل و ارائه شود. البته این مورد نیاز به تنظیمات Microsoft.DotNet.Watcher.Tools را در فایل csproj برنامه دارد. این روش (استفاده از NET Core CLI.) برای آزمایش این نوع برنامه‌ها، روش پیش‌فرض هست.
Moq makes testing this piece of code a breeze. Without it, I would have had to write a whole lot of essentially throwaway code just to test this three line controller action. Probably one or two orders of magnitude more code. Clearly, this tool which I relied on heavily prior to .NET Core, remains quite a powerful weapon in my arsenal in .NET Core.
These are the customer-reported issues addressed in 15.7.2:
- With 15.7, users installing an extension on the command line with a nested extension may see an error installing. This has been addressed in the 15.7.2 servicing release.
- Anaconda fails to uninstall during upgrade and issues warning (Error 87).
- The SSDT 15.6.0 Installer configuration registry key could not be opened..
- Editor performance Issues when editing JavaScript.
- The Code Coverage functionality in Visual Studio 2017 ignores async methods.
- Missing
atls.libinarm/arm64after update. - Test Explorer no longer greys out the previously run unit tests.
- Version 15.7.1 debugs .aspx App in a new Chrome instance even if JavaScript debugging is disabled.
- 15.7 compiler fails with Folly.
- ASP project keeps running after closing the web page.
- Chrome Debugger not working and shows an error message, however, the debugger buttons stay active. .
- Rename Python from Rename on the Refactor menu no longer works.
- Visual Studio Installer doesn't work correctly in low disk space conditions.
- Debugger links to browser when previously not set.
- Problems with template argument deduction for class templates.
- C++ constexpr string_view == fails to compile.
- A regression in Type Providers which use native resources (e.g., FSharp.Data.TypeProviders) has been fixed.
- You can now add files to F# ASP.NET Core projects from the UI.
- Listening to Microsoft-Extensions-Logging causes VS diagnostic events window to disconnect with an error message has been fixed in Service Fabric Tools.
در بخش اول آشنایی با Feature Toggle، با مفهوم Feature Toggle آشنا شدیم و در بخش پایانی مقاله، به معرفی یکی از کتابخانه‌های نوشته شده توسط مایکروسافت پرداختیم.
فرض کنید یک قابلیت را تحت عنوان Chat پیاده سازی کرده و با توجه به تکنولوژی‌هایی که استفاده کرده‌اید، فقط با مرورگر کروم سازگار هست و شما باید این قابلیت را فقط برای کاربرانی که مروگر کروم دارند، فعال نمایید؛ در غیر اینصورت غیرفعال و در دسترس کاربران نباشد. برای این منظور فرض میکنیم کنترلر زیر مسئول تمام کارهای مربوط به قابلیت چت می‌باشد :
همانطور که در کد بالا قابل مشاهده می‌باشد ، کنترلر با یک Attribute مزین شده‌است که از Attributeهای توکار کتابخانه می‌باشد. با استفاده از این ویژگی میتوانیم یک کنترلر و یا اکشن متد را کلا از دسترس خارج کنیم (اگر مقدار این قابلیت در appsetting.json غیرفعال باشد).
برای حالتیکه نیاز هست اسم چندین قابلیت را به FeatureGate بدهیم، میتوانیم تعیین کنیم که آیا همه‌ی قابلیت‌ها باید فعال باشند تا کنترلر/ اکشن در دسترس باشد یا خیر؟ برای این منظور یک Enum توکار، به اسم RequirementType به همراه این کتابخانه وجود دارد که کار آن And/OR است:
همانطور که از توضیحات آن قابل تشخیص است، در زمان استفاده از FeatureGate میتوانیم با استفاده از این enum مشخص کنیم که اگر فقط یکی از قابلیت‌ها فعال بود، کنترلر/اکشن موردنظر فعال و در دسترس باشد، در غیر اینصورت از دسترس خارج شود و تمامی درخواست‌ها را با خطای 404 پاسخ دهد.
لازم به ذکر هست اینجا هم میتوان با مقداردهی خصویت requirement با یکی از مقدارهای Any و یا All، مشخص نماییم به صورت And اجرا شود یا خیر.
و سپس نیاز هست تا این هندلر را به صورت زیر ثبت نماییم :
در این مقاله به صورت کاربردی‌تر به استفاده از کتابخانه‌ی مورد استفاده می‌پردازیم. برای ادامه نیاز هست بسته‌ی زیر را که مخصوص برنامه‌های مبتنی بر ASP.NET CORE است نصب نمایید :
Install-package Microsoft.FeatureManagement.AspNetCore
[FeatureGate("chat")]
public class ChatController : Controller
{
public IActionResult Index()
{
// do sth
}
} اگر درخواستی به کنترلر Chat ارسال شود و قابلیت چت در فایل appsetting.json غیرفعال باشد (طبق روش‌هایی که در مقاله قبل توضیح داده شد) کاربر با خطای 404 مواجه خواهد شد.
میتوان به FeatuteGate اسم چندین قابلیت را داد و اگر همه‌ی آنها فعال باشند، کنترلر/اکشن در دسترس خواهد بود؛ در غیر اینصورت خطای 404 دریافت می‌شود.
[FeatureGate("feature1", "feature2")]
public class ChatController : Controller
{
public IActionResult Index()
{
// do sth
}
} "FeatureManagement": {
"feature1": true,
"feature2": false
}, public enum RequirementType
{
//
// Summary:
// The enabled state will be attained if any feature in the set is enabled.
Any = 0,
//
// Summary:
// The enabled state will be attained if all features in the set are enabled.
All = 1
} نمونه‌ای از استفاده از این enum به صورت زیر است:
[FeatureGate(RequirementType.Any,"feature1", "feature2","feature3")]
public class ChatController : Controller
{
public IActionResult Index()
{
// do sth
}
} تگ <feature>
تا اینجا موفق شدیم یک کنترلر و یا اکشن متد را غیرفعال و از دسترس خارج نماییم. فرض کنید قابلیت چت بنا بر تنظیمات انجام شده، غیرفعال می‌باشد، منتها در منوی سایت همچنان لینک آن در حال نمایش است و کاربران میتوانند لینک را کیک کنند (و در نتیجه با خطای 404 مواجه می‌شوند). برای غیر فعال کردن المان‌هایی (تگ) مربوط به یک قابلیت، میتوانیم از tag helper مربوطه به صورت زیر استفاده نماییم :
@addTagHelper *, Microsoft.FeatureManagement.AspNetCore // put this line in _ViewImports
<feature name="feature1,feature2,feature3">
<li>
<a asp-area="" asp-controller="Chat" asp-action="index">Stay in contact</a>
</li>
</feature> نوشتن Handler سفارشی
همانطور که در بالا هم بیان شد، اگر یک قابلیت به هر دلیلی غیرفعال باشد، کاربران با خطای 404 مواجه خواهند شد. اگر نیاز داشتید کاربر را به صفحه‌ی دیگری هدایت کنید و یا Status Code بهتری را برگردانید، میتوانید اینکار را با پیاده سازی یک هندلر سفارشی که اینترفیس IDisabledFeaturesHandler را پیاده سازی میکند، انجام دهید. در زیر یک نمونه پیاده سازی شده را مشاهده می‌کنید:
public class RedirectDisabledFeatureHandler : IDisabledFeaturesHandler
{
public Task HandleDisabledFeatures(IEnumerable<string> features, ActionExecutingContext context)
{
context.Result = new RedirectResult("url");
return Task.CompletedTask;
}
} public void ConfigureServices(IServiceCollection services)
{
services.AddFeatureManagement().UseDisabledFeaturesHandler(new RedirectDisabledFeatureHandler()); ;
}
مطالب
مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger - قسمت چهارم - تکمیل مستندات نوع‌های خروجی API
Swashbuckle.AspNetCore چگونه اطلاعات خود را فراهم میکند؟
در برنامه‌های ASP.NET Core، اطلاعات OpenAPI بر اساس سرویس توکاری به نام ApiExplorer تولید می‌شود که کار آن فراهم آوردن متادیتای مرتبط با یک برنامه‌ی وب است. برای مثال توسط این سرویس میتوان به لیست کنترلرها، متدها و پارامترهای آنها دسترسی یافت. Swashbuckle.AspNetCore به کمک ApiExplorer کار تولید OpenAPI Specification را انجام می‌دهد. برای فعالسازی این سرویس نیازی نیست کار خاصی انجام شود و زمانیکه ()services.AddMvc را فراخوانی میکنیم، ثبت و معرفی این سرویس نیز جزئی از آن است.
اهمیت تولید Response Types صحیح
در قسمت‌های قبل مشاهده کردیم که اگر متدی برای مثال در قسمتی از آن return NotFound یا 404 را داشته باشد، این نوع از خروجی، در OpenAPI Specification تولیدی لحاظ نمی‌شود و ناقص است و یا حتی ممکن است Response Type پیش‌فرض تولیدی که 200 است، ارتباطی به هیچکدام از نوع‌های خروجی یک اکشن متد نداشته باشد و نیاز به اصلاح آن است. این مورد برای تکمیل مستندات یک API ضروری است و استفاده کنندگان از یک API باید بدانند چون نوع خروجی‌هایی را ممکن است در شرایط مختلف، دریافت کنند.
روش تغییر و اصلاح Response Type پیش‌فرض OpenAPI Specification
اکشن متد GetBook کنترلر کتاب‌ها، دارای دو نوع return Ok و return NotFound است؛ اما OpenAPI Specification تولیدی پیش‌فرض، تنها حالت return Ok یا 200 را مستند میکند. برای تکمیل مستندات این اکشن متد، میتوان به صورت زیر عمل کرد:
در اینجا با استفاده از ویژگی ProducesResponseType، میتوان StatusCodes بازگشتی از متد را به صورت صریحی مشخص کرد. وجود این متادیتاها سبب خواهد شد تاOpenAPI Specification تولیدی، به نحو صحیحی حالت 404 را نیز لحاظ کند.
در اینجا StatusCodes.Status400BadRequest را نیز مشاهده می‌کنید. هرچند حالت return BadRequest در کدهای این اکشن متد وجود خارجی ندارد، اما در صورت بروز مشکلی در فراخوانی و یا پردازش آن، به صورت خودکار توسط فریم‌ورک بازگشت داده می‌شود. بنابراین مستندسازی آن نیز ضروری است.
برای آزمایش آن، برنامه را اجرا کنید. در قسمت مستندات متد فوق، اکنون سه حالت 404، 400 و 200 قابل مشاهده هستند. برای نمونه بر روی دکمه‌ی try it out آن کلیک کرده و زمانیکه authorId و bookId را درخواست میکند، دو Guid اتفاقی و کاملا بی‌ربط را وارد کنید. همچنین Controls Accept header را نیز بر روی application/json قرار دهید. سپس بر روی دکمه‌ی execute در ذیل آن کلیک نمائید. یک چنین خروجی 404 کاملی را مشاهده خواهید کرد:
در این تصویر، response body بر اساس rfc 7807 تولید می‌شود و استاندارد گزارش مشکلات یک API است. این مورد اکنون به صورت یک اسکیمای جدید در انتهای مستندات تولیدی نیز قابل مشاهده‌است:
بهبود مستندات تشخیص نوع‌های مدل‌های خروجی اکشن متدها
مورد دیگری که در اینجا جالب توجه است، تشخیص نوع خروجی، در حالت return Ok است:
در اینجا اگر بر روی لینک Schema، بجای Example value پیش‌فرض کلیک کنیم، تصویر فوق حاصل می‌شود. تشخیص این نوع، به علت استفاده‌ی از ActionResult از نوع Book، به صورت زیر است که در ASP.NET Core 2.1 برای همین منظور (تکمیل مستندات Swagger) معرفی شده‌است:
بنابراین از ASP.NET Core 2.1 به بعد، بهتر است در APIها خود از IActionResult استفاده نکنید و شروع به کار با <ActionResult<T نمائید تا بتوان مستندات بهتری را تولید کرد. اگر از IActionResult استفاده کنید، دیگر خبری از Example value و Schema تصویر فوق نخواهد بود و از روی متادیتای این اکشن متد نمی‌توان نوع خروجی آن‌را تشخیص داد. البته در این حالت میتوان این مشکل را به صورت زیر نیز حل کرد؛ اما باز هم بهتر است از <ActionResult<T استفاده کنید:
یک نکته: در این تصویر، در قسمت توضیحات حالت 200، عبارت "Returns the requested book" مشاهده می‌شود. اما در حالت‌های دیگر response types تعریف شده، عبارات پیش‌فرض bad request و یا not found نمایش داده شده‌اند. نحوه‌ی بازنویسی این پیش‌فرض‌ها، با تکمیل مستندات XMLای اکشن متد و ذکر response code دلخواه، به صورت زیر است:
استفاده از API Analyzers برای بهبود OpenAPI Specification تولیدی
اکنون این سؤال مطرح می‌شود که پس از این تغییرات، هنوز چه مواردی در OpenAPI Specification تولیدی ما وجود خارجی ندارند و بهتر است اضافه شوند. برای پاسخ به این سؤال، از زمان ارائه‌ی ASP.NET Core 2.2، بسته‌ی جدید Microsoft.AspNetCore.Mvc.Api.Analyzers نیز ارائه شده‌است که کار آن دقیقا بررسی همین نقایص و کمبودها است. بنابراین ابتدا آن‌را به فایل OpenAPISwaggerDoc.Web.csproj اضافه کرده و سپس دستور dotnet restore را صادر میکنیم:
پس از نصب این ابزار جدید که به صورت افزونه‌ای برای کامپایلر #C کار میکند، بلافاصله اخطارهایی توسط کامپایلر ظاهر خواهند شد؛ مانند:
همانطور که ملاحظه می‌کنید، هنوز هم نیاز به تعریف تعدادی ProducesResponseType فراموش شده وجود دارد که آنها را به صورت زیر اضافه خواهیم کرد:
در ابتدا نوع‌های خروجی اکشن متد GetBooks را تکمیل میکنیم که آن نیز دارای return NotFound و همچنین return Ok است. به علاوه در اینجا ویژگی جدید ProducesDefaultResponseType را نیز ملاحظه می‌کنید که یک چنین خروجی را تولید میکند:
کار آن مدیریت تمام حالت‌های دیگری است که هنوز توسط ProducesResponseTypeها تعریف یا پیش‌بینی نشده‌اند. هرچند وجود آن می‌تواند در یک چنین مواردی مفید باشد، اما همواره تعریف صریح نوع‌های خروجی نسبت به استفاده‌ی از یک حالت پیش‌فرض برای تمام آنها، ترجیح داده می‌شود.
ساده سازی کدهای تکراری تعریف ProducesResponseTypeها
مواردی مانند StatusCodes.Status400BadRequest و یا 406 را در حالت عدم قبول درخواست (مثلا با انتخاب یک accept header اشتباه) و یا 500 را در صورت وجود استثنائی در سمت سرور، باید به تمام اکشن متدها نیز اضافه کرد؛ چون میتوانند تحت شرایطی، نوع‌های خروجی معتبری باشند. برای خلاصه سازی این عملیات، یا میتوان این ویژگی‌ها را بجای قراردادن آنها در بالای تعریف امضای اکشن متدها، به بالای تعریف کلاس کنترلر انتقال داد. با اینکار ویژگی که به یک کنترلر اعمال شده باشد به تمام اکشن متدهای آن نیز اعمال خواهد شد و یا حتی برای عدم تعریف این ویژگی‌های تکراری به ازای هر کنترلر موجود، میتوان آنها را به صورت سراسری تعریف کرد:
به این ترتیب یکسری از نوع‌های خروجی که ممکن است توسط خود فریم‌ورک به صورت خودکار بازگشت داده شوند، به صورت سراسری به تمام اکشن متدهای برنامه اعمال می‌شوند و دیگر نیازی به تعریف دستی آنها نخواهد بود.
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-04.zip
در قسمت بعد، روش‌های دیگری را برای تکمیل مستندات خروجی API بررسی میکنیم.
در برنامه‌های ASP.NET Core، اطلاعات OpenAPI بر اساس سرویس توکاری به نام ApiExplorer تولید می‌شود که کار آن فراهم آوردن متادیتای مرتبط با یک برنامه‌ی وب است. برای مثال توسط این سرویس میتوان به لیست کنترلرها، متدها و پارامترهای آنها دسترسی یافت. Swashbuckle.AspNetCore به کمک ApiExplorer کار تولید OpenAPI Specification را انجام می‌دهد. برای فعالسازی این سرویس نیازی نیست کار خاصی انجام شود و زمانیکه ()services.AddMvc را فراخوانی میکنیم، ثبت و معرفی این سرویس نیز جزئی از آن است.
اهمیت تولید Response Types صحیح
در قسمت‌های قبل مشاهده کردیم که اگر متدی برای مثال در قسمتی از آن return NotFound یا 404 را داشته باشد، این نوع از خروجی، در OpenAPI Specification تولیدی لحاظ نمی‌شود و ناقص است و یا حتی ممکن است Response Type پیش‌فرض تولیدی که 200 است، ارتباطی به هیچکدام از نوع‌های خروجی یک اکشن متد نداشته باشد و نیاز به اصلاح آن است. این مورد برای تکمیل مستندات یک API ضروری است و استفاده کنندگان از یک API باید بدانند چون نوع خروجی‌هایی را ممکن است در شرایط مختلف، دریافت کنند.
روش تغییر و اصلاح Response Type پیش‌فرض OpenAPI Specification
اکشن متد GetBook کنترلر کتاب‌ها، دارای دو نوع return Ok و return NotFound است؛ اما OpenAPI Specification تولیدی پیش‌فرض، تنها حالت return Ok یا 200 را مستند میکند. برای تکمیل مستندات این اکشن متد، میتوان به صورت زیر عمل کرد:
/// <summary>
/// Get a book by id for a specific author
/// </summary>
/// <param name="authorId">The id of the book author</param>
/// <param name="bookId">The id of the book</param>
/// <returns>An ActionResult of type Book</returns>
/// <response code="200">Returns the requested book</response>
[HttpGet("{bookId}")]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status200OK)]
public async Task<ActionResult<Book>> GetBook(Guid authorId, Guid bookId) در اینجا StatusCodes.Status400BadRequest را نیز مشاهده می‌کنید. هرچند حالت return BadRequest در کدهای این اکشن متد وجود خارجی ندارد، اما در صورت بروز مشکلی در فراخوانی و یا پردازش آن، به صورت خودکار توسط فریم‌ورک بازگشت داده می‌شود. بنابراین مستندسازی آن نیز ضروری است.
برای آزمایش آن، برنامه را اجرا کنید. در قسمت مستندات متد فوق، اکنون سه حالت 404، 400 و 200 قابل مشاهده هستند. برای نمونه بر روی دکمه‌ی try it out آن کلیک کرده و زمانیکه authorId و bookId را درخواست میکند، دو Guid اتفاقی و کاملا بی‌ربط را وارد کنید. همچنین Controls Accept header را نیز بر روی application/json قرار دهید. سپس بر روی دکمه‌ی execute در ذیل آن کلیک نمائید. یک چنین خروجی 404 کاملی را مشاهده خواهید کرد:
در این تصویر، response body بر اساس rfc 7807 تولید می‌شود و استاندارد گزارش مشکلات یک API است. این مورد اکنون به صورت یک اسکیمای جدید در انتهای مستندات تولیدی نیز قابل مشاهده‌است:
بهبود مستندات تشخیص نوع‌های مدل‌های خروجی اکشن متدها
مورد دیگری که در اینجا جالب توجه است، تشخیص نوع خروجی، در حالت return Ok است:
در اینجا اگر بر روی لینک Schema، بجای Example value پیش‌فرض کلیک کنیم، تصویر فوق حاصل می‌شود. تشخیص این نوع، به علت استفاده‌ی از ActionResult از نوع Book، به صورت زیر است که در ASP.NET Core 2.1 برای همین منظور (تکمیل مستندات Swagger) معرفی شده‌است:
public async Task<ActionResult<Book>> GetBook(Guid authorId, Guid bookId)
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Book))]
یک نکته: در این تصویر، در قسمت توضیحات حالت 200، عبارت "Returns the requested book" مشاهده می‌شود. اما در حالت‌های دیگر response types تعریف شده، عبارات پیش‌فرض bad request و یا not found نمایش داده شده‌اند. نحوه‌ی بازنویسی این پیش‌فرض‌ها، با تکمیل مستندات XMLای اکشن متد و ذکر response code دلخواه، به صورت زیر است:
/// <response code="200">Returns the requested book</response>
استفاده از API Analyzers برای بهبود OpenAPI Specification تولیدی
اکنون این سؤال مطرح می‌شود که پس از این تغییرات، هنوز چه مواردی در OpenAPI Specification تولیدی ما وجود خارجی ندارند و بهتر است اضافه شوند. برای پاسخ به این سؤال، از زمان ارائه‌ی ASP.NET Core 2.2، بسته‌ی جدید Microsoft.AspNetCore.Mvc.Api.Analyzers نیز ارائه شده‌است که کار آن دقیقا بررسی همین نقایص و کمبودها است. بنابراین ابتدا آن‌را به فایل OpenAPISwaggerDoc.Web.csproj اضافه کرده و سپس دستور dotnet restore را صادر میکنیم:
<Project Sdk="Microsoft.NET.Sdk.Web">
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc.Api.Analyzers" Version="2.2.0" />
</ItemGroup> Controllers\BooksController.cs(40,17): warning API1000: Action method returns undeclared status code '404'. Controllers\BooksController.cs(89,13): warning API1000: Action method returns undeclared status code '201'.
/// <summary> /// Get the books for a specific author /// </summary> /// <param name="authorId">The id of the book author</param> /// <returns>An ActionResult of type IEnumerable of Book</returns> [HttpGet()] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status404NotFound)] [ProducesDefaultResponseType] public async Task<ActionResult<IEnumerable<Book>>> GetBooks(Guid authorId)
کار آن مدیریت تمام حالت‌های دیگری است که هنوز توسط ProducesResponseTypeها تعریف یا پیش‌بینی نشده‌اند. هرچند وجود آن می‌تواند در یک چنین مواردی مفید باشد، اما همواره تعریف صریح نوع‌های خروجی نسبت به استفاده‌ی از یک حالت پیش‌فرض برای تمام آنها، ترجیح داده می‌شود.
ساده سازی کدهای تکراری تعریف ProducesResponseTypeها
مواردی مانند StatusCodes.Status400BadRequest و یا 406 را در حالت عدم قبول درخواست (مثلا با انتخاب یک accept header اشتباه) و یا 500 را در صورت وجود استثنائی در سمت سرور، باید به تمام اکشن متدها نیز اضافه کرد؛ چون میتوانند تحت شرایطی، نوع‌های خروجی معتبری باشند. برای خلاصه سازی این عملیات، یا میتوان این ویژگی‌ها را بجای قراردادن آنها در بالای تعریف امضای اکشن متدها، به بالای تعریف کلاس کنترلر انتقال داد. با اینکار ویژگی که به یک کنترلر اعمال شده باشد به تمام اکشن متدهای آن نیز اعمال خواهد شد و یا حتی برای عدم تعریف این ویژگی‌های تکراری به ازای هر کنترلر موجود، میتوان آنها را به صورت سراسری تعریف کرد:
namespace OpenAPISwaggerDoc.Web
{
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(setupAction =>
{
setupAction.Filters.Add(
new ProducesResponseTypeAttribute(StatusCodes.Status400BadRequest));
setupAction.Filters.Add(
new ProducesResponseTypeAttribute(StatusCodes.Status406NotAcceptable));
setupAction.Filters.Add(
new ProducesResponseTypeAttribute(StatusCodes.Status500InternalServerError));
setupAction.Filters.Add(
new ProducesDefaultResponseTypeAttribute());
setupAction.ReturnHttpNotAcceptable = true;
// ... کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-04.zip
در قسمت بعد، روش‌های دیگری را برای تکمیل مستندات خروجی API بررسی میکنیم.
Our beginner's guide to building Web APIs with ASP.NET Core is designed to provide you with the foundation you need to start building Web APIs with .NET in a collection of short, pragmatic collection of videos. Web APIs have become a critical component in almost every type of software we use today. In this introductory video series, we will walk you through the fundamental concepts you need to know to get started with building Web APIs using ASP.NET Core. We will cover topics such as routing, validation, working with data, and much more.
