يعني إيه Background Job؟
Background Job مهمة تنفذ خارج عمر HTTP request: إرسال email، معالجة صورة، مزامنة بيانات، تقرير طويل، أو retry لعملية مؤقتة الفشل. الـ request عادة يرسل command ويستلم Accepted/queued response، والـ worker ينفذ لاحقًا. ده يحسن response time ويعزل request lifecycle، لكنه يضيف eventual completion و monitoring و duplicate execution و failure recovery.
Hangfire framework للـ background processing مع persistent storage و worker servers و dashboard. مش مجرد Task.Run: job metadata و arguments و state تتخزن، والـ workers تسحب jobs وتنفذها. إذا process قفلت، jobs غير المنتهية يمكن أن تستعاد حسب storage/state behavior.
فرّق بين Fire-and-forget (تتجدول الآن)، Delayed (بعد وقت)، Recurring (حسب cron)، Continuation (بعد job أخرى)، و Batch/Pro features حسب المنتج/الإصدار. لا تستخدم recurring job كبديل عن event processing لكل business event.
الإعداد والتخزين والـ Worker Server
في ASP.NET Core، سجل Hangfire storage ثم أضف Hangfire Server. Storage قد تكون SQL Server أو Redis حسب provider المدعوم. الـ worker server يملك threads/queues ويحتاج connection configuration و polling/heartbeat settings. في deployment متعدد replicas، قد يعمل أكثر من server ويشاركوا نفس storage؛ صمم jobs على أساس أن أكثر من worker قد ينفذ jobs مختلفة بالتوازي.
builder.Services.AddHangfire(config => config
.SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
.UseSimpleAssemblyNameTypeSerializer()
.UseRecommendedSerializerSettings()
.UseSqlServerStorage(
builder.Configuration.GetConnectionString("Hangfire")));
builder.Services.AddHangfireServer(options =>
{
options.WorkerCount = Math.Max(1, Environment.ProcessorCount);
options.Queues = ["critical", "default", "low"];
});في production، استخدم storage منفصل أو schema/permissions مخصصة حسب policy، واضبط retention و cleanup. لا تخلط application DB user بصلاحيات واسعة مع Hangfire schema إن أمكن. راقب database size لأن job history قد تنمو إذا لم تضبط expiration/retention.
Fire-and-Forget و Delayed و Continuations
Hangfire يسجل method call expression ويخزن معلومات النوع وال method وال arguments. لذلك job arguments لازم تكون serializable ومستقرة نسبيًا. لا تمرر HttpContext أو DbContext أو service instance أو Stream أو object graph ضخم. مرر identifiers و small immutable command، ثم اجلب البيانات وقت التنفيذ.
public sealed class InvoiceJobs(IInvoiceProcessor processor)
{
public Task GenerateAsync(Guid invoiceId, CancellationToken ct) =>
processor.GeneratePdfAsync(invoiceId, ct);
}
// From an endpoint/application service:
var jobId = BackgroundJob.Enqueue<InvoiceJobs>(
job => job.GenerateAsync(invoiceId, CancellationToken.None));Delayed job تستخدم Schedule لوقت لاحق، و continuation تربط job بعد نجاح/انتهاء job أخرى حسب الحالة المحددة. لا تعتمد على أن scheduled job ستنفذ بالثانية بالضبط؛ worker availability و storage polling و system load تؤثر على الوقت الفعلي.
var exportJobId = BackgroundJob.Enqueue<ExportJobs>(
job => job.ExportAsync(exportId, CancellationToken.None));
BackgroundJob.ContinueJobWith<NotificationJobs>(
exportJobId,
job => job.NotifyExportReadyAsync(exportId, CancellationToken.None));
BackgroundJob.Schedule<ReminderJobs>(
job => job.SendAsync(reminderId, CancellationToken.None),
TimeSpan.FromHours(2));تأكد إن continuation behavior يناسبك: هل تعمل بعد نجاح parent فقط أم بعد حالة أخرى؟ ماذا يحدث لو parent فشلت أو اتلغت؟ راجع overload/state filters بدل افتراض semantics.
Recurring Jobs و Cron و Time Zones
Recurring job تُعرّف باسم ثابت و cron expression، و Hangfire يضيف scheduled occurrence دوريًا. لا تسجل recurring job باسم عشوائي كل startup؛ استخدم identifier ثابتًا حتى يتم تحديث definition بدل إنشاء duplicates. افهم timezone: cron قد يفسر وفق UTC أو timezone محدد في API/الإصدار، و DST قد يجعل بعض الأوقات تتكرر أو تتخطى.
RecurringJob.AddOrUpdate<ExchangeRateJobs>(
recurringJobId: "exchange-rates-refresh",
methodCall: job => job.RefreshAsync(CancellationToken.None),
cronExpression: "*/5 * * * *",
options: new RecurringJobOptions
{
TimeZone = TimeZoneInfo.Utc
});لو المهمة كل 5 دقائق لكن تنفيذها يستغرق 8 دقائق، حدد هل يسمح بتداخل executions أم لا. استخدم distributed concurrency control/DisableConcurrentExecution بحذر مع فهم lock timeout، أو اجعل job نفسها idempotent وقادرة على التعامل مع overlap. لا تعتمد على in-process timer إذا عندك replicas كثيرة وتريد تشغيلًا واحدًا عالميًا.
Time Zones و Scheduling Correctness
خزن timestamps التقنية في UTC، لكن جدولة business event قد تكون مرتبطة بوقت محلي مثل 9 صباحًا في القاهرة. احتفظ بـ timezone ID صريح، ولا تحول local schedule إلى UTC مرة واحدة للأبد إذا كان DST قد يتغير. بعض الأوقات المحلية غير موجودة أو تتكرر عند انتقال الساعة؛ حدد policy: skip، shift، أو choose earlier/later occurrence.
اختبر recurring jobs عند DST boundaries، الشهر الذي فيه 28/29/30/31 يومًا، آخر يوم عمل، و timezone مختلفة عن server. cron expression يحدد schedule syntax فقط؛ لا يضمن تنفيذًا في اللحظة نفسها ولا يحل business calendar rules وحده.
Retries و Recurring Jobs و Worker Capacity
Retry policy يجب أن تميز transient errors عن permanent errors. إعادة محاولة validation failure عشر مرات لا تفيد. استخدم exponential backoff مع jitter لتجنب thundering herd، وحدد عدد المحاولات والـ dead-letter/manual review path. لا تجعل كل jobs في queue واحدة إذا كان عندك عمل سريع وآخر ثقيل.
عدد workers ليس “كلما زاد كان أفضل”. كل worker قد يستهلك DB connections و CPU و memory و external API quota. قس queue latency و execution duration و failure rate، وحدد concurrency حسب أبطأ dependency. recurring schedule قد يتأخر إذا لم توجد worker capacity، لذلك لا تتعامل معه كـ real-time timer.
// Register a recurring job with an explicit queue and stable identifier
RecurringJob.AddOrUpdate<IExchangeRateRefreshJob>(
"exchange-rates-refresh",
job => job.RefreshAsync(CancellationToken.None),
"*/5 * * * *",
new RecurringJobOptions { TimeZone = TimeZoneInfo.Utc });
// Keep the job method small: resolve data, process, persist status, emit metrics.راجع API signature حسب إصدار Hangfire المثبت لديك؛ المثال يستخدم recurring-job API الشائع في الإصدارات الحديثة. لا تمرر scoped DbContext كـ captured object داخل job. دع Hangfire/DI ينشئ scope ويحل service لكل execution، ومرر identifiers فقط.
Dependency Injection و Job Serialization
Hangfire يخزن method/arguments ثم ينشئ job instance ويحل dependencies من DI وقت التنفيذ. الـ job class يفضل تكون صغيرة وتفوض العمل إلى application service. لا تخزن dependencies داخل arguments. خليك حذر مع تغيير namespace/class/method signature بعد وجود jobs pending؛ serialization قديمة قد لا تتوافق مع النوع الجديد.
public sealed class RebuildSearchIndexJob(
ISearchIndexRebuilder rebuilder,
ILogger<RebuildSearchIndexJob> logger)
{
public async Task ExecuteAsync(Guid tenantId, CancellationToken ct)
{
logger.LogInformation("Rebuilding index for tenant {TenantId}", tenantId);
await rebuilder.RebuildAsync(tenantId, ct);
}
}لو غيرت method signature، خطط migration: اترك compatibility method مؤقتة، أفرغ/حوّل jobs القديمة، أو version command contract. لا تضع PII أو secrets في job arguments لأنها قد تظهر في dashboard/storage/logs.
Job Argument Versioning و Deployment أثناء وجود Jobs Pending
Hangfire يخزن معلومات method/arguments، لذلك تغيير namespace أو assembly أو method signature قد يجعل jobs القديمة غير قابلة للـ deserialize/execute. لا تعتبر deployment مجرد تحديث binaries؛ فيه persistent work queue لازم تظل متوافقة. استخدم command DTOs versioned وبسيطة، وخلي method entry point مستقرة فترة انتقالية.
لو تحتاج تغيير payload، strategy ممكن تكون: دعم V1/V2 handlers مؤقتًا، تحويل jobs pending عبر migration، تصريف queue قبل deployment، أو جدولة job جديدة وإلغاء القديمة بعد التأكد. لا تحذف class تستخدمها jobs محفوظة قبل فحص storage.
Retries و Failed Jobs و Job States
في الأنظمة الموزعة، افترض أن job قد تنفذ أكثر من مرة. worker قد ينفذ side effect ثم يتعطل قبل تسجيل النجاح؛ بعد restart قد يعيد التنفيذ. لذلك job semantics غالبًا at-least-once عمليًا، وليس exactly-once end-to-end. Automatic retries مفيدة للأخطاء transient، لكنها خطيرة لو method غير idempotent.
صنف الأخطاء: transient network/timeout/deadlock يمكن retry محدودًا؛ validation/business conflict غالبًا لا؛ invalid credentials يحتاج intervention. استخدم backoff مع jitter، حد أقصى للمحاولات، alert على failed jobs، و dead-letter/manual recovery process. لا تكرر job بلا نهاية.
[AutomaticRetry(Attempts = 5, OnAttemptsExceeded = AttemptsExceededAction.Fail)]
public async Task SendReceiptAsync(Guid orderId, CancellationToken ct)
{
var order = await orders.GetAsync(orderId, ct);
if (order is null)
throw new InvalidOperationException("Order does not exist.");
await receiptSender.SendOnceAsync(order, ct);
}Attribute مثال توضيحي؛ اختَر retry policy حسب نوع job. لا تعالج كل exception داخل method ثم ترجع نجاحًا، وإلا Hangfire سيعتبر job ناجحة. في المقابل لا ترمِ exception على permanent failure وتتركها تعاد بلا معنى؛ سجل terminal state أو ارسلها لمسار manual review.
Failure Runbook: من Failed Job إلى Recovery
عند failed job، لا تضغط Retry بشكل أعمى. اقرأ exception category و attempt history و job arguments (من غير secrets)، حدد هل السبب transient أو data-specific أو code bug، ثم قرر retry أو manual correction أو dead-letter. لو job ترسل email/payment، تحقق من external provider قبل retry لأن side effect قد يكون نجح رغم timeout.
ضع alert على queue age و failed jobs و retry exhaustion، وليس فقط server process up. worker قد يكون alive لكن queue متوقفة بسبب storage permissions أو poison job أو exhausted connections. dashboard مفيدة للتشخيص لكنها ليست monitoring strategy كاملة.
اكتب runbook لكل critical job: owner، expected frequency/duration، idempotency key، source of truth، safe retry procedure، manual replay instructions، data repair steps، alert threshold و rollback/disable switch.
Hangfire Retry و Idempotency و Job State
Job قد تنفذ ثم يتعطل worker قبل حفظ نجاحها؛ عند retry قد تنفذ مرة ثانية. لذلك صمم handler idempotent: business key ثابت، unique constraint، processed marker، أو upsert آمن. لا تعتمد على job ID وحده كـ business idempotency key إذا enqueue قد يحدث أكثر من مرة.
حدد retry policy حسب failure: transient network/database timeout يمكن retry bounded مع backoff؛ invalid input أو missing required resource قد يحتاج Failed state ومراجعة؛ payment timeout يحتاج reconciliation لأن النتيجة قد تكون unknown. اجعل job صغيرة وقابلة للاستئناف، ومرر CancellationToken إذا كان supported. راقب queue latency و failed jobs و retry count و worker saturation.
public sealed class SendInvoiceJob(AppDbContext db, IEmailSender email)
{
public async Task ExecuteAsync(Guid invoiceId, CancellationToken ct)
{
var invoice = await db.Invoices.SingleAsync(x => x.Id == invoiceId, ct);
if (invoice.EmailSentAt is not null) return;
await email.SendInvoiceAsync(invoice.CustomerEmail, invoice.Number, ct);
invoice.MarkEmailSent(DateTimeOffset.UtcNow);
await db.SaveChangesAsync(ct);
}
}هذا sketch يوضح الفكرة لكنه يحتوي race: workerان قد يقرآن EmailSentAt == null ويرسلان معًا. في production استخدم outbox/delivery state مع atomic claim/lease و unique constraint أو provider idempotency. إرسال email ثم حفظ marker ليس atomic؛ صمم retry/reconciliation لهذا gap.
Idempotency و Duplicate Prevention
Idempotent operation تعطي نفس النتيجة المنطقية لو تكررت بنفس command. إرسال email ليس idempotent بطبيعته؛ تحتاج delivery key أو outbox record يحدد هل تم الإرسال. إنشاء invoice يمكن حمايته بـ unique business key. خصم المخزون يحتاج conditional update/transaction وليس مجرد check في C#.
CREATE TABLE ProcessedJobs (
JobKey nvarchar(200) NOT NULL PRIMARY KEY,
ProcessedAt datetime2 NOT NULL DEFAULT SYSUTCDATETIME()
);public async Task<bool> TryClaimAsync(string key, CancellationToken ct)
{
try
{
db.ProcessedJobs.Add(new ProcessedJob { JobKey = key });
await db.SaveChangesAsync(ct);
return true;
}
catch (DbUpdateException ex) when (IsUniqueViolation(ex))
{
return false; // Already processed by another execution.
}
}الـ claim والـ business side effect لازم يكونا ضمن transaction واحدة لو الاتنين في نفس database؛ وإلا crash بعد claim وقبل side effect يمنع إعادة التنفيذ رغم عدم اكتمال العمل. للـ external side effects استخدم provider idempotency key أو outbox + delivery state/reconciliation. احتفظ بالـ idempotency record للمدة التي تمنع duplicates فعليًا.
Prevent Concurrent Runs: Distributed Lock vs Idempotency
Recurring job قد تبدأ مرة جديدة قبل انتهاء execution السابقة. DisableConcurrentExecution يمكن أن يمنع overlap باستخدام distributed lock mechanism المرتبط بالـ storage، لكنه ليس ضمانًا مطلقًا ضد كل failure scenario: lock timeout أو storage/network failure أو worker crash قد يترك سلوكًا يحتاج reconciliation. لا تستخدمه بديلًا عن idempotency.
اسأل هل overlap ضار فعلًا؟ لو job تعيد حساب cache من source of truth، قد يكون overlap مقبولًا مع last-write-safe update. لو job ترسل invoice أو تخصم balance، يجب أن تكون العملية idempotent ومحمية بقيد business في database. distributed lock يقلل التنافس، لكن business invariant يجب أن تكون enforced في storage.
[DisableConcurrentExecution(timeoutInSeconds: 60)]
public async Task RefreshRatesAsync(CancellationToken ct)
{
var latest = await provider.FetchLatestAsync(ct);
await rateStore.ReplaceSnapshotAsync(latest, ct);
}راجع behavior للـ attribute والـ storage provider والإصدار المستخدم، ولا تضعها على job طويلة جدًا من غير lock timeout/monitoring مناسب. لو lock انتهى بينما job القديمة ما زالت تعمل، تحتاج fencing/version check أو atomic replace semantics.
Job Delivery Semantics و Idempotency
Background job systems قد تعيد تنفيذ job بعد timeout أو worker crash أو فقدان acknowledgment. لذلك صمم job على أساس at-least-once ما لم يضمن المنتج semantics مختلفة بوضوح. لا تفترض أن method ستعمل مرة واحدة فقط. Idempotency تعني أن تنفيذ نفس الأمر أكثر من مرة ينتج نفس الأثر النهائي، غالبًا عبر unique operation key أو state transition مشروط.
فرّق بين job enqueue و job execution. نجاح enqueue لا يعني أن العمل انتهى. استخدم states والمراقبة والـ retry policy، واجعل job payload صغيرًا ويحتوي IDs بدل serialized entity graph قديم.
public async Task SendInvoiceAsync(Guid invoiceId, CancellationToken ct)
{
var invoice = await db.Invoices.SingleAsync(x => x.Id == invoiceId, ct);
if (invoice.EmailSentAt is not null) return;
// Persist a durable state transition / idempotency marker.
var claimed = await db.Invoices
.Where(x => x.Id == invoiceId && x.EmailSentAt == null)
.ExecuteUpdateAsync(s => s.SetProperty(x => x.EmailStatus, "Sending"), ct);
if (claimed == 0) return;
await emailSender.SendAsync(invoice.CustomerEmail, invoice.PdfUrl, ct);
await db.Invoices.Where(x => x.Id == invoiceId)
.ExecuteUpdateAsync(s => s.SetProperty(x => x.EmailSentAt, DateTimeOffset.UtcNow), ct);
}حتى هذا النمط يحتاج معالجة حالة crash بعد إرسال البريد وقبل تسجيل Sent؛ لا يمكن ضمان exactly-once عبر DB و SMTP من غير بروتوكول مشترك. استخدم Outbox + provider idempotency إن توفر، أو صمم reconciliation لإعادة المحاولة مع فهم احتمال duplicate email.
Dashboard Security و Queues و Monitoring
Hangfire Dashboard تعرض job arguments و history و retry/delete actions؛ لا تفتحها للعامة. استخدم authentication و authorization policy و network restrictions، واحجب PII/secrets من arguments. لا تفترض إن Dashboard آمنة لمجرد إنها على مسار غير معروف.
قسّم queues حسب priority أو workload، واضبط worker count بعناية. زيادة workers قد تزيد DB connections أو CPU pressure أو provider rate limits. راقب enqueued/processing/succeeded/failed counts، queue age، job duration، retry count، server heartbeat، storage latency، recurring schedule drift و dead-letter volume.
Logging يجب أن يحتوي job id و business correlation id و tenant id عند الحاجة، لكن لا تسجل access tokens أو customer secrets. اربط job tracing مع request الذي أنشأها عبر correlation metadata صغيرة.
Cancellation و Graceful Shutdown
Job قد تتوقف بسبب shutdown أو cancellation أو worker restart. استخدم CancellationToken في DB/network operations، وقسم العمل الكبير إلى chunks/checkpoints. لا تفترض إن cancellation تعني rollback لكل side effects؛ لو أرسلت email أو خصمت مبلغًا، لا يمكن إلغاء الأثر الخارجي تلقائيًا.
صمم graceful shutdown: أوقف قبول jobs جديدة حسب host behavior، اسمح للعمليات الحالية بوقت محدود، ثم اتركها تتعافى عبر retries/requeue. اجعل كل chunk idempotent و checkpointed حتى لا تعيد معالجة ملايين السجلات من البداية.
Hangfire vs HostedService و Quartz و Channels و Outbox
| الآلية | متى تناسب؟ | ما الذي لا توفره تلقائيًا؟ |
|---|---|---|
| BackgroundService | worker بسيط داخل host، polling أو loop | persistent job store و dashboard/retries |
| System.Threading.Channels | in-process producer/consumer pipeline | durability بعد process crash |
| Quartz.NET | جدولة متقدمة و calendars/triggers | business job persistence semantics حسب الإعداد |
| Hangfire | persistent jobs و dashboard/retries | exactly-once side effects |
| Message broker | event-driven distributed consumers | business idempotency و outbox من تلقاء نفسه |
Outbox pattern يحل فجوة DB commit ثم publish: في نفس transaction تحفظ business change و outbox message. Background dispatcher يقرأ outbox ويرسل الرسالة ثم يعلّمها processed. لو dispatcher crash بعد publish وقبل mark، قد يعيد النشر؛ لذلك consumer أيضًا idempotent. Hangfire ممكن يشغل dispatcher دوريًا، لكنه لا يلغي outbox semantics.
CREATE TABLE OutboxMessages (
Id uniqueidentifier NOT NULL PRIMARY KEY,
Type nvarchar(300) NOT NULL,
Payload nvarchar(max) NOT NULL,
OccurredAt datetime2 NOT NULL,
ProcessedAt datetime2 NULL,
Attempts int NOT NULL DEFAULT 0
);اختبر فهمك
هل Hangfire job تنفذ exactly once؟
لماذا تمرر ID بدل DbContext أو entity graph في job arguments؟
هل recurring job كل خمس دقائق تعني execution واحدًا فقط عالميًا؟
ما الذي يحمي Dashboard؟
كيف يساعد Outbox؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
خريطة التغطية: 22 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.