اشتراک‌ها
ایجاد Pull Requests از طریق VSCode

To create pull requests in VS Code, hover over the GitHub Pull Requests title and click the + sign. Choose the target branch for the pull request, press enter, and relax—you’ve opened your pull request. 

ایجاد Pull Requests از طریق VSCode
اشتراک‌ها
Rider 2017.2 EAP منتشر شد.

It comes with full support for .NET Core 2.0, adds MSTest, various NuGet improvements, a new debugger tool window for visualizing Parallel Stacks and marking of instances, new refactorings and more. And with ReSharper 2017.2 now released, we’ve updated the ReSharper version powering Rider, too. Which brings improved support for C# 7.0, initial support for C# 7.1, new code inspections, navigation improvements, and so on. Let’s look at a few highlights! 

Rider 2017.2 EAP منتشر شد.
نظرات مطالب
بهبود SEO در ASP.NET MVC
یک نکته‌ی تکمیلی در مورد محتوای تکراری
به گزارش‌های گوگل در مورد سایت جاری که نگاه می‌کردم، تمام لینک‌های به صفحات جستجوی سایت را مثلا https://www.dntips.ir/search?term=seo تکراری گزارش کرده بود (تعداد زیادی بودند). چون عنوان قبلی صفحه جستجو، فقط «جستجو» بود (یک عنوان همیشه ثابت). بعد از اینکه عنوان را تبدیل کردم به «جستجو + عبارت وارد شده»، گزارش موارد تکراری آن برطرف شد. 
اشتراک‌ها
تغییرات ASP.NET Core در NET Core 3.0 Preview 4.

Here’s the list of what’s new in this preview:

  • Razor Components renamed back to server-side Blazor
  • Client-side Blazor on WebAssembly now in official preview
  • Resolve components based on @using
  • _Imports.razor
  • New component item template
  • Reconnection to the same server
  • Stateful reconnection after prerendering
  • Render stateful interactive components from Razor pages and views
  • Detect when the app is prerendering
  • Configure the SignalR client for server-side Blazor apps
  • Improved SignalR reconnect features
  • Configure SignalR client for server-side Blazor apps
  • Additional options for MVC service registration
  • Endpoint routing updates
  • New template for gRPC
  • Design-time build for gRPC
  • New Worker SDK 
تغییرات ASP.NET Core در NET Core 3.0 Preview 4.
مطالب
روش استفاده‌ی از jQuery در برنامه‌های AngularJS 2.0
استفاده‌ی گسترده‌ی از jQuery به همراه برنامه‌های AngularJS 2.0 ایده‌ی خوبی نیست؛ زیرا jQuery و کدهای آن، ارتباط تنگاتنگی را بین DOM و JavaScript برقرار می‌کنند که برخلاف رویه‌ی فریم‌ورک‌های MVC است. اما با این حال استفاده‌ی از افزونه‌های بی‌شمار jQuery در برنامه‌های AngularJS 2.0، جهت غنا بخشیدن به ظاهر و همچنین کاربردپذیری برنامه، یکی از استفاده‌های پذیرفته شده‌ی آن است.
روش استفاده‌ی از jQuery نیز در حالت کلی همانند مطلب «استفاده از کتابخانه‌های ثالث جاوا اسکریپتی در برنامه‌های AngularJS 2.0» است؛ اما به همراه چند نکته‌ی اضافه‌تر مانند محل فراخوانی و دسترسی به DOM، در کدهای یک کامپوننت.


هدف: استفاده از کتابخانه‌ی Chosen

می‌خواهیم جهت غنی‌تر کردن ظاهر یک دراپ داون در برنامه‌های AngularJS 2.0، از یک افزونه‌ی بسیار معروف jQuery به نام Chosen استفاده کنیم.


تامین پیشنیازهای اولیه

می‌توان فایل‌های این کتابخانه را مستقیما از GitHub دریافت و به پروژه اضافه کرد. اما بهتر است این‌کار را توسط bower مدیریت کنیم. این کتابخانه هنوز دارای بسته‌ی رسمی npm نیست (و بسته‌ی chosen-npm که در مخزن npm وجود دارد، توسط این تیم ایجاد نشده‌است). اما همانطور که در مستندات آن نیز آمده‌است، توسط دستور ذیل نصب می‌شود:
bower install chosen
برای مدیریت این مساله در ویژوال استودیو، به منوی project و گزینه‌ی add new item مراجعه کرده و bower را جستجو کنید:


