Middleware يعني إيه؟
Middleware component جزء من pipeline يستقبل HttpContext ويقرر: ينفذ logic قبل اللي بعده؟ ينادي الـ next middleware؟ يعدل response بعد رجوعه؟ أو يوقف السلسلة ويرجع response بنفسه؟ التوقيع المفاهيمي هو RequestDelegate(HttpContext) → Task.
لما middleware تعمل await next(context) فهي تسلّم التحكم للي بعدها وتنتظر إكماله. بعد رجوعه تقدر تقيس elapsed time أو تضيف response header، بشرط ألا تكون headers/body أُرسلت بالفعل. الـ pipeline تشبه onion لأن التنفيذ يمر inward ثم يرجع outward.
RequestDelegate و Composition
RequestDelegate هو delegate يمثل وحدة تنفيذ HTTP request: يستقبل HttpContext ويرجع Task. Middleware class أو inline delegate ينتهي في صورة delegate متصل باللي بعده. الـ application builder يجمع القطع في pipeline واحدة. لذلك middleware مش مجرد class فيه method اسمها Invoke؛ المهم إنه يكوّن continuation chain.
public delegate Task RequestDelegate(HttpContext context);
public sealed class TimingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<TimingMiddleware> _logger;
public TimingMiddleware(RequestDelegate next,
ILogger<TimingMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
var started = Stopwatch.GetTimestamp();
await _next(context);
_logger.LogInformation("Request took {Elapsed}",
Stopwatch.GetElapsedTime(started));
}
}الـ next ليس event يطلق كل handlers؛ هو continuation للجزء التالي. استدعاؤه مرة واحدة يمرر الطلب، عدم استدعائه يوقف التنفيذ، واستدعاؤه مرتين غالباً bug لأنه قد ينفذ endpoint أو يكتب response مرتين.
قاعدة next: مرة واحدة أو صفر
Middleware عندها ثلاثة أشكال أساسية: pass-through (تنفذ قبل وبعد next)، short-circuit (ترجع response من غير next)، أو branch (تختار continuation بناءً على condition). لا تستدعي next مرتين في request عادية. لو تحتاج retry downstream، ده ليس مسؤولية middleware عامة؛ أعد تصميم operation/service مع idempotency و retry policy واضحة.
// Pass-through
app.Use(async (context, next) =>
{
var started = Stopwatch.GetTimestamp();
await next();
context.Response.Headers["X-Elapsed-Ms"] =
Stopwatch.GetElapsedTime(started).TotalMilliseconds.ToString("F1");
});
// Short-circuit
app.Use(async (context, next) =>
{
if (context.Request.Path == "/blocked")
{
context.Response.StatusCode = StatusCodes.Status403Forbidden;
return;
}
await next();
});في المثال الأول header بعد next قد يكون متأخراً إذا response بدأ بالفعل؛ استخدم OnStarting عند الحاجة. المثال يوضح pass-through structure، لكن مكان تعديل response يجب أن يراعي commitment boundary.
Trace كامل: قبل next وبعد next
لو عندك middleware A ثم B ثم C ثم endpoint، الدخول يكون A-before ثم B-before ثم C-before ثم endpoint. بعد انتهاء endpoint، الرجوع يكون C-after ثم B-after ثم A-after. ده لأن كل middleware تنتظر Task من next. لو B short-circuit، C وال endpoint لا يعملان، لكن B-after (لو فيه code بعد next) لن يعمل أيضاً لأنه لم يستدع next؛ أما A-after سيعمل بعد رجوع B.
app.Use(async (context, next) =>
{
Console.WriteLine("A before");
await next();
Console.WriteLine("A after");
});
app.Use(async (context, next) =>
{
Console.WriteLine("B before");
await next();
Console.WriteLine("B after");
});
app.Run(context => context.Response.WriteAsync("Endpoint"));Output: A before → B before → Endpoint → B after → A after. لو endpoint يرمي exception، code بعد next لا يصل إليه إلا إذا كان داخل finally؛ exception يصعد للخارج حتى يلتقطه exception handler. استخدم finally للقياس/cleanup الذي يجب أن يعمل عند exception، لكن لا تخفي exception.
Use vs Run vs Map
- Use: يضيف middleware يمكنه استدعاء
nextأو short-circuit. - Run: terminal middleware؛ لا يمرر للذي بعده. أي Use بعده لن يصل إليه branch التنفيذ العادي.
- Map: ينشئ branch بناءً على path prefix (مثلاً
/health-debug)؛ الطلب المطابق يدخل branch منفصل.
var app = builder.Build();
app.Use(async (context, next) =>
{
Console.WriteLine("A before");
await next();
Console.WriteLine("A after");
});
app.Map("/ops", branch =>
{
branch.Run(async context =>
{
await context.Response.WriteAsync("Operations branch");
});
});
app.Run(async context =>
{
await context.Response.WriteAsync("Main terminal handler");
});
app.Run();لو طلبت / هتشوف A before ثم main terminal handler ثم A after. لو طلبت /ops يدخل branch الخاص بالـ Map. تذكر أن app.Run() overload بدون delegate هو الذي يشغّل host، أما app.Run(RequestDelegate) فيضيف terminal middleware.
Map و MapWhen و UseWhen
Map يعمل branch بناءً على path prefix ويزيل prefix من Request.Path داخل branch، بينما MapWhen يسمح predicate على HttpContext. UseWhen يعمل branch شرطياً ثم يرجع إلى main pipeline إذا branch لم ينتهِ بـ terminal middleware. اختار أبسط operator يعبّر عن شرطك.
app.Map("/internal", internalApp =>
{
internalApp.Use(async (context, next) =>
{
context.Response.Headers["X-Branch"] = "internal";
await next();
});
internalApp.Run(context =>
context.Response.WriteAsync("Internal endpoint"));
});
app.UseWhen(context =>
context.Request.Headers.ContainsKey("X-Debug-Mode"), branch =>
{
branch.Use(async (context, next) =>
{
context.Items["DebugRequested"] = true;
await next();
});
});لا تعتبر header مثل X-Debug-Mode authorization signal؛ أي client قد يرسله. branching هدفه composition وليس access control.
Middleware Ordering: الترتيب يغيّر المعنى
Routing يحدد endpoint metadata؛ CORS و authentication و authorization و rate limiting و output caching قد تعتمد على metadata أو user identity. ترتيب خاطئ ممكن يعني authorization غير مطبق، CORS preflight يفشل، أو cache يقدم response غير مناسبة لمستخدم آخر. استخدم ترتيب Microsoft الموصى به، لكن راجع متطلبات كل middleware/policy.
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseCors("Frontend");
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.UseOutputCache();
app.MapControllers();ده مثال توضيحي وليس ترتيباً آلياً لكل تطبيق؛ مثلاً بعض rate limiter policies تحتاج endpoint routing metadata، و Output Cache يجب أن يأتي بعد CORS و routing، ومع auth يجب ألا يسمح cache بمشاركة استجابة محمية. راجع توثيق كل middleware الذي تستخدمه.
ترتيب Middleware: افهم الاعتماد بين الطبقات
Exception handler غالباً يكون مبكراً ليغطي أكبر مساحة. HTTPS redirection قبل endpoint. Static files يمكنها short-circuit، لذلك لو وضعت auth بعدها فلن تحمي الملفات الثابتة. Routing يختار endpoint metadata؛ CORS و authentication و authorization و rate limiting قد تعتمد على metadata أو user. Session و response compression/output caching لها متطلبات ترتيب أيضاً. لا تنسخ قائمة ترتيب من مقال قديم من غير مراجعة middleware التي أضفتها.
اختبر الترتيب بحالات ملموسة: preflight OPTIONS، anonymous request، authenticated user بلا permission، endpoint عليه rate-limit policy، exception من endpoint، static file، و response cache مع user-specific data. اختبار happy path وحده لا يكشف أخطاء الترتيب.
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseRouting();
app.UseCors("Spa");
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.MapControllers();ده ترتيب شائع، وليس recipe لكل application. مثال: rate limiter الذي يعتمد على endpoint metadata يحتاج routing قبله. راجع docs لكل middleware، خاصة output caching و static files و session.
اختبار ترتيب Pipeline عملياً
اعمل endpoints اختبارية بسيطة: واحد يرجع 200، واحد يرمي exception، واحد محمي authorization، واحد CORS preflight، واحد static file، وواحد rate-limited. راقب response headers/status و logs. لو عندك middleware custom، اختبر short-circuit branch و normal branch و downstream exception و cancellation.
أخطاء شائعة: وضع static files قبل authorization ثم توقع حماية الملفات؛ وضع authentication بعد authorization؛ إضافة CORS بعد endpoint execution؛ أو كتابة response header بعد body بدأ. الاختبار end-to-end يكشف هذه الأخطاء أسرع من قراءة Program.cs فقط.
Middleware Ordering: سيناريوهات واقعية
Scenario 1 — CORS preflight: browser يرسل OPTIONS قبل POST؛ لو CORS middleware في موضع لا يرى endpoint metadata أو بعد authorization بشكل غير مناسب، قد يرجع 401/404 قبل CORS headers. Scenario 2 — Static files: static file middleware قد تنهي request فوراً؛ middleware بعدها لن تعمل على هذه الملفات. Scenario 3 — Authorization: UseAuthentication يملأ User، و UseAuthorization يقرأه ويطبق policy؛ عكس الترتيب يجعل القرار لا يرى identity كما تتوقع. Scenario 4 — Rate limiting: endpoint-specific policies تحتاج routing metadata. Scenario 5 — Exception handling: handler يجب أن يحيط بالطبقات التي تريد التقاط exceptions منها.
لا تحفظ ترتيباً كقائمة جامدة. اقرأ docs الخاصة بالـ middleware، افهم هل تحتاج endpoint metadata أو authenticated user أو response body، ثم اختبر الحالات السابقة. في application كبيرة، اكتب تعليقاً قصيراً حول ترتيب غير واضح بدلاً من تركه magic.
Decision Matrix للـ Pipeline
| Need | Best starting point | Why |
|---|---|---|
| Catch unhandled HTTP exceptions | Exception middleware | Wraps broad pipeline |
| Correlation ID / security header | Middleware | Applies across endpoint types |
| Inspect MVC action arguments | MVC action filter | Runs in MVC action pipeline |
| Inspect Minimal API handler args | Endpoint filter | Endpoint-specific scope |
| Decide access to a resource | Authorization handler/use case | Needs user + resource context |
| Execute business operation | Application service | Should be framework-independent |
الـ decision matrix دي تمنع middleware تتحول إلى God component. كل concern له owner. لو component بدأت تعرف تفاصيل Order/Payment/Customer، غالباً business logic خرجت من مكانها. ولو service بدأت تعدّل response headers، غالباً HTTP concern تسربت إليها.
مراجعة ترتيب Pipeline كتمرين
افترض أن endpoint عليها [Authorize] و CORS policy و rate-limit policy، وعايز exception response Problem Details. اسأل: هل exception handler يحيط بالـ pipeline؟ هل routing سبق policies التي تحتاج metadata؟ هل authentication سبق authorization؟ هل CORS يستطيع الرد على preflight؟ هل rate limiter يرى endpoint policy؟ هل endpoint map موجود بعد تسجيل middleware المناسبة؟ ارسم flow للـ normal request ولـ OPTIONS preflight ولـ anonymous request، ثم اختبر كل واحد.
لو أضفت middleware جديدة، اكتب سبب موضعها. «حطيتها هنا لأن docs تقول كده» بداية، لكن الفهم الحقيقي هو dependency: هل تحتاج user identity؟ endpoint metadata؟ body قبل model binding؟ response قبل commitment؟
كتابة Custom Middleware
public sealed class CorrelationMiddleware(RequestDelegate next)
{
private const string Header = "X-Correlation-ID";
public async Task InvokeAsync(HttpContext context, ILogger<CorrelationMiddleware> log)
{
var supplied = context.Request.Headers[Header].FirstOrDefault();
var correlationId = Guid.TryParse(supplied, out var parsed)
? parsed.ToString("N")
: Guid.NewGuid().ToString("N");
context.TraceIdentifier = correlationId;
context.Response.OnStarting(() =>
{
context.Response.Headers[Header] = correlationId;
return Task.CompletedTask;
});
using (log.BeginScope(new Dictionary<string, object>
{
["CorrelationId"] = correlationId
}))
{
log.LogInformation("HTTP {Method} {Path} started",
context.Request.Method, context.Request.Path);
await next(context);
}
}
}
// Registration:
app.UseMiddleware<CorrelationMiddleware>();Trace
- اقرأ correlation id من header، لكن لا تثق بأي قيمة arbitrary كـ GUID إذا كنت تستخدمه في log indexing أو storage؛ هنا نقيّد الشكل.
- لو لا توجد قيمة صالحة، أنشئ واحدة.
OnStartingيضمن إضافة response header قبل إرسال headers.- BeginScope يضيف field لكل logs داخل scope.
await nextيستدعي بقية pipeline، ثم يخرج scope بعد رجوع الاستجابة.
في نظام موزع، استخدم W3C Trace Context و OpenTelemetry بدلاً من اختراع tracing protocol كامل. Correlation ID هو helpful identifier لكنه ليس security token، ولا تستخدمه لإثبات هوية client.
Conventional Middleware vs IMiddleware
Conventional middleware يتكون عادة عند بناء pipeline؛ constructor injection فيه مناسب لخدمات متوافقة مع عمر middleware. لو احتجت scoped dependency مثل DbContext، لا تحقنها في constructor التقليدي الذي يعيش طوال عمر التطبيق. تقدر تحقنها في InvokeAsync parameter، أو تطبق IMiddleware وتسجل implementation في DI فينشأ وفق lifetime المسجل.
public sealed class TenantAuditMiddleware(
IAuditWriter auditWriter) : IMiddleware
{
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
await next(context);
await auditWriter.WriteAsync(
context.TraceIdentifier,
context.Response.StatusCode,
context.RequestAborted);
}
}
builder.Services.AddScoped<TenantAuditMiddleware>();
app.UseMiddleware<TenantAuditMiddleware>();لو audit لازم يحصل حتى لو endpoint رمى exception، ضع try/finally حول next. لكن انتبه أن audit write نفسه قد يرمي exception ويغطي على exception الأصلي؛ قرر هل audit failure fail-open أم fail-closed حسب متطلبات النظام.
قواعد تصميم Middleware Production-ready
Middleware الجيدة تكون focused، سريعة، وتتعامل مع cancellation و exceptions بوضوح. لا تعمل network call synchronous لكل request. لا تقرأ body أو response بالكامل لمجرد logging. لا تحفظ request-specific data في static fields. لا تعتمد على request headers كهوية موثوقة. لا تضف global mutable state بدون concurrency control.
لو middleware تعمل cache lookup أو tenant resolution، حدد timeout/failure behavior. هل لو tenant provider وقع ترجع 503 أم تسمح anonymous? قرار security-sensitive لازم يكون fail-closed غالباً. لو middleware تضيف correlation ID، استخدم W3C Activity/trace context إن أمكن بدلاً من بروتوكول custom لا يتكامل مع tracing ecosystem.
لا تسجل raw query string بالكامل إذا ممكن تحمل token أو PII. اعمل redaction للـ sensitive headers. Logging middleware قد تتعامل مع آلاف requests في الثانية؛ أي allocation/serialization فيها يتضاعف مع throughput.
قرار عملي: Middleware ولا Filter؟
- هل concern يجب أن يعمل لكل HTTP request مهما كان endpoint type؟ اختار middleware.
- هل يحتاج MVC action arguments أو ModelState أو result؟ اختار MVC filter.
- هل يعمل فقط حول Minimal API handler؟ اختار endpoint filter.
- هل القرار متعلق بمن يملك resource أو ما claims المطلوبة؟ استخدم authorization policy/handler.
- هل المنطق business operation؟ انقله إلى application/domain layer.
التمييز ده يمنع وضع logic في طبقة لا تملك السياق اللازم. مثال: request logging عام middleware؛ validation ل DTO في validator؛ resource ownership في authorization handler/use case؛ تعديل MVC result في result filter.
Exception و Logging Middleware
Exception middleware توضع مبكراً حتى تلتقط exceptions القادمة من middleware لاحقة و endpoint. استخدم UseExceptionHandler و Problem Details بدلاً من تكرار try/catch في كل controller. Logging middleware مناسب لتسجيل latency/status/method/path، لكن لا تسجل كل request body بشكل افتراضي. ضع log بعد next لتقرأ status code والمدة.
app.Use(async (context, next) =>
{
var started = Stopwatch.GetTimestamp();
try
{
await next(context);
}
finally
{
var elapsed = Stopwatch.GetElapsedTime(started);
app.Logger.LogInformation(
"{Method} {Path} -> {StatusCode} in {ElapsedMs}ms",
context.Request.Method,
context.Request.Path,
context.Response.StatusCode,
elapsed.TotalMilliseconds);
}
});الـ finally يضمن قياس الزمن حتى لو downstream رمى exception. لكن exception handler الخارجي قد يغيّر status code إلى 500 بعد انتهاء هذا middleware حسب ترتيب الطبقات؛ لذلك مكان تسجيل النتيجة النهائية مهم. كذلك streaming responses تجعل مدة middleware تشمل stream lifecycle.
Exception Boundary و Response Started
Exception middleware لا تستطيع دائماً تحويل exception إلى Problem Details لو response headers/body اتبعت بالفعل. في الحالة دي response committed ولا يمكن استبدالها بـ 500 JSON clean. لذلك لا تبدأ streaming أو تكتب body قبل ما تكون جاهزاً للتعامل مع failure semantics. في streaming protocol قد تحتاج ترسل terminal event أو تقفل الاتصال بدلاً من تغيير HTTP status.
لو middleware تسجل status بعد await next و endpoint رمى exception، status قد يظل 200 في اللحظة التي ترجع فيها للـ logger إذا exception handler الخارجي لم يكتب response بعد. ترتيب middleware يحدد من يرى status النهائي. ضع logging middleware داخل/خارج exception handler وفق metric الذي تريد قياسه، أو استخدم diagnostics/Activity instrumentation لقياس request بشكل شامل.
Cancellation و Exception Propagation
Middleware يجب أن تحترم RequestAborted عند I/O أو عمليات طويلة. لو العميل قطع الاتصال، لا تستمر في كتابة response. لا تلتقط Exception ثم تكمل كأن الطلب نجح؛ إما تسجل وتعيد رميها، أو تحولها إلى response في exception boundary مخصصة. لا تلتقط OperationCanceledException دائماً كـ error؛ افصل client cancellation عن host shutdown.
لو middleware تكتب إلى database أو remote service، فكر في timeout و resilience و failure mode. هل فشل audit logging يمنع request؟ هل correlation service optional؟ حدد fail-open/fail-closed حسب security/compliance requirement. cross-cutting code ممكن يؤثر على كل endpoints؛ لذلك لازم يكون محدوداً وقابلاً للاختبار.
Security Headers و Correlation IDs
Middleware مكان مناسب لإضافة response headers العامة مثل nosniff أو correlation ID، مع مراعاة إن بعض headers الأفضل تضبطها في reverse proxy/security configuration. استخدم OnStarting لضمان الإضافة قبل إرسال headers. لا تخترع tracing format غير متوافق؛ استخدم Activity/OpenTelemetry/W3C Trace Context حيثما أمكن.
Correlation ID قد يأتي من client، لكن validate format/length ولا تسمح له أن يصبح unbounded log key. Trace ID يختلف عن user ID؛ لا تستخدمه في authorization. لا تسجل authorization headers أو cookies.
Exception Handling Patterns
في production، exception middleware تكون boundary عامة. تسجل exception مرة واحدة مع trace identifier، وتنتج Problem Details آمنة، ولا تكشف stack trace. لا تجعل middleware تمسك كل Exception وتعيد 200؛ ده يحوّل failure إلى success ظاهري ويكسر monitoring. لا تحول OperationCanceledException إلى 500 لو client هو الذي ألغى request.
لو exception حصلت بعد بدء response، لا يمكن استبدال response بشكل مضمون. لذلك endpoints streaming تحتاج protocol-level error signaling أو إنهاء stream. لو exception handler نفسه فشل، لا تدخل في recursive error handling؛ حافظ على fallback response minimal مع logging.
app.UseExceptionHandler(errorApp =>
{
errorApp.Run(async context =>
{
var feature = context.Features.Get<IExceptionHandlerFeature>();
var logger = context.RequestServices
.GetRequiredService<ILoggerFactory>()
.CreateLogger("GlobalExceptionBoundary");
logger.LogError(feature?.Error,
"Unhandled request failure. TraceId: {TraceId}",
context.TraceIdentifier);
context.Response.StatusCode = StatusCodes.Status500InternalServerError;
await Results.Problem(
title: "An unexpected error occurred.",
extensions: new Dictionary<string, object?>
{
["traceId"] = context.TraceIdentifier
}).ExecuteAsync(context);
});
});في تطبيق فعلي، AddProblemDetails/UseExceptionHandler built-in قد يكون أبسط. الـ sketch يوضح responsibilities وليس دعوة لكتابة custom handler إذا framework يقدم behavior مناسباً.
Observability في Middleware
Middleware تستطيع قياس elapsed time/status code وبدء Activity أو إضافة trace context. استخدم route template بعد routing بدل raw path كـ metric label لتجنب high cardinality. لا تسجل query strings كاملة؛ ممكن تحتوي tokens أو search terms شخصية. اجعل logs structured ومحددة، واحتفظ بمعلومات request اللازمة للتشخيص فقط.
لو تحتاج distributed tracing، OpenTelemetry instrumentation ل ASP.NET Core و HttpClient/EF غالباً أفضل من كتابة custom timing middleware وحدها. custom middleware تظل مفيدة ل business correlation metadata، لكن لا تعيد اختراع trace propagation.
Performance و Short-circuiting
Short-circuiting مفيد في cache hit أو رفض request مبكر أو endpoint terminal. كل middleware إضافية تضيف delegate invocation وقد تضيف allocations أو I/O؛ غالباً overhead قليل لكنه يتراكم في high-throughput services. تجنب reading body بدون الحاجة أو buffering أحجام ضخمة. لا تعدّل response headers بعد بدء body؛ استخدم OnStarting عند الحاجة. لا تكتب middleware تعمل sync-over-async أو blocking calls.
استدعاء next() مرتين في middleware عادية قد يؤدي إلى تنفيذ downstream مرتين أو exceptions. Pipeline ليست event handler متعدد المستمعين؛ نادِ next مرة واحدة فقط، أو لا تناده عند short-circuit.
Middleware Allocation و Throughput
كل request يمر على middleware المسجلة؛ لذلك تكلفة صغيرة تتكرر ملايين المرات. تجنب إنشاء regex أو serializer أو HttpClient لكل request. استخدم static compiled regex أو DI singleton للخدمات thread-safe. لا تستخدم Task.Run لتغليف async I/O. لا تعمل sync file/database access داخل pipeline. لو middleware تحتاج read body، استخدم limits. ولو تحتاج logs كثيرة، استخدم log levels و sampling مناسبين.
Middleware لا ينبغي أن تحجز locks واسعة أو تعمل blocking waits. أي lock contention في outer middleware يؤثر على كل endpoints. قِس latency قبل وبعد، وراقب allocation rate والـ throughput؛ لا تفترض أن class-based middleware أسرع أو أبطأ من inline delegate بلا benchmark.
Response Headers و Request Body Ownership
تقدر تضيف security headers أو response metadata من middleware، لكن headers تُرسل بمجرد بدء response؛ بعد ذلك تعديلها يرمي exception أو لا يظهر للعميل. استخدم Response.OnStarting لو التعديل يجب أن يحصل في اللحظة الأخيرة. لو middleware تقرأ request body، لا تفعل ذلك بلا سبب؛ stream قد يكون forward-only. لو فعّلت buffering، ضع limits وتأكد من إعادة position إلى zero حتى يقدر model binder يقرأه.
app.Use(async (context, next) =>
{
context.Response.OnStarting(() =>
{
context.Response.Headers["X-Content-Type-Options"] = "nosniff";
return Task.CompletedTask;
});
await next(context);
});Response.OnStarting و OnCompleted
HTTP response لها لحظة commitment: قبل إرسال headers تستطيع تغيير status و headers؛ بعد إرسالها لا تستطيع تعديلهم بأمان. Response.OnStarting يسجل callback يعمل قبل كتابة headers، وده مفيد لإضافة security headers أو correlation ID حتى لو middleware downstream عدّلت response. OnCompleted يعمل بعد اكتمال response، لكنه ليس مكاناً لعمل critical durable work لأن العملية قد تتوقف أو request lifecycle ينتهي.
app.Use(async (context, next) =>
{
context.Response.OnStarting(() =>
{
context.Response.Headers["X-Content-Type-Options"] = "nosniff";
context.Response.Headers["X-Request-Id"] = context.TraceIdentifier;
return Task.CompletedTask;
});
context.Response.OnCompleted(() =>
{
app.Logger.LogDebug("Response completed: {Path}", context.Request.Path);
return Task.CompletedTask;
});
await next();
});لو streaming response استمرت وقتاً طويلاً، middleware التي تنتظر next قد تظل active طوال مدة stream. لذلك لا تخلط request duration مع time-to-first-byte، وراقب streaming endpoints بمقاييس منفصلة.
Request Body Buffering و Streaming Ownership
Request body stream قد لا يكون seekable، والـ model binder أو endpoint يحتاج يقرأه. لو middleware قرأت body للتوقيع أو audit، استخدم buffering بحد أقصى، ثم أعد position إلى صفر حتى downstream يقرأه. لا تفعل buffering لملفات كبيرة لأنك قد تنقل كل body إلى memory أو disk وتخلق denial-of-service vector.
app.Use(async (context, next) =>
{
context.Request.EnableBuffering(bufferThreshold: 30 * 1024,
bufferLimit: 256 * 1024);
using var reader = new StreamReader(
context.Request.Body, Encoding.UTF8,
detectEncodingFromByteOrderMarks: false,
leaveOpen: true);
var body = await reader.ReadToEndAsync(context.RequestAborted);
context.Request.Body.Position = 0;
// Inspect only if the use case requires it; never log secrets by default.
await next();
});لو الهدف webhook signature، اقرأ raw bytes وفق contract بدقة لأن deserialize ثم reserialize قد يغيّر whitespace/property order ويكسر signature. ضع body size limits قبل أي buffering.
Middleware DI و Factory Lifetime
Conventional middleware class عادة يتم إنشاؤه مرة أثناء إعداد pipeline؛ لذلك constructor injection مناسب dependencies ذات lifetime compatible مثل singleton. لا تحقن scoped DbContext في constructor middleware التقليدي. لو تحتاج scoped dependency لكل request، احقنها في InvokeAsync parameter أو استخدم IMiddleware الذي ينشأ من DI ويمكن تسجيله scoped/transient.
public sealed class TenantMiddleware(ITenantResolver resolver) : IMiddleware
{
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
context.Items["Tenant"] = await resolver.ResolveAsync(context.Request);
await next(context);
}
}
builder.Services.AddScoped<ITenantResolver, TenantResolver>();
builder.Services.AddScoped<TenantMiddleware>();
app.UseMiddleware<TenantMiddleware>();هذا مثال يوضح lifetime. لا تخزن mutable per-request state في fields داخل conventional middleware singleton-like instance؛ استخدم HttpContext.Items أو scoped service. راجع درس DI عن captive dependencies والـ scopes.
اختبار Middleware و Debugging
اختبر middleware على مستوى pipeline مصغر أو عبر WebApplicationFactory. أهم assertions: هل next تم استدعاؤه؟ هل branch عمل short-circuit؟ هل response header اتضاف قبل بدء response؟ هل status code اتسجل بعد downstream؟ هل request cancellation تم احترامه؟
app.Use(async (context, next) =>
{
if (context.Request.Path == "/maintenance")
{
context.Response.StatusCode = StatusCodes.Status503ServiceUnavailable;
await context.Response.WriteAsync("Maintenance");
return; // downstream will not run
}
await next();
});أثناء debugging، اطبع أو سجّل اسم middleware قبل وبعد next في development، لكن لا تسجل tokens أو bodies الحساسة. لو response اتكتبت بالفعل، تغيير status أو headers متأخر لن يحقق النتيجة المتوقعة؛ استخدم OnStarting للـ headers.
Knowledge Check
ما الترتيب الذي ينفذ بعد await next؟
أين نضع exception handler؟
متى نستخدم Map؟
هل Middleware و MVC Filter interchangeable؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
خريطة التغطية: 12 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.