Software Engineer Encyclopedia
0%
Domain 03 · Backend Engineering & Web Development · Topic 3.1 · Part 1/2

ASP.NET Core Web API — الأساس ودورة الطلب

ASP.NET Core Web API · Part 1

فهم شكل تطبيق ASP.NET Core، HTTP request lifecycle، routing، controllers، binding، configuration، logging، environments، وعلاقة كل ده بالـ hosting pipeline.

  • Intermediate
  • ~23 min read
  • 8 sections
  • 16 code examples
  • 3 diagrams
  • 4 questions
  • Priority L1 · Essential
  • .NET 10 LTS · ASP.NET Core 10 · C# 14

المتطلبات قبل ما تبدأ

C# و.NET (المجال 02) والـ HTTP/Networking (درس 1.2).

مستوى التعمق المطلوب

DEEPPipeline, DI, HTTP, validation, security, error handling, and testing.

01

الصورة الكبيرة: الـ API بيعمل إيه؟

Introduction · What an HTTP API actually does
Basics

الـ Web API هو boundary بين client (موبايل، Angular، خدمة تانية) وبين business capabilities عندك. العميل بيبعت HTTP request فيه method و URL و headers وممكن body؛ التطبيق يفسّر الطلب، يطبّق السياسات، ينفّذ المنطق، ويرجع status code و headers و representation غالباً JSON.

Transport contract

HTTP هو الاتفاق على شكل التواصل: method، URI، status، headers، body. لا تخلط بين HTTP وبين business logic.

Application behavior

Endpoint يربط الطلب بحالة استخدام، ثم service/domain يتعامل مع القواعد، و data access يتعامل مع التخزين.

Host responsibilities

Kestrel يستقبل الاتصالات، والـ middleware pipeline يمرر الطلب خلال cross-cutting concerns ثم endpoint execution.

ClientMobile / SPAKestrelHTTP serverMiddlewarePipelineEndpointController / HandlerResponse travels back through the pipeline
المسار العام من جهاز العميل إلى النتيجة، مع فصل HTTP boundary عن business logic والتخزين.

الـ request/response lifecycle لازم يبقى واضح في دماغك: network connection → server accepts request → middleware → endpoint selection/execution → response creation → middleware unwind → network response. الـ response ممكن يبدأ streaming؛ وقتها مش كل body لازم يكون اتجهز في الذاكرة قبل الإرسال.

خريطة ذهنية لدورة ASP.NET Core API

HTTP RequestMiddlewareRoutingEndpointBinding+ ValidationAuthorization+ FiltersApplicationUse CasePersistence/ External I/OHTTP Result → Serialization → Response
كل طبقة لها مسؤولية مختلفة؛ لا تنقل قراراً من طبقة إلى أخرى لمجرد أن الكود أقصر.

استخدم الخريطة دي عند debugging. لو route لم يتم اختياره، المشكلة Routing. لو body لم يتحول إلى DTO، راجع content type/model binding. لو 400 قبل دخول action، راجع automatic validation. لو user وصل للـ action لكنه غير مسموح، راجع authorization/resource access. لو database بطيئة، راقب persistence spans. لو JSON مختلف عن المتوقع، راجع result execution/serializer settings.

الفصل بين المراحل يمنعك من وضع workaround في المكان الخطأ. مثلاً لا تعالج invalid JSON داخل business service؛ الخدمة لم تستلم DTO صالحاً أصلاً. ولا تجعل controller يقرر SQL retry policy؛ ده concern في infrastructure/dependency boundary. ولا تستخدم CORS لتمنع API access؛ CORS browser policy وليست authorization.

02

الـ Hosting و Program.cs

Host, builder, services, and app
Deep dive

في القالب الحديث، WebApplication.CreateBuilder(args) بيجهز Generic Host و Web Host defaults: configuration providers، logging providers، DI container، environment، Kestrel defaults، و content root. بعد كده بتسجل الخدمات، تستدعي Build() لإنشاء التطبيق، وتكوّن middleware/endpoint pipeline، ثم Run() لتشغيله.

C#Program.cs — minimal hosting model
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();
builder.Services.AddScoped<IInventoryService, InventoryService>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler();
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseRouting();
app.MapControllers();

app.Run();

// Needed by WebApplicationFactory in some top-level Program test setups.
public partial class Program { }

تتبّع التنفيذ

  1. CreateBuilder ينشئ builder ويحمّل إعدادات البيئة والـ command line وغيرها.
  2. builder.Services هو composition root: مكان تسجيل الخدمات قبل بناء provider. تفاصيل resolution والـ lifetimes موجودة في درس Dependency Injection.
  3. Build يبني الـ app والـ service provider ويثبت إعدادات الـ pipeline.
  4. النداءات Use... تضيف middleware بالترتيب؛ MapControllers يضيف controller endpoints.
  5. Run يبدأ استقبال الطلبات ويبقى التطبيق شغالاً حتى الإيقاف.

