ניהול משימות ותזמון עם Hangfire
יש הרבה פעולות בתוכנה שלא צריכות להתבצע מיד או כחלק מבקשת המשתמש. הפקת דוח יכולה להתבצע ברקע, תזכורת צריכה להישלח בתאריך מסוים, וניקוי קבצים ישנים יכול לרוץ בכל לילה. בכל המקרים האלה צריך גם לדעת מה התבצע, מה נכשל ומה עדיין מחכה.
הספרייה Hangfire מאפשרת לנהל את המשימות האלה בסביבת .NET: להכניס עבודה לתור לביצוע ברקע, לתזמן אותה למועד עתידי, להגדיר משימות מחזוריות וגם להפעיל משימה בהמשך למשימה אחרת. היא שומרת את פרטי העבודות באחסון, תומכת בניסיונות חוזרים במקרה של כישלון ומספקת מסך ניהול למעקב ולהפעלה חוזרת. אפשר להריץ כמה עבודות במקביל, ואף לחלק את הביצוע בין כמה שרתים.
השימוש הבסיסי בה נראה כמעט כמו קריאה רגילה למתודה. אבל בין קריאה למתודה לבין שמירת בקשה שמישהו יבצע אותה מאוחר יותר יש הבדל שכדאי להבין. נתחיל משם.
נתחיל מקריאה למתודה
נניח שיש לנו מערכת שמאפשרת להפיק דוחות. המשתמש בוחר תקופה, לוחץ על כפתור וממתין לקובץ.
הקוד שמפעיל את ההפקה עשוי להיראות כך:
await reportGenerator.GenerateAndStoreAsync(reportId);
אם הפקת הדוח אורכת דקה, גם הטיפול בבקשת המשתמש ימתין לה בערך דקה.
דרך אגב, המילה await לא משנה את העובדה הזו. היא מאפשרת להמתין לפעולות אסינכרוניות בלי להחזיק Thread חסום בזמן ההמתנה, אבל המתודה שמטפלת בבקשה עדיין לא סיימה את עבודתה. המשתמש עדיין מחכה לתשובה.
אפשר להתפתות לכתוב:
_ = Task.Run(
() => reportGenerator.GenerateAndStoreAsync(reportId));
עכשיו אנחנו כבר לא ממתינים להפקת הדוח. אבל העבודה הזו חיה בתוך התהליך הנוכחי. אם התהליך יקרוס או ייעצר בזמן העלאת גרסה, אין כאן מנגנון שיזכור שעליו להשלים אותה. בנוסף, אם reportGenerator מחזיק שירותים שנוצרו עבור בקשת ה־HTTP, למשל DbContext, הם עלולים להשתחרר עוד לפני שהעבודה הסתיימה.
כלומר, הצלחנו להפסיק לחכות. עדיין צריך לטפל בעבודה עצמה.
לשמור את הבקשה לבצע
בעזרת Hangfire נוכל לכתוב:
var jobId = backgroundJobs.Enqueue<ReportJob>(
job => job.RunAsync(reportId));
המשתנה backgroundJobs הוא שירות מסוג IBackgroundJobClient, שאפשר לקבל באמצעות Dependency Injection.
השורה הזו לא מפעילה בעצמה את RunAsync. היא יוצרת עבודה, שומרת אותה באחסון שהגדרנו ומכניסה אותה לתור. לאחר מכן רכיב אחר ייקח את העבודה ויפעיל את המתודה. הערך שחוזר הוא מזהה העבודה ב־Hangfire, ולא הדוח שהופק.
כאן יש פרט מעניין. מה בעצם נשמר?
הביטוי ששלחנו ל־Enqueue נראה כמו Lambda רגילה, אבל במקרה הזה הוא מתקבל כ־Expression Tree: מבנה נתונים שמתאר את הקריאה. כך Hangfire יכולה לחלץ ממנו את סוג המחלקה, את המתודה ואת ערכי הפרמטרים, ולשמור את המידע הדרוש להפעלה מאוחרת.
לא נשמר עותק של האובייקט שלנו, ולא נשמר כל הזיכרון של התוכנית. נשמר תיאור של הפעולה שצריך לבצע.
לכן גם הקוד המתאים חייב להיות זמין בתהליך שיבצע את העבודה. אם נשנה שם של מחלקה או חתימה של מתודה בזמן שעבודות ישנות עדיין ממתינות, צריך להביא בחשבון שהן שמורות לפי המבנה הקודם. זו משמעות מעשית של שמירת קריאות למתודות כנתונים.
שלושת החלקים
כדי להבין את המבנה, אפשר לחלק אותו לשלושה:
Client: הקוד שמבקש ליצור עבודה. בדוגמה שלנו, הקוד שמגיב לבקשת הפקת הדוח.
Storage: האחסון שבו נשמרים פרטי העבודות והמצבים שלהן.
Server: הרכיב שמפעיל Workers, לוקח עבודות מהתורים ומבצע אותן.
המילה Server קצת מבלבלת כאן. לא חייבת להיות מכונה נפרדת. אפשר להפעיל את רכיב העיבוד בתוך אותה אפליקציית Web, ובהמשך להעביר אותו לתהליך נפרד אם יש בכך צורך.
למשל, אם הפקת הדוחות צורכת הרבה מעבד וזיכרון, יש היגיון להרחיק אותה מהתהליך שמשרת את המשתמשים. ה־API יכניס עבודות לאחסון המשותף, ותהליך אחר, שבו מותקן קוד ההפקה, יבצע אותן.
האחסון הוא מה שמאפשר להפריד בין רגע הבקשה לרגע הביצוע. העבודה יכולה להישאר בו גם כשהתהליך שיצר אותה כבר אינו פועל. כדי לבצע אותה בפועל עדיין צריך Server פעיל.
קצת קוד
בדוגמה הזו נשתמש ב־SQL Server לאחסון העבודות. נוסיף לפרויקט את החבילות:
dotnet add package Hangfire.AspNetCore
dotnet add package Hangfire.SqlServer
dotnet add package Microsoft.Data.SqlClient
בקובץ Program.cs נגדיר:
using Hangfire;
var builder = WebApplication.CreateBuilder(args);
var connectionString =
builder.Configuration.GetConnectionString("Hangfire")
?? throw new InvalidOperationException(
"Missing Hangfire connection string.");
builder.Services.AddHangfire(configuration => configuration
.UseSimpleAssemblyNameTypeSerializer()
.UseRecommendedSerializerSettings()
.UseSqlServerStorage(connectionString));
builder.Services.AddHangfireServer();
builder.Services.AddScoped<ReportJob>();
// Register the application's IReportGenerator implementation.
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseHangfireDashboard();
}
app.Run();
צריך להגדיר Connection String בשם Hangfire, שמצביע למסד נתונים זמין. כמו כן, צריך לרשום את המימוש של IReportGenerator, שהוא שירות של האפליקציה שלנו.
שימו לב לשתי ההרשמות השונות: AddHangfire מגדירה את שירותי הספרייה והאחסון. הקריאה ל־AddHangfireServer מוסיפה גם את רכיב הביצוע. אפליקציה שרק מכניסה עבודות לתור אינה חייבת להריץ אותו בעצמה.
ה־Dashboard מאפשר לראות עבודות ומצבים שלהן. בדוגמה הפעלנו אותו רק בסביבת פיתוח; לחשיפה מרחוק צריך להגדיר הרשאות מתאימות.
המחלקה שלנו יכולה להיראות כך:
public class ReportJob
{
private readonly IReportGenerator _reportGenerator;
public ReportJob(IReportGenerator reportGenerator)
{
_reportGenerator = reportGenerator;
}
public async Task RunAsync(Guid reportId)
{
await _reportGenerator.GenerateAndStoreAsync(reportId);
}
}
זהו קטע מתוך אפליקציה: IReportGenerator והמימוש שמפיק ושומר את הדוח אינם חלק מ־Hangfire.
אין כאן ירושה ממחלקה מיוחדת של הספרייה. כשהעבודה תתבצע, Hangfire תיצור את המחלקה בעזרת מנגנון הפעלת העבודות והאינטגרציה ל־Dependency Injection, ואז תקרא למתודה שלה.
למה העברנו רק מזהה?
אפשר להעביר למתודה אובייקטים מורכבים, אבל הפרמטרים עוברים סריאליזציה ונשמרים באחסון. אם נשלח רשימה של מאה אלף רשומות, נשמור אותה כחלק מהעבודה.
במקום זה, בדוגמה שלנו נשמור במסד הנתונים בקשת דוח עם התקופה והמסננים שנבחרו, ונעביר לעבודה רק את המזהה שלה. בזמן הביצוע היא תטען את מה שדרוש לה.
יש כאן גם החלטה לגבי משמעות הנתונים. האם הדוח צריך לשקף את מצב המערכת בזמן שהמשתמש לחץ על הכפתור, או בזמן שההפקה התחילה? אם חשוב לשמר את המצב המקורי, העברת מזהה לבדה אינה מספיקה. צריך לשמור גרסה או תמונת מצב מתאימה שאליה המזהה מפנה.
העובדה שהעבודה ממתינה בתור פירושה שהנתונים עשויים להשתנות בינתיים.
ניסיון נוסף
עד עכשיו עסקנו בדרך שבה העבודה מגיעה לביצוע. אבל הפקת הדוח יכולה להיכשל, למשל בגלל תקלה זמנית בחיבור למסד הנתונים.
כאשר מתודה זורקת Exception, מנגנון הניסיונות החוזרים של Hangfire יכול לתזמן אותה מחדש. כברירת מחדל מוגדרים עשרה ניסיונות חוזרים, עם השהיות הולכות וגדלות. אפשר לקבוע מדיניות אחרת למתודה:
[AutomaticRetry(Attempts = 3)]
public async Task RunAsync(Guid reportId)
{
await _reportGenerator.GenerateAndStoreAsync(reportId);
}
כאן הגדרנו עד שלושה ניסיונות חוזרים בנוסף להפעלה הראשונה. אם כולם ייכשלו, בברירת המחדל העבודה תישאר במצב Failed ואפשר יהיה לבדוק אותה ולהפעיל אותה ידנית.
זה גם מסביר למה לא כדאי לתפוס כל Exception בתוך העבודה, לכתוב ללוג ולסיים כרגיל. מבחינת Hangfire, מתודה שהסתיימה בלי לדווח על כישלון עשויה להיחשב מוצלחת.
אבל לפני שמוסיפים ניסיונות חוזרים, צריך לשאול מה יקרה אם חלק מהפעולה כבר התבצע.
אותה עבודה עשויה להתבצע שוב
נחזור לדוח. הקובץ נוצר ונשמר בהצלחה, ומיד אחר כך התהליך קרס, לפני ש־Hangfire הספיקה לרשום שהעבודה הסתיימה.
העבודה עשויה לחזור לביצוע. היא לא תמשיך אוטומטית מהשורה שבה נעצרה, אלא המתודה תופעל מחדש.
לכן צריך לתכנן אותה כך שהרצה חוזרת לא תייצר תוצאה עסקית כפולה. זו אותה תכונה שנקראת Idempotency. במקרה שלנו אפשר לשייך את התוצאה ל־reportId קבוע ולתכנן שמירה חוזרת של אותה תוצאה, במקום ליצור בכל ניסיון דוח חדש שאינו קשור לקודם. התכנון המדויק תלוי באחסון ובמשמעות של הדוח.
גם בדיקה פשוטה של “האם הדוח כבר קיים?” אינה בהכרח מספיקה. שתי הרצות עלולות לבדוק יחד, לקבל תשובה שלילית ולהתחיל לעבוד. כדי להגן על התוצאה צריך מנגנון אטומי מתאים, למשל אילוץ ייחודיות או עדכון מותנה במסד הנתונים.
דרך אגב, גם נעילה שמצמצמת הרצות מקבילות אינה תחליף להגנה הזו. בתקלות מסוימות אפשר לאבד את הנעילה בלי שהקוד שרץ נעצר מיד. התיעוד של Hangfire מדגיש שגם מנגנוני הגבלת המקביליות שלה אינם הבטחה לביצוע יחיד.
בין שמירת הבקשה להכנסה לתור
נשאר עוד פער קטן בקוד, עם משמעות גדולה.
אמרנו שנשמור בקשת דוח במסד הנתונים, ואז נכניס עבודה ל־Hangfire. אלו שתי פעולות נפרדות. אם התהליך ייעצר ביניהן, תהיה לנו בקשה שמורה שאין מי שמבצע אותה.
עצם השימוש ב־Hangfire לא הופך את השמירה העסקית ואת ההכנסה לתור לטרנזקציה משותפת.
אפשר לפתור זאת בעזרת Outbox: באותה טרנזקציה שבה שומרים את בקשת הדוח, שומרים גם רשומה שמציינת שצריך לתזמן אותה. תהליך נפרד קורא את הרשומות ומכניס עבודות ל־Hangfire.
גם התהליך הזה עלול להיעצר אחרי שהכניס עבודה ולפני שסימן שהרשומה טופלה. כלומר, ייתכן שיכניס אותה שוב. זו סיבה נוספת לבסס את ההגנה מכפילויות על מזהה הבקשה העסקית שלנו, ולא להסתמך רק על מזהה העבודה ש־Hangfire יצרה.
תזמון למועד עתידי ומשימות מחזוריות
לא כל עבודה צריכה להתחיל בהקדם האפשרי. אפשר לבקש שמשימה תתבצע בעוד שעה:
backgroundJobs.Schedule<ReportJob>(
job => job.RunAsync(reportId),
TimeSpan.FromHours(1));
ואפשר לקבוע תאריך ושעה מסוימים:
var scheduledAt = new DateTimeOffset(
2026, 12, 1, 9, 0, 0,
TimeSpan.FromHours(2));
backgroundJobs.Schedule<ReportJob>(
job => job.RunAsync(reportId),
scheduledAt);
בדוגמה הזו ביקשנו להפעיל את העבודה ב־1 בדצמבר 2026, בשעה תשע בבוקר, בהפרש של שעתיים מ־UTC. ההפרש מפורש כדי שלא נהיה תלויים באזור הזמן של השרת. במערכת שמקבלת שעה מקומית ממשתמש צריך להתחשב גם באזור הזמן שלו ובשעון קיץ.
אלו עבודות חד־פעמיות. לעומת זאת, לעבודה שחוזרת באופן קבוע משתמשים ב־RecurringJob. למשל, ניקוי קובצי דוחות ישנים בכל יום שני בשעה שמונה בבוקר לפי שעון ישראל:
var israelTimeZone =
TimeZoneInfo.FindSystemTimeZoneById("Asia/Jerusalem");
RecurringJob.AddOrUpdate<ReportCleanupJob>(
"weekly-report-cleanup",
job => job.RunAsync(),
"0 8 * * 1",
new RecurringJobOptions
{
TimeZone = israelTimeZone
});
המחלקה ReportCleanupJob היא מחלקה נוספת של האפליקציה, שבה נממש את הניקוי. מזהה אזור הזמן שבדוגמה דורש תמיכה במזהי IANA בסביבת הריצה.
המחרוזת "0 8 * * 1" היא ביטוי Cron. חמשת השדות מתארים דקות, שעות, יום בחודש, חודש ויום בשבוע. הכוכבית פירושה שאין הגבלה בשדה הזה. כאן המשמעות היא: בדקה אפס, בשעה שמונה, בכל חודש, בימי שני.
המחרוזת "weekly-report-cleanup" היא מזהה קבוע של ההגדרה. קריאה חוזרת עם אותו מזהה מעדכנת אותה.
מנגנון התזמון בודק את העבודות המחזוריות במרווחים של דקה ומכניס לתור עבודות שהגיע זמנן. ההכנסה לתור והביצוע הם עדיין שני דברים שונים: אם כל ה־Workers עסוקים, העבודה תמתין. אם אין Server פעיל, אין מי שיתזמן ויבצע אותה.
גם בעבודה חד־פעמית, המועד שקבענו אינו הבטחה להתחלה באותה שנייה. מרווחי הבדיקה של מנגנון התזמון והעומס בתור משפיעים על זמן ההתחלה בפועל.
בחזרה למערכת הדוחות
במערכת שלנו המשתמש כבר לא צריך להחזיק בקשת HTTP פתוחה עד שהקובץ ייווצר. אפשר להחזיר לו אישור שהבקשה התקבלה ומזהה שבאמצעותו יבדוק את מצבה, ובהמשך להציג קישור להורדה.
לצורך זה הייתי שומר מצב עסקי של בקשת הדוח באפליקציה עצמה. ה־Dashboard של Hangfire מתאים לנו כמפתחים וכמפעילי המערכת; המשתמש צריך לראות אם הדוח שלו ממתין, נמצא בהפקה, מוכן או נכשל.
מבחינת המימוש, הייתי מתחיל בעבודה אחת ובודק אותה גם בתנאים פחות נוחים: לעצור את התהליך באמצע ההפקה, להפעיל אותו מחדש, ולהכניס בכוונה פעמיים את אותה בקשה. כך אפשר לבדוק שהקובץ הסופי והמצב שמוצג למשתמש נשארים עקביים.
בעיניי, זה גם המבחן הטוב לשילוב של Hangfire במערכת. קל יחסית לגרום למתודה לרוץ ברקע. העבודה שלנו היא לדאוג שיהיה ברור מה קרה לה, ושהמערכת תישאר נכונה גם כשהיא תצטרך לרוץ שוב.