تمرين - إضافة وحدة تحكم

  • 5 دقائق

وحدة التحكم هي فئة عامة مع أسلوب عام واحد أو أكثر يعرف باسم الإجراءات. حسب ما هو تعارف عليه، تُوضع وحدة تحكم في دليل ⁧وحدات التحكم⁩⁧⁩الخاصة بجذر المشروع. يتم عرض الإجراءات كنقاط نهاية HTTP داخل وحدة تحكم واجهة برمجة التطبيقات على الويب.

إنشاء وحدة تحكم

  1. حدد مجلد Controllers في Visual Studio Code ثم أضِف ملفاً جديداً يُسمى PizzaController.cs.

    لقطة شاشة لـ Visual Studio Code تعرض إضافة ملف جديد إلى المجلد

    يُنشأ ملف فئة فارغ باسم PizzaController.cs في الدليل Controllers. اسم دليل Controllers هو اصطلاح. اسم الدليل يأتي من تصميم وحدة التحكم في عرض النموذج الذي تستخدمه واجهة برمجة تطبيقات الويب.

    إشعار

    حسب ما هو تعارف عليه، يجري إلحاق أسماء فئة وحدة التحكم بـ ⁧⁩⁧Controller⁩⁧.

  2. أضِف التعليمات البرمجية التالية إلى Controllers/PizzaController.cs. احفظ تغييراتك.

    using ContosoPizza.Models;
using ContosoPizza.Services;
using Microsoft.AspNetCore.Mvc;

namespace ContosoPizza.Controllers;

[ApiController]
[Route("[controller]")]
public class PizzaController : ControllerBase
{
    public PizzaController()
    {
    }

    // GET all action

    // GET by Id action

    // POST action

    // PUT action

    // DELETE action
}

    كما علمت سابقًا، هذه الفئة مشتقة من ControllerBase، الفئة الأساسية للعمل مع طلبات HTTP في ASP.NET Core. كما يتضمن السمتين القياسيتين اللذين تعلمتهما عن: [ApiController] و [Route]. كما في السابق، تحدد السمة [Route] تعيين إلى الرمز المميز [controller]. لأن فئة وحدة التحكم هذه تُسمى PizzaController، فإن وحدة التحكم هذه تعالج طلبات إلى https://localhost:{PORT}/pizza.

احصل على جميع أنواع البيتزا

فعل REST الأول الذي تحتاجه إلى تنفيذه هو GET حيث يمكن للعميل الحصول على جميع أنواع البيتزا من واجهة برمجة التطبيقات. يمكنك استخدام السمة المضمنة [HttpGet] لتحديد أسلوب يقوم بإرجاع البيتزا من خدمتنا.

استبدل التعليق // GET all action في Controllers/PizzaController.cs بالتعليمة البرمجية التالية:

[HttpGet]
public ActionResult<List<Pizza>> GetAll() =>
    PizzaService.GetAll();

الإجراء السابق:

  • يستجيب فقط إلى الفعل HTTP GET، كما هو موضح بواسطة السمة [HttpGet].
  • إرجاع مثيل ActionResult من النوع List<Pizza>. النوع ActionResult هو الفئة الأساسية لجميع نتائج الإجراء في ASP.NET Core.
  • للاستعلام عن الخدمة لجميع أنواع البيتزا وإرجاع البيانات تلقائيًا بـ Content-Type قيمة application/json.

استرداد بيتزا واحدة

قد يرغب العميل أيضًا في طلب معلومات عن بيتزا معينة بدلًا من القائمة بأكملها. يمكنك تنفيذ إجراء GET آخر يتطلب معلمة id. يمكنك استخدام السمة المضمنة [HttpGet("{id}")] لتحديد أسلوب يقوم بإرجاع البيتزا من خدمتنا. منطق التوجيه يسجل [HttpGet] (دون id) و [HttpGet("{id}")] (مع id) باعتبارهما مسارين مختلفين. يمكنك بعد ذلك كتابة إجراء منفصل لاسترداد عنصر واحد.

استبدل التعليق // GET by Id action في Controllers/PizzaController.cs بالتعليمة البرمجية التالية:

[HttpGet("{id}")]
public ActionResult<Pizza> Get(int id)
{
    var pizza = PizzaService.Get(id);

    if(pizza == null)
        return NotFound();

    return pizza;
}

الإجراء السابق:

  • يستجيب فقط إلى الفعل HTTP GET، كما هو موضح بواسطة السمة [HttpGet].
  • يتطلب تضمين قيمة المعلمة id في مقطع URL بعد pizza/. تذكر أن السمة [Route] على مستوى وحدة التحكم حددت النمط /pizza.
  • استفسارات عن قاعدة البيانات الخاصة بالبيتزا التي تطابق المعلمة idالمتاحة.

يُعين كل مثيل ⁧ActionResult⁩ في الإجراء السابق إلى التعليمة البرمجية الخاصة بحالة HTTP المطابق في الجدول التالي:

ASP.NET Core
نتيجة الإجراء		 رمز حالة HTTP ‏‏الوصف
Ok ضمني 200 يوجد منتج يطابق المعلمة id الموجودة في ذاكرة التخزين المؤقت في الذاكرة.
يُدرج المنتج في نص الاستجابة في نوع الوسائط على النحو المحدد في accept عنوان طلب HTTP (JSON بشكل افتراضي).
NotFound 404 لا يوجد منتج مطابق للمعلمة id المتاحة في ذاكرة التخزين المؤقت في الذاكرة.

إنشاء وحدة التحكم الجديدة وتشغيلها

أنشئ واجهة برمجة تطبيقات الويب وابدأ تشغيلها عن طريق تشغيل الأمر التالي:

