راهنمای مقدماتی NET Core. | به زبان ساده

مایکروسافت هر سال با معرفی نرم‌افزارهای متن-باز جدید و فناوری‌های قدرتمند و جدید در این حوزه بیشتر و بیشتر با ابداعات اوپن-سورس درگیر می‌شود. یکی از این ابداع‌ها نیز ‎.NET Core است. در این مقاله به عنوان یک راهنمای مقدماتی NET Core. با این فناوری بیشتر آشنا خواهیم شد.

فریمورک ‎.NET Core فرصتی برای توسعه‌دهندگان و سازمان‌هایی که از فناوری مایکروسافت استفاده می‌کنند فراهم ساخته است تا به سمت مدل متن-باز مهاجرت کنند. همچنین افرادی نیز که از اول در حوزه متن-باز کار کرده‌اند و در این زمینه تجربه دارند، می‌توانند از این ابزارها و فریمورک‌های مایکروسافت بهره‌مند شوند.

این مواجهه دو دنیای مختلف و با ارزش بالا یعنی مایکروسافت و اوپن-سورس موجب شده است که فرصت‌های جدیدی برای مهاجرت سیستم‌های قدیمی به معماری مدرن فراهم آید و امکان ساخت اینترفیس برای سیستم‌هایی که عموماً این کار برایشان دشوار است پدید آید. همچنین می‌توان نرم‌افزارهای جدید را با استفاده از تیم‌هایی توسعه داده که تجربه‌های متنوعی در زمینه‌های مختلف ابزارها و روش‌های صنعت نرم‌افزار دارند.

در این مقاله به بررسی شیوه ساخت یک REST API ساده با پیاده‌سازی مقدماتی CRUD می‌پردازیم تا آیتم‌هایی را با name و description شبیه‌سازی کنیم. سورس کد پروژه مطرح شده در این راهنما را می‌توانید در این ریپوی گیت‌هاب (+) ببینید.

تنظیم پروژه

اگر ‎.NET Core را روی سیستم خود ندارید یک کپی از آن را برای سیستم‌ عامل خودتان از این آدرس (+) تهیه کنید.

فیلم آموزش ASP.NET Core – مقدماتی در فرادرس

کلیک کنید

این پروژه را با دستور زیر مقداردهی می‌کنیم:

dotnet new webapi -o ItemsAPI

دستور فوق نوعی کد قالبی ‎.NET Core در پوشه ItemsAPI ایجاد می‌کند. فایل پیکربندی این پروژه برای این اپلیکیشن در مسیر ItemsAPI.csproj و با محتوای زیر قرار دارد:

1<Project Sdk="Microsoft.NET.Sdk.Web">
2
3  <PropertyGroup>
4    <TargetFramework>netcoreapp2.2</TargetFramework>
5    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
6  </PropertyGroup>
7
8  <ItemGroup>
9    <PackageReference Include="Microsoft.AspNetCore.App" />
10    <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
11  </ItemGroup>
12
13</Project>

این فایل جزییات پیکربندی از قبیل نسخه فریمورک ‎.NET و پکیج‌های لازم برای اپلیکیشن را برای خود پروژه تعریف می‌کند. این پروژه از هیچ پکیج اضافی استفاده نمی‌کند؛ اما اگر چنین چیزی اضافه می‌شد، به تگ <ItemGroup> به عنوان یک مدخل دیگر <PackageReference> اضافه می‌شد.

نقطه ورودی اپلیکیشن

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

1using Microsoft.AspNetCore;
2using Microsoft.AspNetCore.Hosting;
3
4namespace ItemsAPI
5{
6    public class Program
7    {
8        public static void Main(string[] args)
9        {
10            CreateWebHostBuilder(args).Build().Run();
11        }
12
13        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
14            WebHost.CreateDefaultBuilder(args)
15                .UseStartup<Startup>();
16    }
17}

زمانی که این اپلیکیشن با دستور dotnet run اجرا شد، متد Main فراخوانی می‌شود و سپس فرا خوانده می‌شود و یک builder با استفاده از کلاس Startup ساخته می‌شود که شامل پیکربندی آغازین اپلیکیشن است.

پیکربندی آغازین

در گام بعدی کلاس Startup را که در بخش فوق اشاره کردیم، در فایلی به نام Startup.cs ایجاد می‌کنیم:

1using Microsoft.AspNetCore.Builder;
2using Microsoft.AspNetCore.Hosting;
3using Microsoft.AspNetCore.Mvc;
4using Microsoft.Extensions.Configuration;
5using Microsoft.Extensions.DependencyInjection;
6
7namespace ItemsAPI
8{
9    public class Startup
10    {
11        public Startup(IConfiguration configuration)
12        {
13            Configuration = configuration;
14        }
15
16        public IConfiguration Configuration { get; }
17
18        // This method gets called by the runtime. Use this method to add services to the container.
19        public void ConfigureServices(IServiceCollection services)
20        {
21            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
22        }
23
24        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
25        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
26        {
27            if (env.IsDevelopment())
28            {
29                app.UseDeveloperExceptionPage();
30            }
31            else
32            {
33                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
34                app.UseHsts();
35            }
36
37            app.UseHttpsRedirection();
38            app.UseMvc();
39        }
40    }
41}

در این کلاس، پیکربندی آغازین زیر را تعریف کرده‌ایم:

• سرویس‌ها در متد ConfigureServices تعریف شده‌اند.
• Pipeline درخواست HTTP در متد Configure تعریف شده است.

همچنین درون Configure بررسی می‌کنیم تا مشخص شود آیا اپلیکیشن در حال حاضر در حالت توسعه (Development) اجرا شده است یا نه. امکان تعیین پیکربندی برای حالت‌های dev ،testing ،production و غیره وجود دارد.

کلاس ItemsController

در این بخش فایل کنترلر به نام Controllers/ItemsController.cs را تعریف می‌کنیم:

1using System.Collections.Generic;
2using System.Linq;
3using Microsoft.AspNetCore.Mvc;
4
5namespace ItemsAPI.Controllers
6{
7    [Route("api/[controller]")]
8    [ApiController]
9    public class ItemsController : ControllerBase
10    {
11        static private List<Item> items = new List<Item>();
12
13        // GET api/values
14        [HttpGet]
15        public ActionResult<List<Item>> Get()
16        {
17            return items;
18        }
19
20        // GET api/values/5
21        [HttpGet("{index}")]
22        public ActionResult<Item> Get(int index)
23        {
24            return items[index];
25        }
26
27        // GET api/values/5
28        [HttpGet("/range/{a}/to/{b}")]
29        public ActionResult<List<Item>> Get(int a, int b)
30        {
31            return items.GetRange(a, b - a);
32        }
33
34        // POST api/values
35        [HttpPost]
36        public int Post([FromBody] Item item)
37        {
38            ItemsController.items.Add(item);
39            int index = ItemsController.items.Count() - 1;
40            return index;
41        }
42
43        // PUT api/values/5
44        [HttpPut("{index}")]
45        public void Put(int id, [FromBody] Item item)
46        {
47            ItemsController.items[id] = item;
48        }
49
50        // DELETE api/values/5
51        [HttpDelete("{index}")]
52        public void Delete(int index)
53        {
54            ItemsController.items.RemoveAt(index);
55        }
56    }
57}

کلاس ItemsController دارای خصوصیت‌های Route و ApiController است که این کنترلر را طوری پیکربندی می‌کند تا روی API در مسیر تعریف شده، مورد استفاده قرار گیرد.

مشخصه items یک List<Item>‎ تعریف می‌کند که لیستی از اشیای Item را در خود نگهداری می‌کند که به عنوان انبار داده برای این اپلیکیشن عمل می‌کنند در عمل می‌توان از هر راهکار ذخیره‌سازی یا پیام‌رسانی مناسب برای مقاصد ضروری استفاده کرد، اما این یک مثال خوب برای ساده نگهداشتن طراحی در مرحله تعیین چارچوب پروژه است، این راه‌کار شبیه‌سازی موقت به سادگی در طی چند ثانیه پیاده‌سازی می‌شود و این مزیت را دارد که استاتیک، داخلی و به سادگی قابل بازگردانی به حالت پاک (با ری‌استارت کردن سرور) است. همه این وارد موجب می‌شوند که این یک تنظیمات سریع و کامل برای تست کردن ایده یا مفهوم مورد نظر ما باشد، چون موارد کمی وجود دارند که امکان بروز اشتباه داشته باشند.