در اینجا نام پیش فرض bower.json را پذیرفته و سپس محتوای فایل ایجاد شده را به نحو ذیل تغییر دهید:
{
    "name": "asp-net-mvc5x-angular2x",
    "version": "1.0.0",
    "authors": [
        "DNT"
    ],
    "license": "MIT",
    "ignore": [
        "node_modules",
        "bower_components"
    ],
    "dependencies": {
        "chosen": "1.4.2"
    },
    "devDependencies": {
    }
}
ساختار این فایل هم بسیار شبیه‌است به ساختار package.json مربوط به npm. در اینجا کتابخانه‌ی chosen در قسمت لیست وابستگی‌ها اضافه شده‌است. با ذخیره کردن این فایل، کار دریافت خودکار بسته‌های تعریف شده، آغاز می‌شود و یا کلیک راست بر روی فایل bower.json دارای گزینه‌ی restore packages نیز هست.
پس از دریافت خودکار chosen، بسته‌ی آن‌را در مسیر bower_components\chosen واقع در ریشه‌ی پروژه می‌توانید مشاهده کنید.


استفاده از jQuery و chosen به صورت untyped

ساده‌ترین و متداول‌ترین روش استفاده از jQuery و افزونه‌های آن شامل موارد زیر هستند:
الف) تعریف مداخل مرتبط با آن‌ها در فایل index.html
<script src="~/node_modules/jquery/dist/jquery.min.js"></script>
<script src="~/node_modules/bootstrap/dist/js/bootstrap.min.js"></script>

<script src="~/bower_components/chosen/chosen.jquery.min.js"></script>
<link href="~/bower_components/chosen/chosen.min.css" rel="stylesheet" type="text/css" />
که در اینجا jQuery و بوت استرپ و chosen به همراه فایل css آن اضافه شده‌اند.
ب) تعریف jQuery به صورت untyped
declare var jQuery: any;
همینقدر که این یک سطر را به ابتدای ماژول خود اضافه کنید، امکان دسترسی به تمام امکانات جی‌کوئری را خواهید یافت. البته بدون intellisense و بررسی نوع‌های پارامترها؛ چون نوع آن، any یا همان حالت پیش فرض جاوا اسکریپت تعریف شده‌است.


محل صحیح فراخوانی متدهای مرتبط با jQuery

در تصویر ذیل، چرخه‌ی حیات یک کامپوننت را مشاهده می‌کنید که با تعدادی از آن‌ها پیشتر آشنا شده‌‌ایم:

روش متداول استفاده از jQuery، فراخوانی آن پس از رخداد document ready است. در اینجا معادل این رخداد، hook ویژ‌ه‌ای به نام ngAfterViewInit است. بنابراین تمام فراخوانی‌های jQuery را باید در این متد انجام داد.
همچنین جی‌کوئری نیاز دارد تا بداند هم اکنون قرار است با چه المانی کار کنیم و کامپوننت بارگذاری شده کدام است. برای این منظور، یکی از سرویس‌های توکار AngularJS 2.0 را به نام ElementRef، به سازنده‌ی کلاس تزریق می‌کنیم. توسط خاصیت this._el.nativeElement آن می‌توان به المان ریشه‌ی کامپوننت جاری دسترسی یافت.
constructor(private _el: ElementRef) {
}


تهیه‌ی کامپوننت نمایش یک دراپ داون مزین شده با chosen

در ادامه قصد داریم نکاتی را که تاکنون مرور کردیم، به صورت یک مثال پیاده سازی کنیم. به همین جهت فایل جدید using-jquery-addons.component.ts را به پروژه اضافه کنید به همراه فایل قالب آن به نام using-jquery-addons.component.html؛ با این محتوا:
الف) کامپوننت using-jquery-addons.component.ts
import { Component, ElementRef, AfterViewInit } from "@angular/core";

declare var jQuery: any; // untyped

