ASP.NET Core / الأساسي: HTTP وتركيب التطبيق / الدرس 5

المتحكمات وعقود MVC للواجهات

استخدم اصطلاحات المتحكم وحالة النموذج ونتائج الأفعال والمرشحات، مع تمييز اختبارات الفعل المباشرة من تنفيذ الإطار.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-26

في هذه الصفحة

أهداف الدرس

شرح ControllerBase وتوجيه الصفات وApiController.
فصل ربط النموذج وتحققه من قواعد المجال.
اختبار قصد الفعل دون ادعاء تنفيذ خط MVC.

ينظم المتحكم أفعال HTTP لا كل المسؤوليات

تدعم ControllerBase نتائج الواجهة وأدوات HTTP، وتضيف Controller دعم العرض. ليترجم المتحكم حد HTTP إلى عمليات تطبيق، لا ليجمع SQL والتفويض والملفات وثوابت الأعمال في صنف ضخم. تظهر حقن المنشئ الاعتمادات وتجعلها قابلة للاختبار.

توفر ApiController اصطلاحات موثقة منها توجيه الصفات والرفض التلقائي لحالة النموذج. تعتمد على تسجيل MVC وتنفيذها، لا على اعتراض سحري لكل طريقة. لا تنفذ دعوة متحكم جديد مباشرة الربط أو المرشحات أو التفويض.

يلزم التسجيل وتعيين النقاط معا

يظهر المقتطف تسجيل المتحكمات وتعيينها ويترك بناء المضيف والطلب الحقيقي خارجه عمدا. لا تجعل الإضافة كل طريقة عامة واجهة آمنة؛ يحدد الاكتشاف والتوجيه والصفات والمرشحات والاصطلاحات ما ينكشف.

طابق الطريقة والمسار ووصف النتيجة بالحالة الفعلية. لا تعد كيان التخزين مدخلا غير مقيد إن لم يجز للعميل ضبط حقول الخادم. قد توضح DTO منفصلة الإفراط في الإسناد وتوافق النسخ.

csharp تسجيل متحكم وتعيينه على سبيل التوضيح

builder.Services.AddControllers();
// After the application is built:
app.MapControllers();

لم ينفذ مقتطف المضيف، وهو لا ينشئ مستمعا ولا ينفذ ربط MVC.

ليست حالة النموذج نموذج المجال الكامل

قد تحتوي ModelState أخطاء تحويل وتحقق من MVC. وقد تولد ApiController حالة 400 تلقائيا وفق إعدادها، غالبا بوصف تحقق من عائلة ProblemDetails. تبقى الملكية الحالية والتفرد وسير العمل في التطبيق والمجال. قد يصح شكل النموذج ويظل غير مخول أو غير متسق مع المحفوظ.

حدد فئات أخطاء متوقعة ولا تعرض SQL أو استثناء خاما. اختبر السلوك التلقائي المخصص وعقد النقطة معا. لا تتوقع 400 آلية من دعوة وحدة مباشرة إلا إذا نفذ الفعل فحصها صراحة.

يفحص الفعل المباشر قصد النتيجة

ينشئ البرنامج متحكما وينادي فعلا دون مضيف، ثم يفحص OkObjectResult وDTO اصطناعية. هذا فحص مفيد لتفرع الفعل لا لخط الطلب. تبقى الصفات تصريحات حتى تفسرها مكونات الإطار المناسبة.

اختر ActionResult<T> أو IActionResult وفق العقد وأظهر النجاح والغياب والخطأ والتعارض والمنع. تحتاج نتائج توليد الروابط مثل CreatedAtAction تكاملا للتوجيه والتوليد؛ فلا يكفي فحص الوحدة لكائن النتيجة.

csharp فحص نتيجة استدعاء فعل متحكم مباشرة

using System;
using Microsoft.AspNetCore.Mvc;

var controller = new ReportsController();
IActionResult response = controller.Get(7);
var ok = response as OkObjectResult ?? throw new InvalidOperationException("expected Ok result");
var report = ok.Value as ReportDto ?? throw new InvalidOperationException("expected report");
Console.WriteLine($"status={ok.StatusCode} id={report.Id}");

[ApiController]
[Route("reports")]
public sealed class ReportsController : ControllerBase
{
    [HttpGet("{id:int}")]
    public IActionResult Get(int id) => id == 7 ? Ok(new ReportDto(7)) : NotFound();
}
internal sealed record ReportDto(int Id);

الناتج المتوقع

status=200 id=7

تعيد الدعوة المباشرة نتيجة Ok تحوي القيمة 7؛ ولا تنفذ توجيه MVC أو مرشحات حالة النموذج.

تحتاج المرشحات والسياسات اختبار حدودها

تقع مرشحات MVC ووسيط النقطة وخدمات التطبيق عند مواضع مختلفة. ليس مرشح الفعل ملتقطا عاما لكل فشل وسيط، ولا تحمي صفة تفويض دعوة خارج الخط. راجع النطاق والترتيب ولا تحمل المتحكم كل شأن مشترك.

اختبر الفروع مباشرة بمزيفات، ثم استخدم تكاملا معزولا مدعوما للربط والتحقق الآلي والمرشحات والهوية والتسلسل والروابط والحالة. أبق البيانات اصطناعية وادعاء المزود صادقا. لا يستخدم الدرس تطبيقا مهيأ أو قاعدة أو TestHost أو مستمعا.

الأخطاء الشائعة وإصلاحها

يتوقع اختبار فعل مباشر الرفض التلقائي 400 من ApiController.

لماذا يحدث؟: لم ينفذ الاختبار خط MVC الذي يطبق هذا السلوك.
كيف تصلحه؟: اختبر منطق الفعل الصريح مستقلا عن تكامل حالة النموذج.
كيف تتجنب تكراره؟: سم مستوى التحقق الذي ينفذه كل اختبار.

يكشف DTO للعميل حقولا يملكها الخادم.

لماذا يحدث؟: أعيد استخدام شكل الحفظ كمدخل غير مقيد.
كيف تصلحه؟: حول نموذج طلب محدودا إلى عملية مجال صريحة.
كيف تتجنب تكراره؟: اختبر الإفراط في الإسناد وحدود التفويض.

يتوقع من مرشح المتحكم التقاط كل فشل وسيط.

لماذا يحدث؟: اختلطت نطاقات تنفيذ مختلفة.
كيف تصلحه؟: ضع معالجة الخطأ عند حد الخط الذي يملكها.
كيف تتجنب تكراره؟: اختبر الفشل قبل MVC وداخلها.

اختبر فهمك

1. يحمل فعل صفة Authorize، لكن اختبار الوحدة يستدعيه كطريقة عادية. ما ادعاء الأمن الذي يثبت فعلا؟

اعرض الحل المشروح

يمكن للاختبار المباشر فحص منطق الإرجاع، لكنه لا يثبت تطبيق التفويض. الصفة وصف يفسره الخط المضبوط. اختبر السياسة منفصلة وأضف طلبا معزولا مناسبا للمصادق وغير المصادق والممنوع ومالك المورد. لا تستنتج ضبط الوصول من نجاح الدعوة أو وجود الصفة وحدهما.

2. لماذا قد يكون كائن CreatedAtAction صحيحا في اختبار الوحدة، بينما يكون رابط Location العام مكسورا؟