using System.Net.Mail; // 核心類別:MailMessage, SmtpClient, Attachment
using System.Net; // NetworkCredential
using System.Text; // Encoding
| 類別 | 職責 | 關鍵屬性/方法 |
|---|---|---|
| MailMessage | 郵件內容建構 | From, To, CC, Bcc, Subject, Body, IsBodyHtml, Attachments, Priority, BodyEncoding, Headers |
| SmtpClient | SMTP 協議傳送 | Host, Port, EnableSsl, Credentials, DeliveryMethod, Timeout, Send/MailAsync |
| Attachment | 附件封裝 | ContentStream, ContentType, Name, ContentDisposition, TransferEncoding |
| AlternateView | 多格式內容 (純文字+HTML) | ContentStream, ContentType, LinkedResources (內嵌圖片) |
public class EmailService
{
private readonly SmtpSettings _settings;
public EmailService(SmtpSettings settings) => _settings = settings;
///
/// 發送郵件 (非同步推薦)
///
public async Task SendAsync(MailRequest request)
{
using (var message = new MailMessage())
using (var client = CreateSmtpClient())
{
try
{
// 寄件者
message.From = new MailAddress(_settings.FromEmail, _settings.FromName, Encoding.UTF8);
// 收件者
request.To.ForEach(t => message.To.Add(new MailAddress(t)));
request.CC.ForEach(c => message.CC.Add(new MailAddress(c)));
request.Bcc.ForEach(b => message.Bcc.Add(new MailAddress(b)));
// 主旨與內容
message.Subject = request.Subject;
message.SubjectEncoding = Encoding.UTF8;
message.Body = request.Body;
message.BodyEncoding = Encoding.UTF8;
message.IsBodyHtml = request.IsHtml;
message.Priority = request.Priority;
// 附件
foreach (var att in request.Attachments)
{
message.Attachments.Add(new Attachment(att.Stream, att.FileName, att.MimeType));
}
// 內嵌圖片 (HTML 郵件用
)
foreach (var linked in request.LinkedResources)
{
var lr = new LinkedResource(linked.Stream, linked.MimeType);
lr.ContentId = linked.ContentId;
lr.TransferEncoding = TransferEncoding.Base64;
message.AlternateViews.Add(AlternateView.CreateAlternateViewFromString(
request.Body, Encoding.UTF8, MediaTypeNames.Text.Html));
// 注意:AlternateView 需正確建構,此處簡化
}
await client.SendMailAsync(message);
return true;
}
catch (SmtpException ex)
{
// 記錄詳細錯誤: ex.StatusCode, ex.Message
return false;
}
catch (Exception ex)
{
// 網路、憑證、逾時等
return false;
}
}
}
private SmtpClient CreateSmtpClient()
{
return new SmtpClient(_settings.Host, _settings.Port)
{
EnableSsl = _settings.EnableSsl,
Credentials = new NetworkCredential(_settings.UserName, _settings.Password),
Timeout = _settings.TimeoutSeconds * 1000,
DeliveryMethod = SmtpDeliveryMethod.Network
};
}
}
// 設定類別 (可從 appsettings.json 繫結)
public class SmtpSettings
{
public string Host { get; set; } = "smtp.gmail.com";
public int Port { get; set; } = 587;
public bool EnableSsl { get; set; } = true;
public string UserName { get; set; }
public string Password { get; set; }
public string FromEmail { get; set; }
public string FromName { get; set; }
public int TimeoutSeconds { get; set; } = 60;
}
public class MailRequest
{
public List To { get; set; } = new();
public List CC { get; set; } = new();
public List Bcc { get; set; } = new();
public string Subject { get; set; }
public string Body { get; set; }
public bool IsHtml { get; set; } = true;
public MailPriority Priority { get; set; } = MailPriority.Normal;
public List Attachments { get; set; } = new();
public List LinkedResources { get; set; } = new();
}
public class AttachmentInfo
{
public Stream Stream { get; set; }
public string FileName { get; set; }
public string MimeType { get; set; }
}
public class LinkedResourceInfo
{
public Stream Stream { get; set; }
public string ContentId { get; set; }
public string MimeType { get; set; }
}
message.SubjectEncoding = Encoding.UTF8; // 主旨編碼
message.BodyEncoding = Encoding.UTF8; // 內文編碼
message.HeadersEncoding = Encoding.UTF8; // 標頭編碼 (含附件檔名)
```
**附件檔名編碼**:`System.Net.Mail` 內建支援 RFC 2231 編碼,檔名含中文會自動編碼為 `=?utf-8?B?...?=`,現代客戶端皆支援。
2. HTML 郵件 + 純文字替代內容
var htmlView = AlternateView.CreateAlternateViewFromString(htmlBody, Encoding.UTF8, "text/html");
var textView = AlternateView.CreateAlternateViewFromString(plainTextBody, Encoding.UTF8, "text/plain");
message.AlternateViews.Add(htmlView);
message.AlternateViews.Add(textView); // 郵件客戶端自動選擇顯示
```
3. 內嵌圖片 (CID)
var logo = new LinkedResource("logo.png", "image/png");
logo.ContentId = "companyLogo"; // 對應 HTML:
logo.TransferEncoding = TransferEncoding.Base64;
var htmlView = AlternateView.CreateAlternateViewFromString(
"
內容
",
Encoding.UTF8, "text/html");
htmlView.LinkedResources.Add(logo);
message.AlternateViews.Add(htmlView);
4. 大量附件/大檔案處理
- 使用 `FileStream` 而非 `MemoryStream` 避免記憶體壓力
- 考慮上傳至雲端儲存 (Blob/S3) 並在郵件中放下載連結
- SMTP 伺服器通常限制單封大小 (25MB~50MB)
常見 SMTP 供應商設定
供應商 SMTP 主機 Port SSL/TLS 備註
Gmail smtp.gmail.com 587 STARTTLS 需應用程式密碼 (兩步驟驗證後產生)
Outlook/Office365 smtp.office365.com 587 STARTTLS 支援 OAuth2 現代驗證
Yahoo smtp.mail.yahoo.com 465/587 SSL/STARTTLS 需應用程式密碼
SendGrid smtp.sendgrid.net 587 STARTTLS API Key 做密碼
自架 Postfix 自訂 25/587/465 視設定 需正確設定 SPF/DKIM/DMARC
遷移至 MailKit / MimeKit (強烈推薦)
`System.Net.Mail` 存在已知問題:
- 不支援 OAuth2 現代驗證 (Gmail/Office365 必須)
- 不支援 SMTPS (隱含 SSL port 465) 穩定連線
- 大附件記憶體管理較弱
- .NET Core 跨平台支援不完整
MailKit 發送範例 (現代標準)
using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;
public async Task SendWithMailKitAsync(MailRequest request)
{
var message = new MimeMessage();
message.From.Add(new MailboxAddress(_settings.FromName, _settings.FromEmail));
request.To.ForEach(t => message.To.Add(MailboxAddress.Parse(t)));
request.CC.ForEach(c => message.Cc.Add(MailboxAddress.Parse(c)));
message.Subject = request.Subject;
var builder = new BodyBuilder();
if (request.IsHtml)
{
builder.HtmlBody = request.Body;
// 內嵌圖片
foreach (var linked in request.LinkedResources)
{
var lr = builder.LinkedResources.Add(linked.ContentId, linked.Stream);
lr.ContentType = ContentType.Parse(linked.MimeType);
}
}
else
{
builder.TextBody = request.Body;
}
// 附件
foreach (var att in request.Attachments)
{
var attachment = builder.Attachments.Add(att.FileName, att.Stream);
attachment.ContentType = ContentType.Parse(att.MimeType);
}
message.Body = builder.ToMessageBody();
using (var client = new SmtpClient())
{
// 支援 OAuth2: client.Authenticate(new SaslMechanismOAuth2(user, accessToken));
await client.ConnectAsync(_settings.Host, _settings.Port, _settings.EnableSsl ? SecureSocketOptions.StartTls : SecureSocketOptions.Auto);
await client.AuthenticateAsync(_settings.UserName, _settings.Password);
await client.SendAsync(message);
await client.DisconnectAsync(true);
}
}
FluentEmail 高階封裝 (推薦架構)
// 註冊 (Startup.cs)
services.AddFluentEmail("noreply@example.com", "系統通知")
.AddMailKitSender(new SmtpClientOptions
{
Server = "smtp.gmail.com",
Port = 587,
User = "user",
Password = "app-password",
UseSsl = true
})
.AddRazorRenderer(); // 支援 Razor 模板
// 使用
await _emailSender.SendAsync(email => email
.To("user@example.com")
.Subject("歡迎")
.UsingTemplate("Welcome.cshtml", new { UserName = "張三" })
.AttachFromFile("attachment.pdf"));
總結
ASP.NET 發送郵件核心類別為 `MailMessage` + `SmtpClient`。關鍵點:**UTF-8 編碼全開**、**HTML/純文字替代視圖**、**附件使用 FileStream**、**內嵌圖片用 CID**、**非同步 SendMailAsync**。**強烈建議遷移至 MailKit/MimeKit/FluentEmail** 獲得 OAuth2 支援、更好記憶體管理、跨平台相容、主動維護的現代化郵件發送堆疊。舊專案若暫時無法遷移,確保 `SmtpClient` 正確 `Dispose`、使用 `EnableSsl=true` (STARTTLS)、設定足夠 `Timeout` 並記錄完整 `SmtpException` 狀態碼進行除錯。