Environment management

الاسم الشائع للبيئات هو Development و Staging و Production، والقيمة تأتي عادة من DOTNET_ENVIRONMENT أو ASPNETCORE_ENVIRONMENT حسب host/configuration precedence. لا تضع secrets في ملفات إعدادات committed. استخدم User Secrets محلياً، و environment variables أو secret manager في النشر. البيئة ليست security boundary: لا تعتمد على اسمها وحده لحماية endpoint.

JSONappsettings.Production.json — non-secret settings
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Inventory": {
    "LowStockThreshold": 12
  }
}

الـ configuration providers لها ترتيب أولوية؛ غالباً environment variables والـ command-line values تتغلب على JSON files. لذلك نفس المفتاح قد يأخذ قيمة مختلفة في كل بيئة من غير تغيير الكود.

Request Anatomy و Kestrel والـ Reverse Proxy

الـ HTTP request عند وصوله للتطبيق لا يكون مجرد URL. Kestrel يقرأ HTTP framing، يكوّن HttpContext ويملأ Request properties مثل Method و Scheme و Host و Path و Query و Headers و Body. الـ Body stream قد يكون غير seekable، لذلك buffering أو القراءة المتكررة لها تكلفة وحدود. خلف reverse proxy مثل IIS/nginx/ingress، الاتصال الخارجي قد ينتهي عند proxy ثم proxy يتصل بـ Kestrel داخلياً؛ لذلك scheme/remote IP الأصليين قد يحتاجان Forwarded Headers Middleware من proxy موثوق.

C#Inspect request metadata safely
app.MapGet("/diagnostics/request", (HttpContext context) => new
{
    context.Request.Method,
    Path = context.Request.Path.Value,
    Query = context.Request.QueryString.Value,
    Scheme = context.Request.Scheme,
    Host = context.Request.Host.Value,
    Protocol = context.Request.Protocol,
    IsHttps = context.Request.IsHttps
});

لا تترك diagnostics endpoint مفتوحاً في production؛ هذه معلومات للتوضيح. لا تثق في X-Forwarded-For أو X-Forwarded-Proto من أي client عشوائي. اضبط KnownProxies/KnownNetworks وفعّل middleware قبل أي component يعتمد على scheme/IP. وإلا يمكن للمهاجم spoofing للـ client IP أو تجاوز rate limiting/security rules.

من أول byte لحد Action Result: دورة الطلب بالتفصيل

افصل بين أربع مراحل عشان ما تخلطش مسؤوليات ASP.NET Core: transport، hosting، middleware/endpoint routing، وapplication execution. المتصفح أو الموبايل يفتح connection ويبعث HTTP bytes. Kestrel يقرأ البروتوكول ويحوّل الاتصال إلى request abstractions. الـ host يمرر HttpContext للـ pipeline. Routing يختار endpoint ويملى metadata. بعد كده authorization و filters/model binding/validation حسب نوع endpoint. الـ action أو handler ينفذ، ثم result executor/HTTP result يحوّل النتيجة إلى status و headers و body. أخيراً response يرجع خلال middleware التي تنتظر next.

الـ HttpContext يمثل request واحد: Request، Response، User، Items، TraceIdentifier، و RequestServices. لا تخزن HttpContext في field داخل singleton أو تحتفظ به بعد انتهاء request؛ عمره مرتبط بالطلب. لو محتاج تنقل معلومة بين middleware و endpoint في نفس الطلب استخدم HttpContext.Items بحذر، ولو محتاج correlation/tracing استخدم Activity/diagnostics.

KestrelMiddlewareRoutingEndpointBindingValidationFiltersActionResult execution → HTTP response
الـ endpoint execution مش خطوة واحدة؛ فيه routing ثم binding ثم filters ثم action ثم result execution.

الترتيب الدقيق يختلف بين Controller actions و Minimal API handlers. في MVC مثلاً model binding و validation و action filters جزء من MVC action invocation، بينما Minimal APIs لها parameter binding و endpoint filters. لذلك لا تحفظ pipeline كأنها قائمة واحدة لكل أنواع endpoints؛ افهم أي subsystem مسؤول عن كل مرحلة.

Action result مش هو نفس HTTP response

لما ترجع Ok(dto) أنت بترجع object يعبّر عن النتيجة. MVC result executor هو اللي يحدد status code ويعمل content negotiation/serialization ويكتب body. أما return dto في بعض الأنماط فله semantics مختلفة. استخدم response types واضحة عشان تقدر توثق success و failure contracts وتختبرها.

