SU2.C15e.Infrastructure.Emailing 2.5.1-rc.1

SU2.C15e.Infrastructure.Emailing

SMTP adapter opt-in cho IEmailSender của SU2.C15e.Core.Interfaces. Worker chỉ cần package này, không cần SU2.C15e.Web.Defaults hoặc ASP.NET Core.

Đăng ký

using SU2.C15e.Infrastructure.Emailing;

builder.Services.AddMimeKitEmailSender(builder.Configuration);

Extension bind section Mailserver, validate options khi khởi động và đăng ký sender/pool dạng Singleton. Chỉ tham chiếu package không tự bật gửi thư.

Host là tên duy nhất cho địa chỉ SMTP (options.Host hoặc Mailserver:Host). Property Hostname đã bị xóa: phải đổi code, JSON và ENV của consumer sang Host, rồi biên dịch lại. Key cũ không còn bind vào Host; nếu chỉ khai key cũ, Host giữ default localhost. Host rỗng bị validation từ chối. Section riêng dùng AddMimeKitEmailSender(configuration, "Notification:Email:SmtpClient"), không cần map tên host ở consumer. Thay đổi này đang ở source chưa release; phải cập nhật package chứa API Host trước khi dùng.

Sender/pool dùng IOptionsMonitor<MailserverConfiguration>, không dùng IOptionsSnapshot (Scoped, không inject trực tiếp vào Singleton). Sender đọc CurrentValue; pool theo dõi OnChange để không tái sử dụng kết nối thuộc cấu hình cũ. Reload cần configuration provider hỗ trợ thông báo thay đổi; thay ENV không tự cập nhật process đang chạy. MaxConnections đọc khi tạo pool nên thay đổi cần restart. Custom ISmtpOAuth2TokenProvider phải phù hợp Singleton pool, không giữ dependency Scoped trực tiếp.

{
  "Mailserver": {
    "Host": "smtp.example.com",
    "Port": 587,
    "Security": "StartTls",
    "Authentication": "Basic",
    "UserName": "service-account",
    "DefaultFromAddress": "noreply@example.com",
    "MaxConnections": 4
  }
}

Truyền Mailserver:Password qua secret store/environment, không lưu mật khẩu trong source. OAuth2 dùng ISmtpOAuth2TokenProvider do service cung cấp.

Property C# Username đã đổi thành UserName, không giữ alias; consumer dùng property cũ phải sửa và biên dịch lại. Key chuẩn là Mailserver:UserName (ENV: Mailserver__UserName); configuration binder không phân biệt hoa/thường nên key Username cũ vẫn bind được.

Hành vi

• SendEmailAsync(to, from, subject, body) giữ API cũ; SendAsync(EmailMessage, CancellationToken) hỗ trợ HTML, To/Cc/Bcc/ReplyTo, attachment, inline resource và custom header.
• await hoàn thành khi SMTP server đã nhận thư; không phải queue/outbox hoặc bảo đảm giao tới hộp thư.
• Pool giới hạn số kết nối đồng thời; retry lỗi tạm thời có thể gửi trùng nếu server nhận thư trước khi kết nối bị ngắt. Consumer cần lưu ý semantics at-least-once.
• Package và namespace là SU2.C15e.Infrastructure.Emailing (trước đây SU2.C15e.Infrastructure.Email). Nâng cấp: đổi PackageReference + using, rồi biên dịch lại — không có type forwarding cho tên cũ.
• Code tự new/subclass sender theo constructor cũ dùng IOptionsSnapshot<MailserverConfiguration> phải chuyển sang IOptionsMonitor hoặc DI extension.

RedirectToTestRecipients (dev/SIT/UAT)

Tên cũ TestingMode đã bị xóa, không có alias. Đổi cả code/JSON/ENV sang RedirectToTestRecipients (ENV: Mailserver__RedirectToTestRecipients) và biên dịch lại. Chỉ giữ key cũ sẽ không bật redirect và có thể gửi thư tới người thật. Cờ mới mặc định false; đây không phải dry-run, email vẫn được gửi qua SMTP thật.

{ "Mailserver": { "RedirectToTestRecipients": true, "TestingRecipients": [ "qa-inbox@company.example" ] } }

Bật thì mọi thư bị chuyển hướng tới TestingRecipients: To/Cc/Bcc gốc bị thay toàn bộ nên người dùng thật không nhận thư. Reply-To cũng trỏ về TestingRecipients để tester bấm Reply không tới người thật. Địa chỉ gốc nằm ở header X-Original-To/Cc/Bcc/Reply-To, subject thêm TestingSubjectPrefix (mặc định [TEST] ), header Resent-* bị gỡ. TestingRecipients bắt buộc ≥ 1 địa chỉ hợp lệ khi bật. Không bật ở production.

Tuỳ biến

SendEmailAsync / SendAsync của MimeKitEmailSender và FakeEmailSender là virtual. Override nên gọi base để giữ pool, retry và RedirectToTestRecipients; đăng ký AddSingleton<IEmailSender, MySender>() sau AddMimeKitEmailSender.

Dependency và bảo mật

Package phụ thuộc Core, MailKit và Microsoft.Extensions cần thiết; không phụ thuộc Web/Common. MimeKit kéo System.Security.Cryptography.Pkcs gián tiếp; bản 10.0.0 dính GHSA-846f-f764-76mx (High) và GHSA-2fmv-rv2c-59x7 (Moderate). Package khai dependency tường minh System.Security.Cryptography.Pkcs 10.0.13 (bản vá) nên consumer restore nhận bản đã vá mà không cần tự pin.