ABP VNext + Twilio：全渠道通知服務（SMS/Email/WhatsApp） 🚀

---

---

一、引言 ?

• 📝 TL;DR

  1. 📡 使用 Twilio SDK + SendGrid 在 ABP VNext 中統一封裝 SMS、Email、WhatsApp 通道
  2. ?? 單例 RazorLight 引擎模板渲染，一行代碼推送多渠道
  3. 🔄 Outbox + Quartz + ABP Unit of Work 保證事務一致與高可用異步投遞
  4. 🔑 Azure Key Vault 管理密鑰；🐇 RabbitMQ 死信；📈 Prometheus 指標；???🩹 Health Checks；🗑 Quartz 清理

現代應用需在用戶注冊、訂單狀態、營銷推送等場景并發多渠道通知。原生調用缺少模板化、事務保障、限流重試、安全存儲和監控。

---

二、環境與依賴 🛠?

• 平臺：.NET 6 + ABP VNext 6.x

• NuGet 包：

  <PackageReference Include="Twilio" Version="5.*" />
  <PackageReference Include="SendGrid" Version="10.*" />
  <PackageReference Include="RazorLight" Version="2.*" />
  <PackageReference Include="Volo.Abp.BackgroundJobs" Version="6.*" />
  <PackageReference Include="Quartz.Extensions.Hosting" Version="3.*" />
  <PackageReference Include="Polly" Version="7.*" />
  <PackageReference Include="DistributedLock.Core" Version="6.*" />
  <PackageReference Include="Microsoft.Extensions.HealthChecks" Version="7.*" />
  <PackageReference Include="prometheus-net.AspNetCore" Version="7.*" />
  <PackageReference Include="Azure.Extensions.AspNetCore.Configuration.Secrets" Version="1.*" />
  <PackageReference Include="Microsoft.Azure.KeyVault" Version="4.*" />
  <PackageReference Include="RabbitMQ.Client" Version="7.*" />
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.*" />
  

• appsettings.json 示例

  {"KeyVault": {"Enabled": true,"VaultUri": "https://your-vault.vault.azure.net/"},"Twilio": { /*…*/ },"SendGrid": { /*…*/ },"Notification": {"MaxParallelism": 5,"QuartzCron": "0/30 * * * * ?","DeadLetterQueue": "notification.dlx"}
  }
  

---

三、系統架構概覽 🏗?

---

四、Secrets 管理 🔑

public override void ConfigureServices(ServiceConfigurationContext context)
{var cfg = context.Services.GetConfiguration();if (cfg.GetValue<bool>("KeyVault:Enabled")){context.ConfigurationBuilder.AddAzureKeyVault(new Uri(cfg["KeyVault:VaultUri"]),new DefaultAzureCredential());}context.Services.Configure<TwilioOptions>(cfg.GetSection("Twilio"));context.Services.Configure<SendGridOptions>(cfg.GetSection("SendGrid"));// …
}

Tip：生產環境通過 Key Vault 托管密鑰，安全可靠。

---

五、本地開發 Secrets 模擬 🏠

# 使用 .NET 用戶機密存儲
dotnet user-secrets init
dotnet user-secrets set "Twilio:AccountSid" "local-sid"
dotnet user-secrets set "Twilio:AuthToken"  "local-token"
dotnet user-secrets set "SendGrid:ApiKey"    "local-sendgrid-key"

本地調試時，appsettings.json 不包含敏感信息，使用用戶機密模擬 Key Vault。

---

六、客戶端封裝與插件化 🔌

1. 通道抽象

   public interface IChannelSender
   {Channel Channel { get; }Task SendAsync(string payloadJson, CancellationToken token = default);
   }
   

2. SmsSender

   public class SmsSender : IChannelSender, ITransientDependency
   {public Channel Channel => Channel.SMS;private readonly TwilioOptions _opts;public SmsSender(IOptions<TwilioOptions> opts) => _opts = opts.Value;public Task SendAsync(string payloadJson, CancellationToken token = default){var p = JsonSerializer.Deserialize<SmsPayload>(payloadJson)!;var client = new TwilioRestClient(_opts.AccountSid, _opts.AuthToken);return client.Messages.CreateAsync(to: new PhoneNumber(p.To),from: new PhoneNumber(_opts.FromPhone),body: p.Body, cancellationToken: token);}
   }
   

3. EmailSender、WhatsAppSender 類似，均注入 CancellationToken 支持。

4. 核心服務

   public class NotificationService : INotificationService, ITransientDependency
   {public async Task SendAsync(Channel channel, string templateKey, object model, string to, string? subjectKey = null){var body = await _tplMgr.RenderAsync($"{channel}/{templateKey}.cshtml", model);var subject = subjectKey == null ? null : await _tplMgr.RenderAsync($"Email/Subject_{subjectKey}.txt", model);var payload = JsonSerializer.Serialize(new { To = to, Subject = subject, Body = body });_db.NotificationOutboxes.Add(new NotificationOutbox(channel, payload));await _uow.SaveChangesAsync(); }
   }
   

---

七、模板管理 📄

public class RazorLightTemplateManager : ITemplateManager, ISingletonDependency
{private readonly RazorLightEngine _engine;public RazorLightTemplateManager(IConfiguration config){_engine = new RazorLightEngineBuilder().UseFileSystemProject(Path.Combine(AppContext.BaseDirectory, "Templates")).UseMemoryCachingProvider().Build();}public Task<string> RenderAsync(string key, object model) =>_engine.CompileRenderAsync(key, model);
}