dotnet run

اختبار وحدة التحكم باستخدام ملف Http

  1. افتح ContosoPizza.http

  2. أضف GET جديدا 

    GET {{ContosoPizza_HostAddress}}/pizza/
Accept: application/json

###

  3. حدد الأمر Send Request أعلى استدعاء GET الجديد هذا.

    يقوم الأمر السابق بإرجاع قائمة بجميع أنواع البيتزا في JSON:

    HTTP/1.1 200 OK
Connection: close
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Jan 2024 16:57:09 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
    {
        "id": 1,
        "name": "Classic Italian",
        "isGlutenFree": false
    },
    {
        "id": 2,
        "name": "Veggie",
        "isGlutenFree": true
    }
]

  4. للاستعلام عن نوع بيتزا واحد، يمكننا تقديم طلب GET آخر، ولكننا نمرر معلمة id باستخدام الأمر التالي:

    GET {{ContosoPizza_HostAddress}}/pizza/1
Accept: application/json

###

    يُرجع الأمر السابق Classic Italian مع ملف الإخراج التالي:

    HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 21:57:57 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
    "id": 1,
    "name": "Classic Italian",
    "isGlutenFree": false
}

  5. تعالج واجهة برمجة تطبيقاتنا أيضًا الحالات التي يكون فيها العنصر غير موجود. بادر باستدعاء واجهة برمجة التطبيقات مرةً أخرى، ولكن مرر معلمة id بيتزا غير صالحة باستخدام الأمر التالي:

    GET {{ContosoPizza_HostAddress}}/pizza/5
Accept: application/json

###

    يُرجع الأمر السابق خطأ 404 Not Found مع الإخراج التالي:

    HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8
Date: Fri, 02 Apr 2021 22:03:06 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
    "title": "Not Found",
    "status": 404,
    "traceId": "00-ec263e401ec554b6a2f3e216a1d1fac5-4b40b8023d56762c-00"
}

الآن بعد أن انتهيت من GET تنفيذ الأفعال. في الوحدة التالية، يمكنك إضافة المزيد من الإجراءات لـ PizzaController لدعم عمليات CRUD على بيانات البيتزا.

اختياري: اختبر وحدة التحكم باستخدام سطر الأوامر HTTP Read-Eval-Print Loop (REPL)

  1. افتح terminal httprepl الموجودة أو افتح terminal متكاملة جديدة من Visual Studio Code عن طريق تحديد Terminal>New Terminal من القائمة الرئيسية.

  2. اتصل بواجهة برمجة تطبيقات الويب عن طريق تشغيل الأمر التالي:

    httprepl https://localhost:{PORT}

    بدلًا من ذلك، شغَّل الأمر التالي في أي وقت أثناء تشغيل HttpRepl:

    connect https://localhost:{PORT}

  3. لرؤية نقطة نهاية Pizza المتاحة حديثًا، شغَّل الأمر التالي:

    ls

    يكشف الأمر السابق عن جميع واجهات برمجة التطبيقات المتاحة على نقطة النهاية المتصلة. يجب أن يعرض التعليمات البرمجية التالية:

     https://localhost:{PORT}/> ls
 .                 []
 Pizza             [GET]
 WeatherForecast   [GET]

  4. انتقل إلى نقطة النهاية Pizza عن طريق تشغيل الأمر التالي:

    cd Pizza

    يظهر الأمر السابق إخراج واجهات برمجة التطبيقات المتوفرة لنقطة النهاية Pizza:

    https://localhost:{PORT}/> cd Pizza
/Pizza    [GET]

  5. قدم طلب GET في HttpRepl باستخدام الأمر التالي:

    get

    يقوم الأمر السابق بإرجاع قائمة بجميع أنواع البيتزا في JSON:

      HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  Date: Fri, 02 Apr 2021 21:55:53 GMT
  Server: Kestrel
  Transfer-Encoding: chunked

  [
      {
          "id": 1,
          "name": "Classic Italian",
          "isGlutenFree": false
      },
      {
          "id": 2,
          "name": "Veggie",
          "isGlutenFree": true
      }
  ]

  6. للاستعلام عن نوع بيتزا واحد، يمكننا تقديم طلب GET آخر، ولكننا نمرر معلمة id باستخدام الأمر التالي:

    get 1

    يُرجع الأمر السابق Classic Italian مع ملف الإخراج التالي:

    HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 21:57:57 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
    "id": 1,
    "name": "Classic Italian",
    "isGlutenFree": false
}

  7. تعالج واجهة برمجة تطبيقاتنا أيضًا الحالات التي يكون فيها العنصر غير موجود. بادر باستدعاء واجهة برمجة التطبيقات مرةً أخرى، ولكن مرر معلمة id بيتزا غير صالحة باستخدام الأمر التالي:

    get 5

    يُرجع الأمر السابق خطأ 404 Not Found مع الإخراج التالي:

    HTTP/1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8
Date: Fri, 02 Apr 2021 22:03:06 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
    "title": "Not Found",
    "status": 404,
    "traceId": "00-ec263e401ec554b6a2f3e216a1d1fac5-4b40b8023d56762c-00"
}

  8. ارجع إلى dotnet terminal في القائمة المنسدلة في تعليمة Visual Studio البرمجية وأوقِف تشغيل واجهة برمجة تطبيقات الويب عن طريق تحديد CTRL+C في لوحة مفاتيحك.

الآن بعد أن انتهيت من GET تنفيذ الأفعال. في الوحدة التالية، يمكنك إضافة المزيد من الإجراءات لـ PizzaController لدعم عمليات CRUD على بيانات البيتزا.