TCIS.Hangfire 1.0.0

TCIS.Hangfire

Đưa IWorkContext đi qua ranh giới job của Hangfire: bắt ngữ cảnh lúc enqueue, dựng lại lúc thực thi, dọn sạch sau đó. Kèm nối lại W3C trace để log của job nằm cùng một trace với request đã tạo ra nó.

Gói này không biết gì về multi-tenancy — xem §6.

Mục lục

1. Đăng ký
2. Ngữ cảnh đi qua ranh giới job như thế nào
3. Hợp đồng trên dây: tham số wc:*
4. CorrelationId đổi mỗi lần chạy — có chủ đích
5. Nối lại trace
6. Scope DI và cách ly giữa các job
7. Job đa cảng
8. Những chỗ dễ vấp

1. Đăng ký

dotnet add package TCIS.Hangfire

using Hangfire;
using TCIS.Hangfire.Extensions;

builder.Services.AddHangfire(config =>
{
    config.UseSqlServerStorage(builder.Configuration.GetConnectionString("HangfireConnection"));
    config.UseTWorkContext();
});

builder.Services.AddHangfireServer();

Đổi danh tính mặc định của job hệ thống:

config.UseTWorkContext(o =>
{
    o.DefaultSystemUsername = "svc-billing";
    o.DefaultSystemCaller   = "hangfire-nightly";
});

Không cần DI. TWorkContextJobFilter đọc/ghi qua TWorkContextAccessor, mà lớp đó giữ ngữ cảnh trong một AsyncLocal static — mọi instance dùng chung một ô nhớ. Nhờ vậy bộ lọc dựng được bằng new và không cần service provider.

2. Ngữ cảnh đi qua ranh giới job như thế nào

Theo loại job:

3. Hợp đồng trên dây: tham số wc:*

Hằng số ở JobParameterNames (public — gói cầu nối multi-tenancy đọc wc:siteCode). Tiền tố wc: để không đụng tham số nội bộ của Hangfire. Trường rỗng không được ghi.

Không đi qua ranh giới job (có chủ đích hoặc đã biết):

4. CorrelationId đổi mỗi lần chạy — có chủ đích

OnPerforming luôn sinh CorrelationId mới, không dùng lại cái đã enqueue. Một job retry 5 lần cho ra 5 CorrelationId khác nhau — nhờ vậy log của từng lần chạy tách bạch được.

Sợi dây nối về nguồn nằm ở Client.Caller:

Caller = "hangfire | <correlation-id-lúc-enqueue>"     ← có ngữ cảnh khi enqueue
Caller = "hangfire-worker"                             ← không có

Đừng tra cứu xuyên ranh giới job bằng CorrelationId — nó không còn giống nhau. Dùng Caller, hoặc trace.id (§5), vốn thực sự xuyên suốt.

5. Nối lại trace

OnCreating ghi traceparent (W3C) của Activity đang chạy; OnPerforming dựng một Activity con từ đó và dispose ở OnPerformed. Kết quả: trace.id trong log của job trùng với request đã enqueue nó.

Không có traceparent (recurring job) thì vẫn khởi một Activity mới — để bản ghi trong lúc chạy có trace.id riêng, thay vì rỗng.

6. Scope DI và cách ly giữa các job

Gói này không tạo scope nào. Khác TCIS.EventBus, nơi SubscribeInvoker tự mở một scope cho mỗi message (await using var scope = _serviceProvider.CreateAsyncScope()), ở Hangfire scope do JobActivator của host tạo — và bộ lọc chạy ngoài nó.

Thứ tự thật, đo trên Hangfire 1.8.18 (ghim bằng test Run_Server_Filters_Outside_The_Job_Scope):

OnPerforming (order tăng dần)  →  scope.begin  →  thân job  →  scope.dispose  →  OnPerformed (ngược lại)

Ba hệ quả:

Scope có được tạo hay không là việc của host, không phải của gói này. TCIS.Hangfire chỉ tham chiếu Hangfire.Core, mà Hangfire.Core dùng JobActivator mặc định — nó gọi Activator.CreateInstance, không có DI và không có scope. Muốn có scope một-job-một-scope thì host phải dùng AddHangfireServer() của Hangfire.NetCore/Hangfire.AspNetCore, vốn cài AspNetCoreJobActivator.

7. Job đa cảng

Thêm gói cầu nối, không phải sửa dòng nào trong job:

dotnet add package TCIS.Hangfire.MultiTenancy

builder.Services.AddTMultiTenant<TenantInfo>().WithConfigurationStore();

builder.Services.AddHangfire((sp, config) =>
{
    config.UseSqlServerStorage(connectionString);
    config.UseTWorkContext();             // ngữ cảnh nghiệp vụ
    config.UseTMultiTenantJobContext(sp); // hồ sơ tenant
});

Thứ tự thực thi là điều kiện đúng đắn, không phải thẩm mỹ: OnPerforming của gói này gán toàn bộ WorkContext mới, nên bộ lọc tenant chạy trước sẽ bị xoá sạch phần vừa nạp — hỏng im lặng, chỉ lộ ra khi job đầu tiên chạm database. Bảo đảm bằng Order: bộ lọc tenant đăng ký 100, còn UseTWorkContext() nhận DefaultOrder = -1 của Hangfire. Gõ hai dòng theo thứ tự nào cũng đúng.

Ứng dụng đơn tenant đơn giản là không gọi dòng thứ hai, và không có gì đổi.

Job phải quét tất cả cảng (bộ lọc không giúp được, vì job chỉ mang một mã cảng hoặc không mang mã nào) — xem md/14 §5 Cách 2.

8. Những chỗ dễ vấp