C#An action with explicit HTTP outcomes
[HttpGet("{id:int}")]
[ProducesResponseType<ProductResponse>(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ProductResponse>> GetById(
    int id, CancellationToken cancellationToken)
{
    var product = await service.FindAsync(id, cancellationToken);
    if (product is null)
        return NotFound();

    return Ok(product);
}

اختبر الـ endpoint من HTTP boundary، مش بس باختبار service. اختبار service يثبت business behavior، لكنه لا يثبت route matching أو JSON serialization أو status code أو middleware. تفاصيل integration testing موجودة في جزء Web API الثاني.

HttpContext و Request Scope و Thread Safety

HttpContext مش object عام للتطبيق كله؛ هو state مرتبط بطلب HTTP واحد. تقدر تقرأ منه Request/Response/User/TraceIdentifier/RequestAborted، لكن لا تحتفظ به في singleton ولا تمرره إلى background job بعد انتهاء request. لو محتاج user ID أو tenant ID في background job، انسخ القيمة الضرورية إلى job payload قبل ما تنهي request، ولا تنقل HttpContext نفسه.

ASP.NET Core request processing async، فلا تفترض إن نفس request سيظل على نفس thread طوال عمره. لا تستخدم ThreadLocal لتخزين request data. استخدم DI scope أو HttpContext.Items أو logging scope أو Activity context حسب طبيعة البيانات. IHttpContextAccessor متاح عند الضرورة لكنه يعتمد على AsyncLocal وله تكلفة؛ الأفضل تمرير البيانات المطلوبة صراحةً إلى application service بدل جعل كل service تقرأ HttpContext مباشرة.

C#Extract identity at the HTTP boundary
[Authorize]
[HttpPost("orders")]
public async Task<ActionResult<OrderResponse>> Create(
    CreateOrderRequest request, CancellationToken token)
{
    var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
    if (string.IsNullOrWhiteSpace(userId))
        return Unauthorized();

    var result = await orderService.CreateAsync(
        userId, request, token);
    return CreatedAtAction(nameof(Get), new { id = result.Id }, result);
}

ده يخلي application service تستقبل user ID كبيانات صريحة، ويمكن اختبارها من غير fake HttpContext. لكن مجرد وجود user ID لا يثبت أن المستخدم يملك كل resource؛ service/domain authorization يجب أن يتحقق من ownership والسياسات المطلوبة.

Request Diagnostics و Trace Context

في production، request واحد ممكن يمر عبر mobile client ثم API gateway ثم ASP.NET Core ثم database وخدمة خارجية. استخدم W3C Trace Context (traceparent) و OpenTelemetry instrumentation لربط spans. TraceIdentifier الخاص بـ ASP.NET Core مفيد داخل host، لكنه ليس بديلاً كاملاً عن distributed trace propagation. لا تخلط TraceId مع CorrelationId أو UserId؛ كل واحد له purpose مختلف.

في logs، استخدم structured properties مثل route template و status code و duration و trace ID. تجنب raw URL كـ metric label أو query string في logs إذا قد تحتوي PII. فعّل sampling للترايسز وفق volume/cost، لكن حافظ على error traces أو tail-based sampling عند الحاجة. لا تجعل observability نفسها سبباً في overload.

03

Routing واختيار الـ Endpoint

Endpoint routing
Deep dive

Routing مش مجرد استخراج ID من URL. الـ endpoint routing بيحدد أي endpoint ينطبق على method والمسار والقيود والـ metadata، ثم middleware يقدر يقرأ الـ selected endpoint ويطبق authorization أو rate limiting أو غيرهم. الترتيب التفصيلي للـ middleware في درس Middleware.

C#Attribute routing
[ApiController]
[Route("api/products")]
public sealed class ProductsController : ControllerBase
{
    [HttpGet("{id:int}")]
    public ActionResult<ProductResponse> GetById(int id)
        => Ok(new ProductResponse(id, "Keyboard"));

    [HttpGet]
    public ActionResult<IReadOnlyList<ProductResponse>> Search([FromQuery] string? q)
        => Ok(Array.Empty<ProductResponse>());
}

public sealed record ProductResponse(int Id, string Name);

[Route] على مستوى controller يحدد prefix. الـ attribute [HttpGet] و [HttpPost] يحددان HTTP verb، و template مثل {id:int} يضيف route constraint. الـ constraint يساعد في اختيار route، لكنه ليس validation تجاري بديل؛ ما زلت تتحقق إن المنتج موجود وإن المستخدم مسموح له الوصول.

404 أم 405؟

404 Not Found معناها لم يتم العثور على route/resource مناسب وفق السياق. 405 Method Not Allowed معناها المسار معروف لكن HTTP method غير مدعوم لذلك المورد، وقد يصدر معه Allow header.

Filters vs Middleware vs Endpoint Filters

MechanismScopeBest fit
MiddlewareWhole HTTP pipelineException boundary, request correlation, security headers
MVC filtersMVC action/result pipelineController/action-specific behavior
Endpoint filtersMinimal API endpoint invocationShared handler argument/result behavior
Authorization policiesEndpoint/resource access decisionWho may perform an operation

اختار extension point بناءً على المعلومات التي تحتاجها. لو محتاج كل request حتى static files و non-MVC endpoints، استخدم middleware. لو محتاج action arguments أو MVC result، استخدم MVC filter. لو endpoint Minimal API فقط، endpoint filter قد تكون أوضح. لو المشكلة permission، لا تكتب filter يدوياً قبل ما تدرس policy authorization.

04

Controllers و Action Methods

Controller-based APIs
Practical

Controller هو adapter عند حد HTTP، مش المكان المناسب لكل business rules. يرث API controller عادة من ControllerBase، ويحوّل HTTP input إلى استدعاء application service ثم يحوّل النتيجة إلى HTTP response. استخدام Controller يضيف دعم Views؛ أما API فقط فـ ControllerBase أنسب.

C#ProductsController.cs
[ApiController]
[Route("api/products")]
public sealed class ProductsController(IProductQuery query) : ControllerBase
{
    [HttpGet("{id:int}")]
    [ProducesResponseType<ProductResponse>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<ActionResult<ProductResponse>> Get(
        int id, CancellationToken cancellationToken)
    {
        var product = await query.FindAsync(id, cancellationToken);
        return product is null ? NotFound() : Ok(product);
    }
}

public interface IProductQuery
{
    Task<ProductResponse?> FindAsync(int id, CancellationToken cancellationToken);
}
public sealed record ProductResponse(int Id, string Name, decimal Price);

ليه الكود متقسم كده؟

  1. الـ route template يعرّف عنوان المورد.
  2. الـ controller يستقبل CancellationToken المرتبط بالـ request؛ لو العميل قطع الاتصال أو الطلب اتلغى، يقدر العمل التابع يوقف بدوره.
  3. الـ query service تحمل مسؤولية استرجاع البيانات؛ controller لا يعرف EF Core ولا SQL.
  4. ActionResult<T> يعبّر إن النتيجة قد تكون payload من النوع T أو HTTP result زي 404.
  5. Attributes الخاصة بـ response types توثّق contract للـ OpenAPI tooling، لكنها لا تضمن وحدها إن implementation يرجع الحالة فعلاً.

Controller Conventions و ApiController Behavior

[ApiController] يجمع مجموعة conventions مفيدة: attribute routing requirement، inference لمصادر binding في حالات كثيرة، automatic 400 عند invalid ModelState، و Problem Details style errors لبعض الحالات. هذه defaults تقلل boilerplate لكنها لا تلغي فهم binding. Input/output formatters تتعامل مع media types؛ JSON formatter يحوّل DTO إلى JSON والعكس. استخدم [Consumes] و [Produces] عندما تحتاج توضيح supported content types، وليس لمجرد تزيين الكود.

اختَر return shape حسب contract: IActionResult مرن، ActionResult<T> يجمع payload مع HTTP alternatives، و typed result metadata يمكن أن يزيد وضوح OpenAPI. لا ترجع 200 لكل الحالات مع body يحتوي { success:false }؛ status code جزء من protocol ويساعد proxies/clients/monitoring.

تصميم Controller قابل للصيانة

Controller الجيد غالباً يعمل أربع حاجات: يقرأ HTTP input، يطلب use case من application service، يترجم النتيجة إلى HTTP response، ويضيف metadata اللازمة للوثيقة. لو لقيت controller بيحسب خصومات، ويقرر inventory، ويعمل transaction، ويكتب SQL، ويبعث email، فهو بقى مكان business orchestration كله. انقل السلوك إلى service/use-case، وسيب controller boundary adapter.

لا تحوّل كل action إلى method generic واحدة لكل CRUD لمجرد تقليل الأسطر. أسماء العمليات الواضحة مثل ApproveOrder و CancelOrder تعكس business intent أحسن من UpdateStatus إذا كانت القواعد مختلفة. كذلك response DTO ينبغي أن يعبّر عن contract، لا عن كل أعمدة الجدول.

قاعدة عملية

اسأل نفسك عند مراجعة كل action: هل أقدر أفهم HTTP contract من signature والـ attributes؟ هل business rule موجودة في المكان المسؤول عنها؟ هل status codes تمثل الحالات المتوقعة؟ هل cancellation وصل للـ I/O؟

Action Return Types و Cancellation

في controller API عندك خيارات مثل IActionResult و ActionResult<T> و specific typed results. ActionResult<T> مفيد لما success يرجع DTO لكن failure يرجع NotFound/BadRequest. IActionResult مرن لكنه أقل وضوحاً في success schema. لا ترجع entity مباشرة. مرر CancellationToken إلى كل I/O operation؛ العميل قد يغلق الاتصال، ولا معنى لإكمال query مكلفة بعد إلغاء الطلب لو العملية يمكن إيقافها بأمان.

C#Propagate cancellation through layers
[HttpGet("{id:int}")]
public async Task<ActionResult<ProductResponse>> Get(
    int id, CancellationToken cancellationToken)
{
    var result = await query.FindAsync(id, cancellationToken);
    return result is null ? NotFound() : Ok(result);
}

public Task<Product?> FindAsync(int id, CancellationToken token)
    => db.Products.AsNoTracking()
        .SingleOrDefaultAsync(p => p.Id == id, token);

لا تبتلع OperationCanceledException كأنها server failure عادية. وفي background work لا تستخدم RequestAborted كـ lifetime للعمل بعد انتهاء request؛ لو العملية يجب أن تكمل بعد response، انقلها إلى durable job/queue.

Controller Conventions و API Behavior

[ApiController] يفعّل behaviors مهمة مثل automatic 400 عند ModelState invalid، binding source inference، و Problem Details-style client errors حسب إعدادات التطبيق. [Route] يحدد base template، و [HttpGet]/[HttpPost] يحددان verb/template، و [ProducesResponseType] يضيف metadata للـ OpenAPI. دي attributes تصف HTTP contract؛ لا تعتبرها business validation أو authorization في حد ذاتها.

استخدم ActionResult<T> لما success type معروف ومعه عدة HTTP outcomes. IActionResult مناسب لما النتائج متنوعة أو لا يوجد success payload. Task<T> يوضح async execution، و CancellationToken يربط العملية بعمر الطلب. تجنب async void تماماً في actions لأنه يمنع framework من انتظار completion ومعالجة exceptions بشكل صحيح.

Route constraint مثل {id:guid} يمنع string غير صالح من مطابقة route، لكن validation للـ business rules يظل منفصلاً. لو endpoint لا يجد resource بعد binding صحيح، 404 أنسب من 400. ولو caller غير مسموح له، 403 أو 404 حسب disclosure policy.

اختيار Return Type و Testing للـ Controller

Controller action return type يؤثر على وضوح العقد والـ OpenAPI. ActionResult<T> مناسب لما عندك success DTO معروف ومعه نتائج مثل NotFound أو Conflict. IActionResult مرن لكنه لا يوضح schema للنجاح بنفس القوة. لو ترجع DTO مباشرة، framework قد يعمل ObjectResult وفق conventions. خليك consistent داخل API، ووثّق failure responses باستخدام ProducesResponseType أو OpenAPI metadata.

في integration test، استخدم HttpClient من WebApplicationFactory وأرسل HTTP request حقيقي. اختبر route template، method، binding، serialization، status code، content type، headers، authorization، و Problem Details. Unit test للـ controller وحده غالباً لا يختبر framework pipeline؛ في ASP.NET Core الأفضل اختبار service كـ unit واختبار endpoint عبر integration.

C#Test the HTTP contract rather than calling the action
[Fact]
public async Task Get_missing_product_returns_404()
{
    using var client = factory.CreateClient();
    using var response = await client.GetAsync("/api/products/404404");

    Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
    Assert.Equal("application/problem+json",
        response.Content.Headers.ContentType?.MediaType);
}

لو عندك multiple environments، الاختبار لازم يضبط test configuration بوضوح. لا تعتمد على Development-only exception page كأنها production behavior. استخدم test database أو fake service وفق ما تريد اختباره.

مراجعة API Endpoint قبل الـ Merge

اعمل review من منظور client وليس من منظور C#‎ class فقط. هل URL يمثل resource واضح؟ هل method صحيح؟ هل route/query/body/header binding واضح؟ هل request DTO يسمح فقط بالحقول المقصودة؟ هل validation ترجع error contract متوقع؟ هل authentication وال authorization متطبقان؟ هل response status و schema و headers واضحة؟ هل cancellation وصل إلى I/O؟ هل logs مفيدة ولا تحتوي secrets؟ هل integration test يغطي success و failure؟

مثال: endpoint لإنشاء منتج لا ينبغي أن يقبل CreatedByUserId أو IsApproved من العميل. الخادم يستخرج user identity من authenticated principal، ويقرر approval وفق business rules. response 201 تحتوي Location إلى resource الجديدة و DTO public. لو الاسم مكرر، يرجع conflict Problem Details. لو JSON malformed، يرجع 400. لو المستخدم anonymous، يرجع 401 قبل business operation.

هذا النوع من review يكشف أن API ليست مجرد Controller + EF query؛ هي contract، security boundary، operational component، وواجهة versioned بين أنظمة قد تتحدث في أوقات مختلفة.

05

Model Binding: البيانات جاية منين؟

Binding sources and validation boundary
Deep dive

Model binding يقرأ HTTP request ويحاول تكوين parameters أو DTOs من route، query string، headers، form fields، أو request body. في Controller APIs مع [ApiController]، framework يقدر يستنتج binding source من نوع parameter واسم route، لكن الأفضل التصريح بـ [FromRoute] و [FromQuery] و [FromBody] في العقود المهمة لتقليل الالتباس.

C#Explicit binding sources
[HttpGet("{id:int}")]
public IActionResult Get(
    [FromRoute] int id,
    [FromQuery] bool includeInactive = false,
    [FromHeader(Name = "X-Client-Version")] string? clientVersion = null)
    => Ok(new { id, includeInactive, clientVersion });

[HttpPost]
public IActionResult Create([FromBody] CreateProductRequest request)
    => CreatedAtAction(nameof(Get), new { id = 42 }, new { id = 42 });

public sealed record CreateProductRequest(string Name, decimal Price);

قاعدة مهمة: HTTP request body غالباً يُقرأ مرة واحدة، لذلك لا تصمم action فيها أكثر من complex parameter يتنافس على نفس body. استخدم DTO واحداً واضحاً. ملفات الرفع تستخدم IFormFile و multipart/form-data، وسنفصل قواعدها في جزء Web API الثاني.

Binding و validation مرحلتان مختلفتان: binding يحاول تحويل القيمة (مثل النص "abc") إلى int؛ validation يختبر هل القيمة الناتجة مقبولة (مثل Price أكبر من صفر). [ApiController] يعيد 400 تلقائياً عند ModelState invalid في السيناريو المعتاد، قبل دخول action.

Model Binding: كل قيمة جت منين؟

Model binding هو تحويل HTTP representation إلى ‎.NET parameters/objects. مصادر شائعة: route values، query string، headers، form fields، request body، و DI services. اختيار المصدر جزء من contract؛ لو endpoint يستقبل id من route و page من query، صرّح ده عندما يكون inference غير واضح أو لما تقرأ signature وتحتاج تفهمها فوراً.

AttributeSourceExample
[FromRoute]Route template/products/42
[FromQuery]Query string?page=2
[FromHeader]HTTP headerX-Tenant
[FromBody]Serialized bodyJSON document
[FromForm]Form/multipart fieldsUpload metadata
[FromServices]DI containerApplication service
C#Explicit binding makes the HTTP contract visible
[HttpGet("{id:int}")]
public Task<ActionResult<ProductResponse>> Search(
    [FromRoute] int id,
    [FromQuery] string? term,
    [FromHeader(Name = "X-Client-Version")] string? clientVersion,
    [FromServices] IProductQuery query,
    CancellationToken cancellationToken)
{
    return SearchCore(id, term, clientVersion, query, cancellationToken);
}

ما ينفعش تقرأ نفس request body كذا مرة من غير buffering مقصود؛ body stream غالباً forward-only. خلي عندك DTO واحد للـ JSON body، وتجنب قبول entity كاملة. الـ binding يثبت إن القيمة قابلة للتحويل لنوع ‎.NET، لكنه لا يثبت إنها business-valid: الرقم 42 قابل للتحويل لـ int حتى لو المنتج غير موجود.

Validation مش authorization

Validation تسأل: هل input صحيح؟ Authorization تسأل: هل هذا المستخدم مسموح له يعمل العملية على هذا المورد؟ وجود CustomerId صحيح شكلياً لا يعني إن العميل الحالي يملك هذا الـ customer. لازم تربط قرار الوصول بهوية المستخدم و resource ownership، مش بمجرد صحة القيمة القادمة من العميل.

Binding ثم Validation ثم Action: مثال تتبّع كامل

تخيل request إلى POST /api/products?notify=true والـ JSON body يحتوي name و price. Routing يختار action المطابقة للـ POST. Model binding يقرأ query parameter notify ويحوّل النص true إلى bool، ويقرأ JSON body إلى CreateProductRequest. Validation تفحص Required/Range/Length وتملأ ModelState. مع ApiController، invalid ModelState يؤدي إلى 400 قبل دخول action غالباً. لو valid، action تستدعي application service، ثم result executor يحول DTO إلى JSON ويحدد status.

لو body JSON malformed، فشل parsing يحدث قبل business logic. لو price = -5 قابل للتحويل إلى decimal لكنه غير valid، validation ترفضه. لو price = 100 valid شكلياً لكن user لا يملك permission لإنشاء product في tenant، authorization/business rule ترفضه. التمييز بين parsing و validation و business rule و authorization يجعل status codes والتصميم أوضح.

C#Request DTO with boundary constraints
public sealed record CreateProductRequest(
    [property: Required, StringLength(120, MinimumLength = 2)] string Name,
    [property: Range(typeof(decimal), "0.01", "999999.99")] decimal Price,
    [property: Required, StringLength(3, MinimumLength = 3)] string Currency);

Attributes تتحقق من input shape، لكن لا تضع فيها كل business logic. الـ validator يمكنه التحقق من currency allow-list، والـ domain يضمن invariants، والـ database تضمن foreign keys/unique constraints تحت concurrency.

Response Serialization و Content-Type

بعد action result، framework يختار formatter/serializer ويكتب response. JSON options تؤثر على property naming، enums، nulls، dates، converters، reference handling. API clients تعتمد على هذه التفاصيل حتى لو لم تكتبها في controller. تجنب global serialization changes من غير contract review، ولا تستخدم polymorphic serialization على public DTOs إلا لو discriminator schema موثق ومختبر.

HTTP status code يحدد outcome، و Content-Type يحدد representation، و headers مثل Location/ETag/Cache-Control تضيف semantics. POST create غالباً 201 Created مع Location إلى resource الجديدة؛ PUT قد يرجع 200 مع representation أو 204 بلا body؛ DELETE قد يرجع 204 عند نجاح الحذف. اختار contract واحداً متسقاً ووثّقه.

06

Configuration و Options Pattern

Strongly typed configuration
Practical

اقرأ الإعدادات مرة عبر typed options بدل تكرار string keys في كل service. IOptions<T> مناسب للإعداد الثابت بعد بدء التطبيق، و IOptionsSnapshot<T> scoped ويعيد snapshot لكل request، و IOptionsMonitor<T> يدعم مراقبة التغييرات في المصادر التي تدعم reload. لا تفترض أن كل provider قابل لإعادة التحميل.

C#Options registration and consumption
public sealed class InventoryOptions
{
    public const string SectionName = "Inventory";
    public int LowStockThreshold { get; init; } = 5;
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOptions<InventoryOptions>()
    .BindConfiguration(InventoryOptions.SectionName)
    .Validate(o => o.LowStockThreshold >= 0, "Threshold cannot be negative.")
    .ValidateOnStart();

public sealed class StockAlertService(IOptions<InventoryOptions> options)
{
    public bool IsLow(int quantity) => quantity <= options.Value.LowStockThreshold;
}

ValidateOnStart() يمنع تشغيل التطبيق بإعدادات غير صالحة بدلاً من اكتشاف المشكلة عند أول request. في التطبيقات ذات الخيارات المعقدة استخدم IValidateOptions<T> أو validation متخصصة، ولا تخزن secrets داخل object قد يظهر في logs.

Configuration و Options Pattern من غير قيم عشوائية

ASP.NET Core يجمع configuration من providers. في القالب المعتاد JSON files ثم environment variables ثم command-line، والأولوية النهائية تتحدد بترتيب providers المضافة. لذلك لا تفترض أن appsettings.json هي القيمة النهائية. استخدم strongly typed options بدل قراءة strings في أماكن كثيرة، وطبّق validation عند startup حتى يفشل التطبيق مبكراً لو configuration ناقصة.

C#Typed options with startup validation
public sealed class PaymentOptions
{
    public const string SectionName = "Payment";
    public string BaseUrl { get; init; } = "";
    public int TimeoutSeconds { get; init; }
}

builder.Services
    .AddOptions<PaymentOptions>()
    .BindConfiguration(PaymentOptions.SectionName)
    .Validate(o => Uri.TryCreate(o.BaseUrl, UriKind.Absolute, out _),
        "Payment:BaseUrl must be an absolute URI.")
    .Validate(o => o.TimeoutSeconds is >= 1 and <= 60,
        "TimeoutSeconds must be between 1 and 60.")
    .ValidateOnStart();

الـ Options validation تمنع التطبيق من استقبال traffic بإعدادات غير صالحة. لكن لا تضع API keys أو passwords في appsettings committed. استخدم User Secrets في development و secret store أو environment injection في production، وامنع طباعة configuration كاملة في logs.

Environment و Secrets و Options Validation

Environment name يغيّر configuration file والـ developer exception behavior، لكنه ليس security control. أي user قد يزور endpoint لو لم تضف authorization. Secrets لا تحفظها في repository. User Secrets local development convenience وليست encrypted production vault؛ في production استخدم managed secret store أو deployment secret injection. لا تطبع configuration objects كاملة في log لأن فيها احتمال secrets.

Options validation عند startup أفضل من اكتشاف config error عند أول payment request. تحقق من absolute URLs، timeout range، required credentials presence، allowed hostnames، و connection string format. لا تتحقق من secret value نفسها في log أو exception message.

Configuration Providers و Secrets

Configuration abstraction تسمح للكود يقرأ قيمة واحدة بغض النظر عن مصدرها. مصادر شائعة: appsettings.json، appsettings.{Environment}.json، User Secrets في development، environment variables، command-line، و external secret/config providers. ترتيب إضافة providers يحدد precedence؛ القيمة التي تأتي لاحقاً غالباً تتغلب على السابقة. في environment variables تستخدم double underscore لتمثيل hierarchy مثل Payment__TimeoutSeconds.

خلي configuration strongly typed عبر Options، وفرق بين IOptions و IOptionsSnapshot و IOptionsMonitor وفق lifetime/update needs. IOptions قيمة مناسبة غالباً للثابتة، Snapshot scoped، Monitor singleton-friendly ويدعم change notifications لبعض providers. لا تستخدم Monitor لتدوير secret تلقائياً إلا لو provider/consumer مصممين لذلك. والأهم: لا تضع secrets في Git أو logs أو screenshots.

07

Logging: سجّل أحداثاً قابلة للتحليل

Structured logging
Practical

الـ logging الاحترافي مش تجميع strings. استخدم message templates ثابتة وحقول منفصلة حتى تقدر تعمل query حسب ProductId أو Outcome. مستويات شائعة: Trace/Debug للتشخيص، Information للأحداث الطبيعية المهمة، Warning لحدث غير متوقع لكنه متعافى منه، Error لفشل عملية، Critical لفشل خطير يحتاج تدخل.

C#Structured logs with ILogger
public sealed class InventoryService(ILogger<InventoryService> logger)
{
    public void Reserve(int productId, int quantity)
    {
        using var scope = logger.BeginScope(new Dictionary<string, object>
        {
            ["ProductId"] = productId
        });

        logger.LogInformation("Reserving {Quantity} units", quantity);
        if (quantity <= 0)
        {
            logger.LogWarning("Rejected invalid reservation quantity {Quantity}", quantity);
            throw new ArgumentOutOfRangeException(nameof(quantity));
        }
    }
}

لا تسجل passwords أو bearer tokens أو raw payment details أو request bodies الحساسة. استخدم correlation/trace identifiers لربط logs بالـ trace؛ تفاصيل OpenTelemetry والتنسيق المتقدم داخل part 2 ودرس Observability لاحقاً.

Logging: إزاي تفهم اللي حصل في Request؟

Logging في backend مش مجرد Console.WriteLine. الهدف إنك تقدر تجاوب: مين عمل request؟ على أي endpoint؟ انتهت بإيه؟ استغرقت قد إيه؟ ولو فشلت، إيه exception type والـ dependency اللي فشلت؟ استخدم structured logging بحيث القيم تبقى properties مستقلة، مش string واحدة صعب تبحث فيها.

C#Structured logging in an application service
public sealed class ProductService(
    IProductRepository repository,
    ILogger<ProductService> logger)
{
    public async Task<Product?> FindAsync(int id, CancellationToken token)
    {
        logger.LogDebug("Looking up product {ProductId}", id);
        var product = await repository.FindAsync(id, token);

        if (product is null)
            logger.LogInformation("Product {ProductId} was not found", id);
        else
            logger.LogDebug("Product {ProductId} loaded", id);

        return product;
    }
}

الـ placeholder {ProductId} property name، والقيمة تتخزن كـ structured field عند provider يدعم ذلك. تجنب interpolation مثل $"Product {id}" في logging hot paths لأنه يبني string حتى لو log level disabled، ويصعّب تحليل fields. اختار log level: Trace/Debug للتفاصيل، Information للأحداث التشغيلية المهمة، Warning لحالة غير متوقعة لكن التطبيق تعامل معها، Error لفشل عملية، Critical لفشل خطير على النظام.

لا تسجل passwords، bearer tokens، cookies، connection strings، payment card data، أو request body كاملة بشكل افتراضي. الـ correlation/trace ID يربط logs بطلب واحد؛ distributed trace يربط spans عبر services. لا تعتبر correlation ID دليلاً على هوية العميل.

08

ملخص واختبار الفهم

Knowledge check
Basics
  • ASP.NET Core يهيئ Host و DI و Configuration و Logging قبل استقبال الطلبات.
  • الـ middleware pipeline يحيط باختيار وتنفيذ endpoint.
  • Controller هو HTTP adapter؛ لا تضع داخله كل business logic.
  • Model binding يحوّل مصادر HTTP إلى parameters؛ validation تختبر صحة المدخلات.
  • Options و structured logging يخليان configuration والرصد أكثر انضباطاً.
طلب GET /api/products/12 وصل إلى Controller، لكن قاعدة البيانات لا تحتوي المنتج. ما status الأنسب؟
404 Not Found؛ لأن route صحيح لكن المورد غير موجود. لا تستخدم 400 لمجرد أن القيمة 12 صالحة شكلياً.
لماذا نمرر CancellationToken من action إلى service؟
حتى ينتقل إلغاء الطلب إلى العمليات التابعة (مثل database/network I/O) بدلاً من الاستمرار في شغل لم يعد له consumer.
هل [ApiController] يغني عن business validation؟
لا. هو يساعد في binding و ModelState validation، لكن قواعد مثل صلاحية السعر أو ملكية المورد تظل مسؤولية domain/application.
أين تضع secret API key؟
في secret store أو environment-specific secret injection، لا في source control ولا logs.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapRequest/Response Lifecycle§01
RoadmapRequest Pipeline§02
RoadmapMiddleware§03
RoadmapRouting§03
RoadmapControllers and Action Methods§04
RoadmapModel Binding and Validation§05
RoadmapDependency Injection and Service Lifetimes§08
RoadmapConfiguration and Options Pattern§02
RoadmapLogging§07
RoadmapEnvironment Management§02

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس