اولین برنامه تحت وب شما بر روی Mac
افزایش کارایی برنامه های ASP.NET
پروژه C# to JavaScript Compiler
مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger - قسمت سوم - تکمیل مستندات یک API با کامنتها
استفاده از XML Comments برای بهبود کیفیت مستندات API
نوشتن توضیحات XML ای برای متدها و پارامترها در پروژههای داتنتی، روشی استاندارد و شناخته شدهاست. برای نمونه در AuthorsController، میخواهیم توضیحاتی را به اکشن متد GetAuthor آن اضافه کنیم:
/// <summary> /// Get an author by his/her id /// </summary> /// <param name="authorId">The id of the author you want to get</param> /// <returns>An ActionResult of type Author</returns> [HttpGet("{authorId}")] public async Task<ActionResult<Author>> GetAuthor(Guid authorId)
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp2.2</TargetFramework> <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
اکنون نیاز است وجود این فایل را به تنظیمات SwaggerDoc در کلاس Startup برنامه، اعلام کنیم:
namespace OpenAPISwaggerDoc.Web { public class Startup { public void ConfigureServices(IServiceCollection services) { services.AddSwaggerGen(setupAction => { setupAction.SwaggerDoc( // ... ); var xmlCommentsFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlCommentsFullPath = Path.Combine(AppContext.BaseDirectory, xmlCommentsFile); setupAction.IncludeXmlComments(xmlCommentsFullPath); }); }
پس از این تنظیمات اگر برنامه را اجرا کنیم، در Swagger-UI حاصل، این تغییرات قابل مشاهده هستند:
افزودن توضیحات به Response
تا اینجا توضیحات پارامترها و متدها را افزودیم؛ اما response از نوع 200 آن هنوز فاقد توضیحات است:
علت را نیز در تصویر فوق مشاهده میکنید. قسمت responses در OpenAPI specification، اطلاعات خودش را از اسکیمای مدلهای مرتبط دریافت میکند. بنابراین نیاز است کلاس DTO متناظر با Author را به نحو ذیل تکمیل کنیم:
using System; namespace OpenAPISwaggerDoc.Models { /// <summary> /// An author with Id, FirstName and LastName fields /// </summary> public class Author { /// <summary> /// The id of the author /// </summary> public Guid Id { get; set; } /// <summary> /// The first name of the author /// </summary> public string FirstName { get; set; } /// <summary> /// The last name of the author /// </summary> public string LastName { get; set; } } }
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup> </Project>
namespace OpenAPISwaggerDoc.Web { public class Startup { public void ConfigureServices(IServiceCollection services) { services.AddSwaggerGen(setupAction => { setupAction.SwaggerDoc( // ... ); var xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly).ToList(); xmlFiles.ForEach(xmlFile => setupAction.IncludeXmlComments(xmlFile)); }); }
در این حالت اگر مجددا برنامه را اجرا کنیم، خروجی ذیل را در قسمت schemas مشاهده خواهیم کرد:
بهبود مستندات به کمک Data Annotations
اگر به اکشن متد UpdateAuthor در کنترلر نویسندگان دقت کنیم، چنین امضایی را دارد:
[HttpPut("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor(Guid authorId, AuthorForUpdate authorForUpdate)
using System.ComponentModel.DataAnnotations; namespace OpenAPISwaggerDoc.Models { /// <summary> /// An author for update with FirstName and LastName fields /// </summary> public class AuthorForUpdate { /// <summary> /// The first name of the author /// </summary> [Required] [MaxLength(150)] public string FirstName { get; set; } /// <summary> /// The last name of the author /// </summary> [Required] [MaxLength(150)] public string LastName { get; set; } } }
بهبود مستندات متد HttpPatch با ارائهی یک مثال
دو نگارش از اکشن متد UpdateAuthor در این مثال موجود هستند:
یکی HttpPut است
[HttpPut("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor(Guid authorId, AuthorForUpdate authorForUpdate)
[HttpPatch("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor( Guid authorId, JsonPatchDocument<AuthorForUpdate> patchDocument)
بهتر است در این حالت مثالی را به استفاده کنندگان از آن ارائه دهیم تا در حین کار با آن، به مشکل برنخورند:
/// <summary> /// Partially update an author /// </summary> /// <param name="authorId">The id of the author you want to get</param> /// <param name="patchDocument">The set of operations to apply to the author</param> /// <returns>An ActionResult of type Author</returns> /// <remarks> /// Sample request (this request updates the author's first name) \ /// PATCH /authors/id \ /// [ \ /// { \ /// "op": "replace", \ /// "path": "/firstname", \ /// "value": "new first name" \ /// } \ /// ] \ /// </remarks> [HttpPatch("{authorId}")] public async Task<ActionResult<Author>> UpdateAuthor( Guid authorId, JsonPatchDocument<AuthorForUpdate> patchDocument)
روش کنترل warningهای کامنتهای تکمیل نشده
با فعالسازی GenerateDocumentationFile در فایل csproj برنامه، کامپایلر، بلافاصله برای تمام متدها و خواص عمومی که دارای کامنت نیستند، یک warning را صادر میکند. یک روش برطرف کردن این مشکل، افزودن کامنت به تمام قسمتهای برنامه است. روش دیگر آن، تکمیل خواص کامپایلر، جهت مواجه شدن با عدم وجود کامنتها در فایل csproj برنامه است:
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp2.2</TargetFramework> <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel> <GenerateDocumentationFile>true</GenerateDocumentationFile> <TreatWarningsAsErrors>false</TreatWarningsAsErrors> <WarningsAsErrors>NU1605;</WarningsAsErrors> <NoWarn>1701;1702;1591</NoWarn> </PropertyGroup>
- اگر میخواهید خودتان را مجبور به کامنت نویسی کنید، میتوانید نبود کامنتها را تبدیل به error کنید. برای این منظور خاصیت TreatWarningsAsErrors را به true تنظیم کنید. در این حالت هر کامنت نوشته نشده، به صورت یک error توسط کامپایلر گوشزد شده و برنامه کامپایل نخواهد شد.
- اگر TreatWarningsAsErrors را خاموش کردید، هنوز هم میتوانید یکسری از warningهای انتخابی را تبدیل به error کنید. برای مثال NU1605 ذکر شدهی در خاصیت WarningsAsErrors، مربوط به package downgrade detection warning است.
- اگر به warning نبود کامنتها دقت کنیم به صورت عبارات warning CS1591: Missing XML comment for publicly visible type or member شروع میشود. یعنی CS1591 مربوط به کامنتهای نوشته نشدهاست. میتوان برای صرفنظر کردن از آن، شمارهی این خطا را بدون CS، توسط خاصیت NoWarn ذکر کرد.
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید: OpenAPISwaggerDoc-03.zip
در قسمت بعد، مشکل خروجی تولید response از نوع 200 را که در قسمت دوم به آن اشاره کردیم، بررسی خواهیم کرد.
متن زیر یک سری نکات و یا شاید توهماتی را مطرح میکند که در مورد رویههای ذخیره شده در اس کیوال سرور رایج هستند.
1- رویههای ذخیره شده در مقابل SQL Injection مقاوم هستند. کوئریهای Ad hoc همیشه این آسیب پذیری را به همراه دارند.
نادرست است! رویههای ذخیره شدهای که رشتهها را به صورت پارامتر دریافت کرده و آنها را به صورت یک عبارت sql اجرا میکنند، آسیب پذیر هستند. اگر هنگام استفاده از کوئریهای Ad hoc از پارامترها استفاده شود، در برابر حملات SQL Injection مصون خواهید بود.
2- execution plan رویههای ذخیره شده کش میشوند اما این Plan برای کوئریهای Ad hoc هر بار محاسبه و تولید میگردد.
نادرست است! اس کیوال سرور تا این اندازه بی هوش نیست! اگر execution plan ایی موجود باشد حتما استفاده خواهد شد و برای موتور اس کیوال سرور اصلا اهمیتی ندارد که کوئری در حال اجرا از یک رویه ذخیره شده صادر شده است یا از یک کوئری Ad hoc . رویههای ذخیره شده پیش کامپایل شده نیستند و مانند تمامی کوئریهای دیگر در زمان اجرا کامپایل میشوند.
3- زمانیکه از رویه ذخیره شده استفاده میکنید همه چیز را در یک مکان به صورت متمرکز و مجتمع خواهید داشت (مدیریت بهتر)
نادرست است! در یک مکان متمرکز در اختیار شما نیستند. برنامه جای خود را دارد و رویههای ذخیره شده در دیتابیس در جای دیگری قرار دارند و برای مثال اگر قرار باشد یک پارامتر را به رویه ذخیره شده خود اضافه کنید، کدهای شما نیز باید تغییر کنند.
4- میتوان از یک رویه ذخیره شده استفاده مجدد کرد (در نقاط مختلف یک کد) و اعمال تغییرات تنها در یک مکان (دیتابیس) باید صورت گیرد.
هر چند این مورد درست است، اما باید دقت داشت که اگر چندین برنامه از این رویه ذخیره شده استفاده میکنند نباید تغییرات شما باعث از کار افتادن سایر برنامهها شوند.
5- میتوان رویه ذخیره شده را بدون نیاز به توزیع مجدد برنامه تغییر داد.
این مورد تا حدودی صحیح است. اگر تنها بحث بهینه سازی و امثال آن مطرح باشد صحیح است اما اگر واقعا نیاز به تغییر یک کوئری در رویه ذخیره شده وجود داشته باشد به احتمال زیاد برنامه نیز باید دستخوش تغییراتی گردد تا این دو با هم هماهنگ شوند.
نظر شما چیست؟
C# 6 - The nameof Operator
عملگر nameof در C# 11، اندکی بهبود یافتهاست و اینبار میتواند در ویژگیها (attributes) نیز به نام پارامترهای متدها، دسترسی پیدا کند. چند مثال:
الف) امکان دسترسی به نام پارامتر متد، در حالت اعمال به متد
[MyAttr(nameof(parameter))] void Method(string parameter) { }
ب) امکان دسترسی به نام نوع پارامتر جنریک متد، در حالت اعمال به متد
[MyAttr(nameof(T))] void Method<T>() { }
ج) امکان دسترسی به نام پارامتر متد، در حالت اعمال به پارامتر
void Method([MyAttr(nameof(parameter))] int parameter) { }
یکی از کاربردهای آن، بهبود تعاریف متادیتای nullable reference types و عدم نیاز به کار با رشتهها به صورت مستقیم است:
[return: NotNullIfNotNull(nameof(path))] public static string? GetUrl(string? path) => !string.IsNullOrEmpty(path) ? $"https://localhost/api/{path}" : null;
سری آموزش Vue.js از مایکروسافت
کتابخانه jquery-sortable-lists
Sortabl elists also contains an export functions toArray, toHierarchy, toString.
using System.Collections.Generic;
using BLL = DotNetTipsBLLLayer;//نام مستعار برای فضای نام using EmployeeDomain = DotNetTipsBLLLayer.Employee;//نام مستعار برای یک نوع داده
using (var sqlConnection = new SqlConnection()) { //کد }
using static System.Console; using static System.Math; namespace dotnettipsUsingStatic { class Program { static void Main(string[] args) { Write(" *** Cal Area *** "); int r = int.Parse(ReadLine()); var result = Pow(r, 2) * PI; Write($"Area is : {result}"); ReadKey(); } } }
enum Gender { Male, Female }
تا قبل از سی شارپ 6 برای استفادهی از نوع داده شمارشی بدین شکل عمل میکردیم:
var gender = Gender.Male;
و اکنون بازنویسی استفادهی ازEnum به کمک ویژگی جدید static using statement :
در قسمت معرفی فضاهای نام بدین شکل عمل میکنیم:
using static dotnettipsUsingStatic.Gender;
و در برنامه کافیست مستقیما نام اعضای Enum را ذکر کنیم .
var gender = Male;//تخصیص نوع داده شمارشی WriteLine($"Employee Gender is : {Male}");//استفاده مستقیم از نوع داده شمارشی
استفاده از ویژگی using static و متدهای الحاقی :
تا قبل از ارائه سی شارپ 6 اگر نیاز به استفادهی از یک متد الحاقی خاص همچون where در فضای نام System.Linq.Enumeable داشتیم میبایستی فضای نام System.Linq را به طور کامل اضافه میکردیم و راهی برای اضافه کردن یک فضای نام خاص درون فضای نام بزرگتر وجود نداشت.
اما با قابلیت جدید اضافه شده میتوانیم بخشی از یک فضای نام را اضافه کنیم:
متدهای استاتیک و متدهای الحاقی در زمان استفاده از ویژگی using static:
فرض کنید کلاس static ای بنام MyStaticClass داشته باشیم که متد Print1 و Print2 در آن تعریف شده باشند:
public static class MyStaticClass { public static void Print1(string parameter) { WriteLine(parameter); } public static void Print2(this string parameter) { WriteLine(parameter); } }
برای استفاده از متدهای تعریف شده به شکل زیر عمل میکنیم :
//فراخوانی تابع استاتیک Print1("Print 1");//روش اول MyStaticClass.Print1("Prtint 1");//روش دوم //فراخوانی متد الحاقی استاتیک MyStaticClass.Print2("Print 2"); "print 2".Print2();
ویژگیهای جدید ارائه شده در سی شارپ 6 برای افزایش خوانایی برنامهها و تمیزتر شدن کدها اضافه شدهاند. در مورد ویژگیهای ارائه شده در مقالهی جاری این نکته مهم است که گاهی قید کردن نام کلاسها خود سبب افزایش خوانایی کدها میشود .