Cyclops.EmailKit

项目概述

Cyclops.EmailKit是企服版框架中的专业邮件处理套件，提供了完整的邮件收发解决方案。该项目基于MailKit库构建，支持SMTP邮件发送、POP3和IMAP邮件接收等核心功能，为企业级应用提供了稳定可靠的邮件通信能力。通过统一的接口和灵活的配置，Cyclops.EmailKit使开发者能够轻松集成邮件功能，实现通知、报表、通信等业务需求。

核心功能模块

1. 邮件客户端接口

1.1 统一客户端接口

• IEMailClient：所有邮件客户端的统一接口，定义了邮件操作的基本方法

1.2 客户端类型枚举

• EnumClientType：定义了支持的邮件客户端类型，包括SMTP、POP3、IMAP等

2. 邮件发送系统

2.1 SMTP客户端

• EMailSmtp：基于SMTP协议的邮件发送客户端实现
• 功能特性：
  • 支持普通文本邮件和HTML邮件
  • 支持附件发送（多种格式）
  • 支持抄送、密送功能
  • 支持自定义邮件头
  • 支持邮件优先级设置
  • 支持SSL/TLS加密连接
  • 支持不同的SMTP服务器配置

3. 邮件接收系统

3.1 POP3客户端

• EMailPop3：基于POP3协议的邮件接收客户端实现
• 功能特性：
  • 支持邮件列表获取
  • 支持邮件内容下载
  • 支持邮件删除操作
  • 支持未读邮件筛选
  • 支持SSL/TLS加密连接

3.2 IMAP客户端

• EMailImap：基于IMAP协议的邮件接收客户端实现
• 功能特性：
  • 支持邮箱文件夹管理
  • 支持邮件搜索和过滤
  • 支持邮件移动和复制
  • 支持邮件标记（已读/未读/标记等）
  • 支持SSL/TLS加密连接
  • 支持部分邮件内容获取
  • 支持邮件状态监控

4. 邮件工厂

4.1 客户端工厂

• EMailFactory：邮件客户端工厂类，负责创建不同类型的邮件客户端实例
• 功能特性：
  • 根据配置创建对应的邮件客户端
  • 支持客户端实例缓存和复用
  • 提供统一的客户端创建入口

5. 邮件配置

5.1 配置选项

• EMailOptions：邮件服务配置选项，包含SMTP、POP3、IMAP的各种配置参数
• 配置项：
  • 服务器地址和端口
  • 用户名和密码
  • SSL/TLS设置
  • 超时设置
  • 最大重试次数
  • 代理设置
  • 连接池配置

6. 邮件数据模型

6.1 核心数据模型

• Message：邮件消息模型，包含邮件的完整内容和元数据
• MsgInput：邮件输入模型，用于创建和发送新邮件
• Attachment：邮件附件模型，支持多种附件格式
• Header：邮件头模型，包含邮件的各种头信息
• UserAddress：用户地址模型，定义发件人、收件人、抄送、密送等

技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • MailKit (4.14.1) - 专业的邮件处理库
  • Cyclops.Common - 提供基础工具类支持

环境依赖要求

• .NET 8.0 SDK 或更高版本
• 有效的邮件服务器账户（用于测试和生产）
• 对于生产环境，建议配置专用的邮件服务器或第三方邮件服务

安装与配置

安装方式

可以通过以下方式安装Cyclops.EmailKit包：

1. NuGet包管理器：

   Install-Package TJC.Cyclops.EmailKit

2. .NET CLI：

   dotnet add package TJC.Cyclops.EmailKit

基本配置

在应用程序中配置邮件服务：

// 在配置文件中（appsettings.json） { "EMailOptions": { "SmtpHost": "smtp.example.com", "SmtpPort": 587, "SmtpUsername": "username@example.com", "SmtpPassword": "password", "SmtpUseSsl": true, "Pop3Host": "pop.example.com", "Pop3Port": 995, "Pop3Username": "username@example.com", "Pop3Password": "password", "Pop3UseSsl": true, "ImapHost": "imap.example.com", "ImapPort": 993, "ImapUsername": "username@example.com", "ImapPassword": "password", "ImapUseSsl": true, "Timeout": 60, "MaxRetryCount": 3 } } // 在应用程序启动时 public void ConfigureServices(IServiceCollection services) { // 从配置中绑定邮件选项 services.Configure<EMailOptions>(Configuration.GetSection("EMailOptions")); // 注册邮件工厂 services.AddSingleton<EMailFactory>(); // 注册邮件服务 services.AddScoped<IMailService, MailService>(); }

核心功能代码示例

1. 发送普通文本邮件

public class MailService : ITransient { private readonly EMailFactory _emailFactory; public MailService(EMailFactory emailFactory) { _emailFactory = emailFactory; } public async Task SendTextEmailAsync(string to, string subject, string body) { // 获取SMTP客户端 var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP); // 创建邮件消息 var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = to } }, Subject = subject, Body = body, IsBodyHtml = false }; // 发送邮件 await smtpClient.SendAsync(msgInput); } }

2. 发送HTML邮件

public async Task SendHtmlEmailAsync(string to, string subject, string htmlBody) { var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP); var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = to } }, Subject = subject, Body = htmlBody, IsBodyHtml = true }; await smtpClient.SendAsync(msgInput); }

3. 发送带附件的邮件

public async Task SendEmailWithAttachmentAsync(string to, string subject, string body, string filePath) { var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP); var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = to } }, Subject = subject, Body = body, IsBodyHtml = true, Attachments = new List<Attachment> { new Attachment { FileName = Path.GetFileName(filePath), FileContent = await File.ReadAllBytesAsync(filePath), ContentType = MimeTypes.GetMimeType(filePath) } } }; await smtpClient.SendAsync(msgInput); }