همچنین درون این کلاس چند متد ()Get علاوه بر ()Post() ،Put و ()Delete وجود دارند که در مجموع، مجموعه عملیات CRUD را تکمیل می‌کنند. هر یک از این متدها دارای یک پیشوند دکوراتور مانند [HttpGet] و نظایر آن هستند که به فریمورک نشان می‌دهد، کدام متد HTTP باید (به صورت اختیاری) به مسیری که نقطه انتهایی REST عرضه می‌کند علاوه شود.

متدهای HTTP زیر توسط این API نمونه پیاده‌سازی شده‌اند:

• [HttpGet] – فهرستی از آیتم‌های مرتب‌سازی‌شده را بازگشت می‌دهد.
• [HttpGet("{index}")] – آیتم موجود در index را بازگشت می‌دهد.
• [HttpGet("/range/{a}/to/{b}")] – آیتم‌های لیست را از a تا b بازگشت می‌دهد.
• [HttpPost] – یک Item را از بدنه JSON به لیست الحاق می‌کند.
• [HttpPut("{index}")] – آیتم موجود در index را تعویض می‌کند.
• [HttpDelete("{index}")] – آیتم موجود در index را حذف می‌کند.

کلاس Item که در اینجا استفاده شده است، مشخص می‌سازد که هر «نقطه انتهایی» (endpoint) باید کدام مشخصه‌ها را دریافت کند و این مسئله هم داده‌های JSON و هم داده‌های درون انبار داده موقتی (لیست آیتم‌ها) را شامل می‌شود. این کار به فریمورک امکان می‌دهد که درخواست‌های با صورت‌بندی ناصحیح را رد کند و همچنین بررسی خطای زمان ادیت و زمان کامپایل به علاوه تکمیل کد و دیگر مزیت‌ها به توسعه‌دهنده کمک می‌کند. در بخش بعدی کلاس Item را بررسی می‌کنیم.

کلاس Item

به عنوان آخرین مورد، کلاس Item را در مسیر Models/Items.cs تعریف می‌کنیم:

1namespace ItemsAPI {
2
3    public class Item
4    {
5        public string name { get; set; }
6        public string description { get; set; }
7    }
8}

این فایل نسبتاً خود-گویا است و مشخصه‌های name و description را برای ایجاد یک ساختمان داده استاندارد برای یک آیتم تعریف می‌کند. در این فایل accessor‌-های get و set برای هر مشخصه تعریف شده‌اند، اما این موارد را می‌توان با جزییات بیشتر تعریف کرد تا میزان کنترل و اعتبارسنجی داده‌ها را افزایش داد.

تست کردن

برای آغاز سرور، باید دستور زیر را در یک ترمینال اجرا کنید:

1$./api-start.sh

سپس یک نشست ترمینال جدید باز کرده و دستورهای زیر را برای اجرای اکشن‌های با نام‌های متناظر اجرا می‌کنیم:

1$./api-add-item.sh "Item Name" "Some item description text"

اسکریپت ‎/api-add-item.sh یک درخواست HTTP POST را به API ارسال می‌کند و داده‌ها را در شیء درخواست JSON می‌فرستد تا با ساختار Item تطبیق پیدا کند که یک آیتم جدید به لیست اضافه کرده و index آیتم را بازگشت می‌دهد:

1$./api-list-items.sh

این اسکریپت یک درخواست HTTP GET به API ارسال می‌کند که صرفاً لیستی از آیتم‌های اضافه شده قبلی را به شکل رشته پاسخ JSON سریال‌سازی‌شده بازگشت می‌دهد.

سخن پایانی

در این مقاله نشان دادیم که توسعه ‎.NET Core تا چه حد ساده است و قابلیت‌هایی عالی چه برای خود زبان #C که قدرتمند و گویا است و چه درون فریمورک NET. و ریپازیتوری پکیج‌های NuGet عرضه می‌کند و به توسعه‌دهندگان اجازه می‌دهد که به سرعت از تجربه جامعه بزرگ توسعه‌دهندگان بهره گرفته و بر مبنای آن کار خود را گسترش دهند.

اپلیکیشن API ساده که در این نوشته بررسی کردیم به صورت متن-باز در این ریپوی گیت‌هاب (+) عرضه شده است و می‌توانید آن را فورک کرده و یک سرور API جدید را برای مقاصد مختلف طراحی کنید.