ASP.NET Core و MVC

#MVC واختيار شكل الواجهةMVC and choosing an application model

لو Controller بيعمل SQL ويحسب discounts ويبني HTML، تغييره واختباره هيبقوا صعبين. MVC يفصل التنسيق عن business behavior وعن العرض.

// IProductService and ProductViewModel are application types.
public sealed class ProductsController(IProductService products) : Controller
{
    public async Task<IActionResult> Details(int id, CancellationToken ct)
    {
        var product = await products.GetAsync(id, ct);       // (1)
        if (product is null) return NotFound();
        return View(product);                              // (2)
    }
}

اختار حسب الفريق والـ UI والـ conventions المطلوبة؛ Minimal API مش معناها كل التطبيق في Program.cs، و MVC مش معناها architecture كاملة.

#Kestrel و IIS و reverse proxyKestrel, IIS and reverse proxies

التطبيق محتاج HTTP server، والتشغيل قدام الإنترنت محتاج قرارات TLS و routing و limits. Kestrel server cross-platform؛ ممكن يبقى edge server مباشرةً أو ورا proxy زي Nginx أو YARP.

Client -> optional CDN/WAF -> reverse proxy -> Kestrel -> pipeline

IIS in-process:     IIS -> ASP.NET Core Module -> IIS HTTP Server -> app
IIS out-of-process: IIS -> ASP.NET Core Module -> Kestrel -> app

using Microsoft.AspNetCore.HttpOverrides;
using System.Net;

// Before Build; replace this address with the trusted proxy's address.
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor
        | ForwardedHeaders.XForwardedProto;                // (1)
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.10")); // (2)
});
// Early in the pipeline, before HTTPS redirection:
app.UseForwardedHeaders();                                 // (3)

IIS in-process مش بيستخدم Kestrel لاستقبال requests. Reverse proxy يفيد في TLS termination والـ load balancing، لكنه مش شرط لتشغيل Kestrel بأمان لو متظبط صح. راعي body size و timeouts في كل طبقة.

#Request pipeline و custom middleware و Use و Run و MapPipeline order, custom middleware, Use, Run and Map

كل middleware ممكن تعمل شغل قبل next وبعده، أو توقف السلسلة. الترتيب هو nesting: الـ response بيرجع عكس اتجاه الدخول، والـ exception handler يقدر يمسك أخطاء اللي بعده بس.

Forwarded headers -> exception handler -> HSTS/HTTPS -> static files
  -> routing -> CORS -> authentication -> rate limiter -> authorization
  -> endpoint -> response unwinds through executed middleware

Use: may call next; Run(RequestDelegate): terminal handler
Map("/path", branch): branch pipeline
MapGet / MapControllers: register endpoints, not the same branching API

public sealed class RequestLogMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext context,
        ILogger<RequestLogMiddleware> log)
    {
        var started = Stopwatch.GetTimestamp();             // (1)
        try { await next(context); }                        // (2)
        finally
        {
            double ms = Stopwatch.GetElapsedTime(started).TotalMilliseconds;
            log.LogInformation("Request {TraceId} ended after {ElapsedMs} ms",
                context.TraceIdentifier, ms);               // (3)
        }
    }
}

// Required CORS, authentication, authorization and limiter services are registered.
app.UseExceptionHandler();
app.UseMiddleware<RequestLogMiddleware>();
if (!app.Environment.IsDevelopment()) app.UseHsts();
app.UseHttpsRedirection();
app.UseRouting();
app.UseCors("storefront");
app.UseAuthentication();
app.UseRateLimiter();                                       // (4)
app.UseAuthorization();
app.MapControllers();

Conventional middleware constructor عمره طويل؛ خد scoped dependencies في InvokeAsync، أو استخدم IMiddleware بتسجيل مناسب. app.Run() اللي من غير delegate بيبدأ host؛ غير Run(handler) اللي بيوقف pipeline. Static files لو قبل auth بتبقى public؛ احمِ المحتوى الخاص بمسار مناسب.

#Routing و model binding: الطلب يوصل لمين والداتا منين؟Routing and binding: destination and input sources

Routing يختار endpoint؛ model binding يحوّل request values لـ parameters. Constraint زي int بيحدد route match، مش رسالة validation لمدخلات المستخدم.

// Conventional routing for controllers with views:
app.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");