4. 接收邮件（POP3）

public async Task<List<Message>> ReceiveEmailsPop3Async(int maxCount = 10) { var pop3Client = await _emailFactory.GetClientAsync(EnumClientType.POP3) as EMailPop3; if (pop3Client == null) throw new InvalidOperationException("POP3 client not available"); // 获取邮件数量 var count = await pop3Client.GetMessageCountAsync(); // 限制获取数量 count = Math.Min(count, maxCount); var messages = new List<Message>(); // 获取最近的邮件 for (int i = 1; i <= count; i++) { var message = await pop3Client.GetMessageAsync(i); messages.Add(message); } return messages; }

5. 接收邮件（IMAP）

public async Task<List<Message>> ReceiveUnreadEmailsImapAsync(string folderName = "INBOX", int maxCount = 10) { var imapClient = await _emailFactory.GetClientAsync(EnumClientType.IMAP) as EMailImap; if (imapClient == null) throw new InvalidOperationException("IMAP client not available"); // 选择邮件文件夹 await imapClient.SelectFolderAsync(folderName); // 搜索未读邮件 var unreadMessages = await imapClient.SearchUnreadMessagesAsync(maxCount); return unreadMessages; }

6. 自定义邮件配置

public async Task SendEmailWithCustomConfigAsync(string to, string subject, string body) { // 创建自定义配置 var customOptions = new EMailOptions { SmtpHost = "custom-smtp.example.com", SmtpPort = 465, SmtpUsername = "custom@example.com", SmtpPassword = "custom-password", SmtpUseSsl = true, Timeout = 30 }; // 使用自定义配置获取客户端 var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP, customOptions); var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = to } }, Subject = subject, Body = body, IsBodyHtml = false }; await smtpClient.SendAsync(msgInput); }

7. 邮件模板使用

public async Task SendTemplatedEmailAsync(string to, string templateName, Dictionary<string, string> replacements) { // 加载邮件模板 var templateBody = await LoadTemplateAsync(templateName); // 替换模板变量 var body = ReplaceTemplateVariables(templateBody, replacements); var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP); var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = to } }, Subject = replacements.ContainsKey("Subject") ? replacements["Subject"] : "Notification", Body = body, IsBodyHtml = true }; await smtpClient.SendAsync(msgInput); }

高级功能示例

1. 批量发送邮件

public async Task SendBulkEmailsAsync(List<string> recipients, string subject, string body) { var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP); foreach (var recipient in recipients) { try { var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = recipient } }, Subject = subject, Body = body, IsBodyHtml = true }; await smtpClient.SendAsync(msgInput); // 添加延迟避免触发邮件服务器限制 await Task.Delay(1000); } catch (Exception ex) { Logger.Error($"Failed to send email to {recipient}: {ex.Message}", ex); // 继续处理下一个收件人 } } }

2. 邮件队列实现

public async Task EnqueueEmailAsync(string to, string subject, string body) { // 将邮件信息保存到队列数据库或消息队列 var emailQueueItem = new EmailQueueItem { To = to, Subject = subject, Body = body, CreatedAt = DateTime.Now, Status = EmailQueueStatus.Pending }; await _dbContext.EmailQueue.AddAsync(emailQueueItem); await _dbContext.SaveChangesAsync(); } // 后台任务处理邮件队列 public async Task ProcessEmailQueueAsync(CancellationToken stoppingToken) { var smtpClient = await _emailFactory.GetClientAsync(EnumClientType.SMTP); while (!stoppingToken.IsCancellationRequested) { // 获取待发送的邮件 var pendingEmails = await _dbContext.EmailQueue .Where(e => e.Status == EmailQueueStatus.Pending) .OrderBy(e => e.CreatedAt) .Take(10) .ToListAsync(); foreach (var email in pendingEmails) { try { var msgInput = new MsgInput { To = new List<UserAddress> { new UserAddress { Email = email.To } }, Subject = email.Subject, Body = email.Body, IsBodyHtml = email.IsHtml }; await smtpClient.SendAsync(msgInput); // 更新邮件状态 email.Status = EmailQueueStatus.Sent; email.SentAt = DateTime.Now; } catch (Exception ex) { Logger.Error($"Failed to send queued email {email.Id}: {ex.Message}", ex); // 更新失败状态 email.Status = EmailQueueStatus.Failed; email.ErrorMessage = ex.Message; email.RetryCount++; // 如果重试次数未达到上限，设置为可重试 if (email.RetryCount < 3) { email.Status = EmailQueueStatus.RetryPending; email.NextRetryAt = DateTime.Now.AddMinutes(5 * email.RetryCount); } } } await _dbContext.SaveChangesAsync(); // 等待下一次处理 await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken); } }

使用注意事项

1. SMTP服务器配置：使用前请确保SMTP服务器配置正确，特别是端口和SSL/TLS设置

2. 邮件发送频率限制：注意控制邮件发送频率，避免触发邮件服务器的限制机制

3. 敏感信息保护：邮件配置中的密码等敏感信息应妥善保管，建议使用配置中心或密钥管理服务

4. 附件大小限制：注意邮件服务器可能对附件大小有限制，大文件建议使用链接替代

5. 编码处理：发送中文或其他非ASCII字符时，注意编码设置

6. 异常处理：邮件发送可能因网络问题失败，建议添加重试机制

7. 内存管理：处理大量邮件或大附件时，注意内存使用情况，及时释放资源

8. 性能优化：对于批量邮件操作，考虑使用异步方法和并发处理

9. 安全考虑：使用SSL/TLS加密连接，避免明文传输邮件内容和凭据

10. 日志记录：记录邮件发送状态和结果，便于问题排查和业务追踪

贡献者

• yswenli

许可证

保留所有权利