/Templates├─ SMS/Sms_VerifyCode.cshtml├─ Email/Subject_OrderShipped.txt├─ Email/OrderShipped.cshtml└─ WhatsApp/Promotion.cshtml

---

八、事務與 Outbox 模式 🔄

public class NotificationOutbox : Entity<Guid>
{public Channel Channel { get; set; }public string Payload  { get; set; }public bool IsSent     { get; set; }public DateTime CreatedTime { get; set; }public int RetryCount  { get; set; }  // 死信限次public NotificationOutbox(Channel ch, string payload){Id = Guid.NewGuid();Channel = ch; Payload = payload;IsSent = false; RetryCount = 0;CreatedTime = DateTime.UtcNow;}
}

Tip：新增 RetryCount 字段，避免死信循環。

---

九、Quartz 調度與清理作業 ?

9.1 投遞調度

public class OutboxJobProcessor : IJob, ISingletonDependency
{private readonly CancellationTokenSource _cts = new();public async Task Execute(IJobExecutionContext _){var batch = await _db.NotificationOutboxes.Where(x=>!x.IsSent && x.RetryCount < 5).Take(NotificationConsts.MaxParallelism).ToListAsync(_cts.Token);foreach (var e in batch){try{using (_latency.NewTimer())using (await _lock.AcquireLockAsync($"lock-{e.Id}", TimeSpan.FromSeconds(30))){await Policy.WrapAsync(Policy.BulkheadAsync(NotificationConsts.MaxParallelism, int.MaxValue),Policy.RateLimitAsync(10, TimeSpan.FromSeconds(1)),Policy.Handle<Exception>().WaitAndRetryAsync(retryCount:3, sleepDurationProvider: i=>TimeSpan.FromSeconds(Math.Pow(2, i)),onRetry: (ex, _, i, _) => {e.RetryCount++;_logger.LogWarning("Outbox {Id} 第 {Count} 次重試", e.Id, i);})).ExecuteAsync(ct=> ProcessAsync(e, ct), _cts.Token);}_total.Inc();}catch (Exception ex){_logger.LogError(ex, "Outbox({Id}) 失敗，轉死信隊列", e.Id);_rabbit.BasicPublish("", _opts.DeadLetterQueue, null, Encoding.UTF8.GetBytes(e.Payload));}}}public Task StopAsync() => Task.Run(() => _cts.Cancel());private async Task ProcessAsync(NotificationOutbox e, CancellationToken token){var sender = _senders.First(s=>s.Channel==e.Channel);await sender.SendAsync(e.Payload, token);e.IsSent = true;await _db.SaveChangesAsync(token);}
}

9.2 清理作業

public class OutboxCleanupJob : IJob, ISingletonDependency
{public async Task Execute(IJobExecutionContext _){var cutoff = DateTime.UtcNow.AddDays(-30);var toDel = await _db.NotificationOutboxes.Where(x=>x.IsSent && x.CreatedTime<cutoff).Take(1000).ToListAsync();_db.RemoveRange(toDel);await _db.SaveChangesAsync();}
}

---

十、監控與健康檢查 📊???🩹

// Startup.ConfigureServices
services.AddHealthChecks().AddSqlServer(cfg.GetConnectionString("Default"), name:"sql").AddRabbitMQ(cfg["Notification:DeadLetterQueue"], name:"rabbitmq").AddUrlGroup("https://api.twilio.com", name:"twilio").AddUrlGroup("https://api.sendgrid.com", name:"sendgrid");app.UseHttpMetrics(); // Prometheus /metrics
app.UseEndpoints(e=>{e.MapHealthChecks("/health");e.MapMetrics();
});

---

十一、Twilio Webhook 與安全 🔒

[HttpPost("twilio-callback"), EnableRateLimiting("Default")]
public async Task<IActionResult> TwilioCallback(CancellationToken token)
{var req = Request; var form = await req.ReadFormAsync(token);var sig = req.Headers["X-Twilio-Signature"].FirstOrDefault()!;var url = $"{req.Scheme}://{req.Host}{req.Path}";var validator = new RequestValidator(_opts.AuthToken);if (!validator.Validate(url, form.ToDictionary(k=>k.Key, v=>v.Value.ToString()), sig))return Unauthorized();var sid = form["MessageSid"].ToString();var status = form["MessageStatus"].ToString();var e = await _db.NotificationOutboxes.Where(x=>x.Payload.Contains(sid)).FirstOrDefaultAsync(token);if (e!=null){e.IsSent = status=="delivered";await _db.SaveChangesAsync(token);}return Ok();
}

---

十二、死信補償 🎯

public class DeadLetterConsumer : BackgroundService
{protected override Task ExecuteAsync(CancellationToken ct){var channel = _rabbit.CreateModel();channel.BasicConsume("notification.dlx", false, new EventingBasicConsumer(channel){Received = async (_, ea) =>{if (ct.IsCancellationRequested) return;var payload = Encoding.UTF8.GetString(ea.Body.ToArray());await _db.NotificationOutboxes.AddAsync(new NotificationOutbox(Channel.SMS, payload), ct);await _db.SaveChangesAsync(ct);channel.BasicAck(ea.DeliveryTag, false);}});return Task.CompletedTask;}
}

---

參考文檔 📄

• Twilio 官方文檔
• SendGrid C# 快速入門
• Quartz Scheduler 文檔
• prometheus-net GitHub
• Azure Key Vault 文檔
• RabbitMQ 文檔