// Attribute routing; IOrderService and UpdateOrder are application types.
[ApiController]
[Route("api/orders")]
public sealed class OrdersController(IOrderService orders) : ControllerBase
{
    [HttpPut("{id:int}")]
    public async Task<IActionResult> Update(
        [FromRoute] int id,                              // (1)
        [FromQuery] bool notify,
        [FromHeader(Name = "Idempotency-Key")] string? key,
        [FromBody] UpdateOrder request,                  // (2)
        CancellationToken ct)
    {
        await orders.UpdateAsync(id, request, notify, key, ct);
        return NoContent();
    }
}

// Minimal API grouping:
var group = app.MapGroup("/api/products").RequireAuthorization();
group.MapGet("/{id:int}", (int id) => TypedResults.Ok(new { Id = id }));

[ApiController] يعمل inference حسب النوع والـ route وتسجيل DI؛ explicit attributes مفيدة لما المصدر مهم. Minimal APIs ليها binding rules خاصة زي TryParse و BindAsync، مش MVC model binders. /orders/abc مش هيطابق {id:int} فيرجع غالباً 404، بينما conversion failure بعد match ممكن يبقى 400. Constraints مش بديل عن range checks.

#Validation و filters و Minimal APIs في .NET 10Validation, filters and .NET 10 Minimal APIs

Binding يجاوب «الداتا اتقرت؟»، validation يجاوب «شكلها مقبول؟»، والـ domain يجاوب «العملية مسموحة دلوقتي؟». Stock availability لازم يتراجع مع update آمن، مش annotation على request.

// .NET 10 Web project; package: Microsoft.Extensions.Validation.
using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddValidation();                         // (1)
var app = builder.Build();
app.MapPost("/products", (CreateProduct request) =>
    TypedResults.Created("/products/1", request));         // (2) illustrative id
app.Run();

public sealed class CreateProduct
{
    [Required, StringLength(200)]
    public string Name { get; set; } = "";
    [Range(0.01, 1_000_000)]
    public decimal Price { get; set; }
}

Action filters بتشوف arguments بعد binding؛ resource filters بتشتغل قبل binding. Exception filters مش بتغطي كل middleware أو response-writing failures. لو concern عام زي logging أو global errors، middleware غالباً أنسب. مرجع validation؛ راجع metadata discovery للأنواع في assemblies تانية.

#Results و status codes و response contractsResults, status codes and response contracts

HTTP response مش JSON بس؛ status و headers جزء من contract. خلي نوع return يوضح احتمالات النجاح والفشل بدل 200 لكل حاجة.

using Microsoft.AspNetCore.Http.HttpResults;

// IOrderReader and OrderDto are application types registered with DI.
app.MapGet("/orders/{id:int}",
    async Task<Results<Ok<OrderDto>, NotFound>>
    (int id, IOrderReader reader, CancellationToken ct) =>
    {
        var order = await reader.GetAsync(id, ct);          // (1)
        return order is null
            ? TypedResults.NotFound()
            : TypedResults.Ok(order);                      // (2)
    });

IActionResult مرن لنتائج MVC مختلفة؛ ActionResult<T> يضيف success type. وثّق failure responses كمان، وماترجعش EF entities مباشرةً.

فرّق 202 عن اكتمال العملية. 401 عادةً challenge ومعاه WWW-Authenticate حسب scheme؛ 403 forbid. اختار سياسة ثابتة للـ business errors بدل حفظ status لكل exception.

#DI lifetimes و captive dependencies و keyed servicesDI lifetimes, captive dependencies and keyed services

DI مش بس بديل لـ new؛ هو كمان إدارة ownership و lifetime. Service طويلة العمر لو احتفظت بحاجة قصيرة العمر، ممكن تشارك state بين requests بالغلط.

// Application types: IPaymentProvider, CardProvider and WalletProvider.
builder.Services.AddKeyedScoped<IPaymentProvider, CardProvider>("card");
builder.Services.AddKeyedScoped<IPaymentProvider, WalletProvider>("wallet"); // (1)

app.MapPost("/payments/card",
    ([FromKeyedServices("card")] IPaymentProvider provider) =>
        TypedResults.Ok(provider.Name));                   // (2)