@Component({
    templateUrl: "app/using-jquery-addons/using-jquery-addons.component.html"
})
export class UsingJQueryAddonsComponent implements AfterViewInit {

    dropDownItems = ["First", "Second", "Third"];
    selectedValue = "Second";

    constructor(private _el: ElementRef) {
    }

    ngAfterViewInit() {
        jQuery(this._el.nativeElement)
            .find("select")
            .chosen()
            .on("change", (e, args) => {
                this.selectedValue = args.selected;
            });
    }
}

ب) قالب using-jquery-addons.component.html
<select>
    <option *ngFor="let item of dropDownItems"
            [value]="item"
            [selected]="item == selectedValue">
        {{item}} option
    </option>
</select>

<h4> {{selectedValue}}</h4>
با این خروجی


توضیحات

کلاس UsingJQueryAddonsComponent، اینترفیس AfterViewInit را پیاده سازی کرده‌است؛ تا توسط متد ngAfterViewInit بتوانیم با عناصر DOM کار کنیم. هرچند در کل اینکار باید صرفا محدود شود به مواردی مانند مثال جاری و در حد آغاز یک افزونه‌ی jQuery و اگر قرار است تغییراتی دیگری صورت گیرند بهتر است از همان روش binding توکار AngularJS 2.0 استفاده کرد.
در سازنده‌ی کلاس، سرویس ElementRef تزریق شده‌است تا توسط خاصیت this._el.nativeElement آن بتوان به المان ریشه‌ی کامپوننت جاری دسترسی یافت. به همین جهت است که پس از آن از متد find، برای یافتن دراپ داون استفاده شده‌است و سپس chosen به نحو متداولی به آن اعمال گردیده‌است.
در اینجا هر زمانیکه یکی از آیتم‌های دراپ داون انتخاب شوند، مقدار آن به خاصیت selectedValue انتساب داده شده و این انتساب سبب فعال سازی binding و نمایش مقدار آن در ذیل دراپ داون می‌گردد.
در قالب این کامپوننت هم با استفاده از ngFor، عناصر دراپ داون از آرایه‌ی dropDownItems تعریف شده در کلاس کامپوننت، تامین می‌شوند. متغیر محلی item تعریف شده‌ی در اینجا، در محدودی همین المان قابل دسترسی است. برای مثال از آن جهت تنظیم دومین آیتم لیست به صورت انتخاب شده، در حین اولین بار نمایش view استفاده شده‌است.


استفاده از jQuery و chosen به صورت typed

کتابخانه‌ی jQuery در مخزن کد https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/jquery دارای فایل d.ts. خاص خود است. برای نصب آن می‌توان از روش ذیل استفاده کرد:
npm install -g typings
typings install jquery --save --ambient
پس از افزودن فایل typings این کتابخانه، در ابتدای فایل main.ts یک سطر ذیل را اضافه کنید:
 /// <reference path="../typings/browser/ambient/jquery/index.d.ts" />
اینکار سبب خواهد شد تا intellisense درون ویژوال استودیو بتواند مداخل متناظر را یافته و راهنمای مناسبی را ارائه دهد.

در ادامه به فایل using-jquery-addons.component.ts مراجعه کرده و تغییر ذیل را اعمال کنید:
// declare var jQuery: any; // untyped
declare var jQuery: JQueryStatic; // typed
فایل d.ts. اضافه شده، امکان استفاده‌ی از نوع جدید JQueryStatic را مهیا می‌کند. پس از آن در کدهای تعریف شده، chosen به رنگ قرمز در می‌آید، چون در تعاریف نوع دار jQuery، این افزونه وجود خارجی ندارد. برای رفع این مشکل، فایل typings/browser/ambient/jquery/index.d.ts را گشوده و سپس به انتهای آن، تعریف chosen را به صورت دستی اضافه کنید:
interface JQuery {
   //...
   chosen(options?:any):JQuery;
}
declare module "jquery" {
   export = $;
}
به این ترتیب این متد به عنوان جزئی از متدهای زنجیروار jQuery، شناسایی شده و قابل استفاده خواهد شد.


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


کدام نگارش‌های NET Core. بر روی سیستم شما نصب هستند؟

پیش از انجام هرکاری نیاز است بررسی کنیم کدامیک از بسته‌های ارائه شده، بر روی سیستم جاری نصب هستند. برای انجام اینکار دستور زیر را در خط فرمان صادر کنید:
 dotnet --info
اگر این دستور کار نکرد و خطایی را دریافت کردید، یعنی NET Core. اصلا بر روی سیستم شما نصب نیست. برنامه dotnet.exe جزئی از runtime نصب شده‌است و به صورت خودکار به path سیستم اضافه می‌شود. به همین جهت است که در صورت نصب آن، فرمان dotnet در هر مسیری قابل اجرا است.
Runtime تنها ویژگی‌های اساسی جهت اجرای برنامه‌های از پیش کامپایل شده‌ی NET Core. را با اجرای فرمانی مانند dotnet mydll.dll و یا اجرای دستور dotnet --info برای دریافت اطلاعاتی از جزئیات این ویژگی‌ها، به همراه دارد. اما برای کار با سورس کدها، build، publish و هر کار دیگری با آن‌ها، حتما باید SDK نیز نصب شود.

خروجی فرمان فوق بر روی سیستم من چنین چیزی است:
 C:\Users\Vahid>dotnet --info
.NET Core SDK (reflecting any global.json):
 Version: 2.1.301
 Commit: 59524873d6

Runtime Environment:
 OS Name:   Windows
 OS Version:  10.0.17134
 OS Platform: Windows
 RID: win10-x64
 Base Path: C:\Program Files\dotnet\sdk\2.1.301\

Host (useful for support):
  Version: 2.1.1
  Commit:  6985b9f684

.NET Core SDKs installed:
  2.1.300 [C:\Program Files\dotnet\sdk]
  2.1.301 [C:\Program Files\dotnet\sdk]

.NET Core runtimes installed:
  Microsoft.NETCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

To install additional .NET Core runtimes or SDKs:
  https://aka.ms/dotnet-download
اولین شماره نگارش نمایش داده شده‌ی در این لیست (2.1.301)، شماره نگارش SDK فعال است. سپس شماره نگارش 2.1.1 به معنای شماره نگارش Runtime فعال بر روی سیستم است که هاست dotnet.exe به شمار می‌رود. سپس لیست SDKها و Runtimeهای نصب شده‌ی بر روی سیستم را نمایش می‌دهد.
باید دقت داشت که بر روی یک سیستم می‌توان چندین SDK و چندین Runtime مختلف را نصب کرد و هر پروژه از شماره نگارش خاصی استفاده کند. شماره نگارش runtime استفاده شده‌ی در پروژه‌ها در فایل csproj، توسط مدخل زیر مشخص می‌شود:
 <TargetFramework>netcoreapp2.1</TargetFramework>
در مورد SDK اینطور نیست و همواره از آخرین SDK نصب شده (همان شماره نگارش SDK فعال فوق) استفاده می‌شود، مگر اینکه فایل ویژه‌ای به نام global.json را در ریشه‌ی اصلی solution قرار دهید؛ با این محتوای فرضی:
 {
  "sdk": {
        "version": "2.1.300-rc.31211"
  }
}
در این حالت پروژه‌ی جاری را وادار می‌کنید بجای استفاده‌ی از آخرین SDK نصب شده‌ی بر روی سیستم، از نگارش SDK خاصی استفاده کند.
البته در اکثر موارد نیازی به انجام این کار نیست؛ چون SDK، با تمام نگارش‌های قبلی سازگار است و همواره استفاده‌ی از آخرین SDK نصب شده توصیه می‌شود. به همین جهت فایل global.json را پس از ایجاد یک solution جدید مشاهده نمی‌کنید؛ مگر اینکه خودتان به دلایل خاصی آن‌را اضافه و مقید نمائید.


تفاوت بسته‌های مختلف قابل دریافت NET Core. در چیست؟

زمانیکه برای دریافت آخرین نگارش NET Core. به سایت آن مراجعه می‌کنیم، به ازای هر نگارش، یک چنین لیستی قابل مشاهده است:
• .NET Core Runtime
• .NET Core SDK
• .NET Core Hosting Bundle
• Visual Studio
• ASP.NET Core Installer
و اکنون سؤالی که مطرح می‌شود این است: کدامیک را باید دریافت کرد؟