// A singleton's unit of work, not a singleton-held DbContext:
await using var scope = scopeFactory.CreateAsyncScope();   // (3)
var work = scope.ServiceProvider.GetRequiredService<IOrderWork>();
await work.ExecuteAsync(ct);

Captive dependency زي singleton ماسك DbContext scoped. ValidateScopes يكشف مخالفات كتير لما scope validation مفعّل؛ شغّل validation في اختبارات startup كمان. Transient داخل singleton ممكن يعيش معاه فعلياً. الـ container يتصرف في disposables اللي يملكها؛ متقفلش injected service عشوائياً ولا تعمل BuildServiceProvider جوه التسجيلات.

#Configuration و options و environments و secretsConfiguration, options, environments and secrets

قيم deployment مختلفة مش سبب لنسخ config متناثرة أو passwords في Git. اجمع الإعدادات في options typed، وافشل بدري لو ناقصة.

Default application configuration, low -> high priority:
appsettings.json -> appsettings.{Environment}.json
  -> User Secrets in Development -> environment variables -> command-line

Later added providers can override earlier values.
Payments__ApiKey maps to Payments:ApiKey.

public sealed class PaymentOptions
{
    [Required] public string ApiKey { get; set; } = "";
    [Range(1, 60)] public int TimeoutSeconds { get; set; } = 10;
}

// Before Build; DataAnnotations attributes need their namespace.
builder.Services.AddOptions<PaymentOptions>()
    .BindConfiguration("Payments")                          // (1)
    .ValidateDataAnnotations()
    .ValidateOnStart();                                     // (2)

Environment زي Development أو Staging أو Production بيختار ملف settings وسلوك debug؛ مش security boundary. في WebApplicationBuilder لو DOTNET_ENVIRONMENT و ASPNETCORE_ENVIRONMENT الاتنين متحددين، DOTNET_ENVIRONMENT ليه الأولوية؛ تجنب التعارض. User Secrets للتطوير خارج Git، مش encrypted vault. في production استخدم secret store أو injection مناسب؛ environment variables مش تشفير.

#IExceptionHandler و ProblemDetails و structured loggingIExceptionHandler, ProblemDetails and structured logging

تكرار try/catch في كل action بيطلع errors غير متسقة، وممكن يكشف stack traces. خلي expected outcomes results، والأخطاء غير المتوقعة ليها handler عام و trace id يربط الرد بالـ logs.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

// Before Build:
builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalErrors>();       // (1)
// After Build, early: app.UseExceptionHandler();

public sealed class GlobalErrors(ILogger<GlobalErrors> log) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext context,
        Exception exception, CancellationToken ct)
    {
        log.LogError(exception, "Unhandled request {TraceId}",
            context.TraceIdentifier);                     // (2)
        context.Response.StatusCode = 500;
        await context.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = 500,
            Title = "An unexpected error occurred.",
            Extensions = { ["traceId"] = context.TraceIdentifier }
        }, contentType: "application/problem+json", cancellationToken: ct); // (3)
        return true;                                      // (4)
    }
}

لو response بدأ، مش دايماً تقدر تغيّر status أو body. تعامل مع request cancellation كحالة متوقعة حسب السياق. في .NET 10 diagnostics الافتراضية للـ exceptions اللي handler رجّع لها true بتتسكت افتراضياً؛ لو محتاج logging اعمله بقرار واضح زي المثال ومن غير تكرار. Logging levels: Trace، و Debug، و Information، و Warning، و Error، و Critical؛ ماتسجّلش tokens أو card data. مرجع errors.

#CORS و preflight و rate limiting و health checksCORS, preflight, rate limits and health checks

Browser محتاج إذن يقرا response من origin تاني؛ API محتاجة كمان تحد الاستخدام وتعلن readiness. دول تلات concerns مختلفة ومش بدائل عن authentication.

using System.Threading.RateLimiting;
using Microsoft.AspNetCore.Diagnostics.HealthChecks;

builder.Services.AddCors(o => o.AddPolicy("storefront", p => p
    .WithOrigins("https://shop.example.com")
    .WithMethods("GET", "POST")
    .WithHeaders("Content-Type", "Authorization")));       // (1)
builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddFixedWindowLimiter("browse", p =>
    {
        p.PermitLimit = 100;
        p.Window = TimeSpan.FromMinutes(1);
        p.QueueLimit = 0;
    });                                                    // (2)
});
builder.Services.AddHealthChecks();                        // (3)

// After Build; install CORS and rate-limiting middleware as shown earlier.
app.MapGet("/catalog", () => TypedResults.Ok("Catalog"))
    .RequireRateLimiting("browse");
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false                                 // (4)
});
app.MapHealthChecks("/health/ready");

CORS browser policy، و curl مش ملتزم بيها؛ مش حماية CSRF. لو cookie credentials مطلوبة، استخدم AllowCredentials مع origins محددة، مش wildcard. Limiter جوه process مش quota موزّعة ولا DDoS defense كامل؛ gateway ينظم المستوى المشترك. ماتخليش dependency outage يعمل restart لكل instances بسبب liveness، وماتكشفش health details للعامة.

#HttpClient و resilience: حدود الوقت وإعادة المحاولةHttpClient and resilience: time budgets and retries

إنشاء client و handler جديد لكل call ممكن يضيّع connection reuse ويضغط sockets. Factory بيفصل عمر client عن handlers، ويسهّل config و resilience.

// Package: Microsoft.Extensions.Http.Resilience.
using Microsoft.Extensions.Http.Resilience;

builder.Services.AddHttpClient<CatalogClient>(http =>
{
    http.BaseAddress = new Uri("https://catalog.example.com/"); // (1)
}).AddStandardResilienceHandler(options =>
{
    options.Retry.DisableForUnsafeHttpMethods();             // (2)
});

public sealed class CatalogClient(HttpClient http)
{
    public Task<ProductDto?> GetAsync(int id, CancellationToken ct) =>
        http.GetFromJsonAsync<ProductDto>($"products/{id}", ct); // (3)
}

Client طويل العمر مع SocketsHttpHandler و PooledConnectionLifetime اختيار صحيح كمان. متحتفظش typed client قصير العمر جوه singleton من غير دراسة DNS و lifetime. ظبّط total budget و per-attempt timeout و retries حسب dependency؛ retry ممكن يكرر payment اتنفذت حتى لو الرد ضاع.

#BackgroundService و durable jobs و deploymentBackgroundService, durable jobs and deployment

شغل زي cleanup أو reconciliation مينفعش يبقى fire-and-forget متعلق بـ request scope. اختار in-process loop للشغل اللي تقدر تعيده، و durable scheduler أو queue لما فقدان الشغل بعد restart غير مقبول.

// IOrderMaintenance is a scoped application service.
public sealed class OrderCleaner(IServiceScopeFactory scopes,
    ILogger<OrderCleaner> log) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromMinutes(10)); // (1)
        try
        {
            while (await timer.WaitForNextTickAsync(stoppingToken))
            {
                try
                {
                    await using var scope = scopes.CreateAsyncScope(); // (2)
                    var work = scope.ServiceProvider
                        .GetRequiredService<IOrderMaintenance>();
                    await work.CleanAsync(stoppingToken);
                }
                catch (Exception ex) when (ex is not OperationCanceledException)
                {
                    log.LogError(ex, "Order cleanup failed");        // (3)
                }
            }
        }
        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
        {
            // Normal shutdown.
        }
    }
}
// Register before Build:
// builder.Services.AddHostedService<OrderCleaner>();

Unhandled ExecuteAsync exception توقف host افتراضياً من .NET 6. في .NET 10 ExecuteAsync كلها بتشتغل في الخلفية؛ ماتعتمدش على الجزء قبل أول await كـ startup barrier. Hangfire يوفر persisted jobs و retries و dashboard؛ Quartz مناسب scheduling ومع persistent store و clustering عند تهيئتهم. مفيش ضمان exactly-once للـ side effects؛ خلّي jobs idempotent.

1. Publish Release كـ framework-dependent أو self-contained، وابنِ artifact ثابت للاختبار والترقية.
2. في container استخدم SDK للبناء و ASP.NET runtime للتشغيل؛ runtime و OS محتاجين patching.
3. مرّر config و secrets لكل environment، واضبط trusted proxies و TLS.
4. شغّل schema migrations بخطوة متحكم فيها، واستخدم تغييرات backward-compatible مع rolling أو blue-green deployment.
5. Readiness قبل traffic، و graceful shutdown و request draining؛ deployment strategy لوحدها مش ضمان zero downtime.