Visual Studio

اگر کاربر ویندوز هستید، با نصب آخرین نگارش Visual Studio، می‌توانید به همراه آن، آخرین نگارش SDK ،runtime و اجزای هاست برنامه‌های ASP.NET Core بر روی IIS را نیز بر روی سیستم خود نصب کنید.


NET Core SDK.

هدف از ارائه‌ی بسته‌ی SDK، انجام فرآیندهای build‌، اجرا و مدیریت امور مرتبط با NET Core.، بدون استفاده از Visual Studio و بر روی تمام سیستم عامل‌های پشتیبانی شده‌است. زمانیکه یک بسته‌ی SDK را نصب می‌کنید، به همراه آن این موارد نیز نصب می‌شوند:
• .NET Core SDK 
• .NET Core Runtime 
• ASP.NET Core Runtime
به همین جهت حجم آن از بسته‌ی تکی runtime بیشتر است و با نصب آن دیگر نیازی به دریافت مجزای بسته‌های runtime نیست.

بنابراین دلیل نصب آن می‌تواند شامل یکی از موارد زیر باشد:
 - بر روی سیستمی که در حال توسعه‌ی برنامه‌های مبتنی بر NET Core. هستید. این تمام چیزی است که به آن نیاز دارید.
 - بر روی سروری که نیاز است دستور dotnet را برای انجام فرآیندهای build/publish اجرا کند.


NET Core Runtime.

بسته‌های Runtimes، کوچکترین بسته‌ی ممکن در این لیست هستند و هدف از آن‌ها صرفا اجرای برنامه‌های کامپایل شده‌ی NET Core. در سکوهای کاری مختلف پشتیبانی شده‌ی توسط آن است.
باید دقت داشت که اگر برنامه‌ی شما از «ASP.NET Core meta package» استفاده می‌کند، این بسته در runtime لحاظ نشده‌است و در یک چنین حالتی باید بسته‌ی ASP.NET Core را به صورت جداگانه دریافت و نصب کنید. هرچند اگر از این متاپکیج‌ها استفاده نکنید و بسته‌های مورد نیاز را به صورت مستقیم به برنامه‌ی خود اضافه کنید، این بسته‌ها جزئی از فایل‌های publish نهایی بوده و در این حالت برنامه توسط بسته‌ی runtime نیز قابل اجرا است.
در این حالت برنامه‌ی dotnet بجز اجرای برنامه‌ها و ارائه‌ی اطلاعاتی در مورد خود آن، کارهای دیگری را مانند build و یا publish، نمی‌تواند انجام دهد و برنامه در این حالت باید کاملا از پیش کامپایل شده باشد.

بنابراین دلیل نصب آن می‌تواند شامل یکی از موارد زیر باشد:
- برای اجرای برنامه‌های از پیش کامپایل شده‌ای که به همراه تمام وابستگی‌های مورد نیاز هم هستند.
- برای اجرای برنامه‌های وبی که از ASP.NET Meta packages استفاده نمی‌کنند


ASP.NET Core Installer

همانطور که در توضیحات بسته‌ی runtime عنوان شد، این بسته، متاپکیج‌های ASP.NET Core را به همراه ندارد. اگر به آن‌ها نیاز دارید، باید آن‌ها را به صورت جداگانه توسط ASP.NET Core installer نصب کنید که شامل این موارد است:
- The ASP.NET Runtime Meta Packages
- Microsoft.AspNetCore.App
- Microsoft.AspNetCore.All
 
NET Core Windows Hosting Pack.

نصب این بسته برای هاست برنامه‌های ASP.NET Core در ویندوز و بر روی IIS ضروری است و شامل این اجزا می‌شود:
- 32 bit and 64 .NET Core Runtimes
- ASP.NET Runtime Packages (Microsoft.AspNetCode.App/All)
- IIS Hosting Components
بنابراین این بسته شامل تمام موارد یاد شده‌است منهای قابلیت‌های SDK برای build و publish برنامه‌ها.



بنابراین به صورت خلاصه

برای سرورها این موارد را نصب کنید:
- در ویندوز: Windows Server Hosting Bundle
- برای Mac و لینوکس:  .NET Core Runtime + ASP.NET Core Runtimes

برای سیستم توسعه‌ی شخصی این موارد را نصب کنید:
- SDK
- اگر از ویندوز استفاده می‌کنید: Visual Studio هم به همراه SDK نصب می‌شود.

برای اجرای برنامه‌های از پیش کامپایل شده که به همراه تمام وابستگی‌های مورد نیاز هم هستند:
- تنها Runtime را نصب کنید.
اگر این برنامه‌ی از پیش کامپایل شده از ASP.NET Runtime Meta packages استفاده می‌کند:
- ASP.NET Runtimes را نیز نصب کنید.
اشتراک‌ها
چند زبانگی در برنامه‌های Angular

Simple i18n support for your Angular apps 

 Easy ways to create a translation mechanism for your Angular and Ionic applications that does not rely on third-party libraries.

In this article, I am going to show a quick and easy way to provide a translation (aka i18n) support for your Angular and Ionic applications. 

چند زبانگی در برنامه‌های Angular
اشتراک‌ها
کتابخانه ngx-trend

Simple, elegant spark lines for Angular  Demo

Features

  • Simple. Integrate in seconds.
  • Scalable. Uses SVG for sharp, scalable graphs. Will fill the parent container, or you can provide a fixed size.
  • Beautiful. Built-in gradient support, and customizable smoothing.
  • Animatable. Support for on-mount animations where the trend graph draws from left to right.
  • Tiny. Zero-dependency, gzips to <3kb.
کتابخانه ngx-trend
مطالب
مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger - قسمت اول - معرفی
مستندسازی یک API، مهم است. اگر این API عمومی باشد، نیاز به مستندات ویژه‌ی آن، امری بدیهی است و اگر عمومی نباشد، باز هم باید دارای مستندات باشد؛ از این جهت که سایر توسعه دهنده‌های یک تیم بتوانند به سادگی از آن استفاده کنند و همچنین نیازی نباشد تا یک سؤال مشخص را بارها پاسخ داد. به علاوه عدم وجود مستندات کافی در مورد یک API سبب خواهد شد تا سایر توسعه دهنده‌ها تصور کنند قابلیتی که مدنظرشان است هنوز پیاده سازی نشده‌است و خودشان شروع به توسعه‌ی آن کنند که سبب اتلاف وقت و هزینه خواهد شد. با استفاده از Swagger که «سوواَگِر» تلفظ می‌شود و یا OpenAI می‌توان این مشکل را برطرف کرد که ارائه دهنده‌ی توضیحی استاندارد از API شما می‌باشد. توسط آن می‌توان قابلیت‌های یک API را دریافت و یا نحوه‌ی تعامل با آن‌را از طریق HTTP، بررسی کرد. چون خروجی آن استاندارد است و مبتنی بر JSON و یا YAML می‌باشد، ابزارهایی نیز برای آن تهیه شده‌اند که برای نمونه می‌توانند بر مبنای آن، یک UI را طراحی و ارائه کنند. البته این ابزارهای ثالث صرفا محدود به تولید UI مستندات مبتنی بر OpenAPI نیستند، بلکه امکان تولید کد و یا آزمون‌های واحد نیز توسط آن‌ها وجود دارد.
به OpenAPI Specification عبارت Swagger Specification نیز گفته می‌شود؛ اما OpenAPI عبارتی است که باید ترجیح داده شود.


OpenAPI و Swagger

تا اینجا دریافتیم که استاندارد OpenAPI و یا Swagger، صرفا دو واژه برای انجام کاری مشابه هستند. اما در عمل Swagger تشکیل شده‌است از تعدادی ابزار سورس باز که برفراز استاندارد OpenAPI کار کرده و قابلیت‌هایی را ارائه می‌دهند؛ مانند Swagger Editor (برای تولید استاندارد)، Swagger UI (برای تولید UI مستندات)، Swagger CodeGen (برای تولید کدهای خودکار) و غیره. برای نمونه swagger-ui را می‌توانید در مخزن کد GitHub آن ملاحظه کنید.
البته این ابزارها به صورت عمومی تهیه شده‌اند. به همین جهت محصور کننده‌هایی نیز برای آن‌ها جهت یکپارچگی با ASP.NET Core، طراحی شده‌اند؛ مانند میان‌افزار Swashbuckle.AspNetCore. کار آن تولید OpenAPI Specification بر اساس ASP.NET Core 2x API شما می‌باشد که جزئیات انجام اینکار را به مرور بررسی خواهیم کرد. این کامپوننت به همراه یک swagger-ui جایگذاری شده (embedded) نیز می‌باشد که کار تهیه‌ی یک UI خودکار را بر اساس این استاندارد میسر می‌کند.
البته محصورکننده‌های متعددی برای ابزارهای Swagger، برای پروژه‌های ASP.NET Core وجود دارند که یکی دیگر از آن‌ها NSwag است. هرچند Swashbuckle.AspNetCore پرکاربردترین مورد تا به امروز بوده‌است.


ساختار نمونه برنامه‌ای که در این سری تکمیل خواهد شد


در اینجا ساختار برنامه‌ی ASP.NET Core 2.2x نمونه‌ی این سری را ملاحظه می‌کنید که هدف اصلی آن، ارائه‌ی دو کنترلر Web API برای کتاب‌ها و نویسنده‌های آن‌ها می‌باشد:


برای نمونه اگر برنامه را اجرا کنید، در مسیر https://localhost:5001/api/authors، لیست تمام نویسندگانی که به صورت اطلاعات آغازین برنامه، توسط OpenAPISwaggerDoc.DataLayer ثبت شده‌اند، قابل مشاهده‌است:


و یا کتاب‌های نویسنده‌ای خاص را در آدرسی مانند https://localhost:5001/api/authors/2902b665-1190-4c70-9915-b9c2d7680450/books می‌توان مشاهده کرد:



کدهای کامل آغازین این نمونه برنامه را از اینجا می‌توانید دریافت کنید: OpenAPISwaggerDoc-01.zip و شامل این اجزا است:
- OpenAPISwaggerDoc.Entities: به همراه موجودیت‌های نویسنده و کتاب است.
- OpenAPISwaggerDoc.DataLayer: شامل DbContext برنامه است؛ به همراه تعدادی رکورد پیش‌فرض جهت آغاز بانک اطلاعاتی و چون DbContext را در یک پروژه‌ی مجزا قرار داده‌ایم، نیاز به IDesignTimeDbContextFactory نیز دارد که این مورد هم در این پروژه لحاظ شده‌است.
- OpenAPISwaggerDoc.Models: شامل DTOهای برنامه است. برای نگاشت این DTOها به موجودیت‌ها و برعکس، از AutoMapper استفاده شده‌است که کار این نگاشت‌ها و تعریف پروفایل متناظر با آن‌ها، در پروژه‌ی OpenAPISwaggerDoc.Profiles صورت می‌گیرد.
- OpenAPISwaggerDoc.Services: کار استفاده‌ی از لایه‌ی OpenAPISwaggerDoc.DataLayer را جهت دسترسی به بانک اطلاعاتی و کار با موجودیت‌های کتاب‌ها و نویسندگان، انجام می‌دهد. از این سرویس‌ها در دو کنترلر Web API برنامه، برای دریافت اطلاعات نویسندگان و کتاب‌های آن‌ها از بانک اطلاعاتی، استفاده می‌شود.
- OpenAPISwaggerDoc.Web: پروژه‌ی اصلی است که دو کنترلر Web API را هاست می‌کند و تنظیمات اولیه‌ی این سرویس‌ها را در کلاس Startup انجام داده و همچنین کار اعمال خودکار Migrations را نیز در کلاس Program (بالاترین سطح برنامه) تکمیل می‌کند. رشته‌ی اتصالی این برنامه، در فایل appsettings.json تعریف شده‌است و به یک بانک اطلاعاتی LocalDB اشاره می‌کند که پس از اجرای برنامه به صورت خودکار ساخته شده و مقدار دهی می‌شود.


در قسمت بعد، کار مستند سازی این API را شروع می‌کنیم.