萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> ASP.NET 程式設計

ASP.NET 發送郵件完整指南:MailMessage、SmtpClient、附件、HTML、編碼與現代 MailKit 遷移

系統內建命名空間


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
SmtpClientSMTP 協議傳送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; }
}

關鍵技術細節

1. 編碼設定:防止中文亂碼


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 主機PortSSL/TLS備註
Gmailsmtp.gmail.com587STARTTLS需應用程式密碼 (兩步驟驗證後產生)
Outlook/Office365smtp.office365.com587STARTTLS支援 OAuth2 現代驗證
Yahoosmtp.mail.yahoo.com465/587SSL/STARTTLS需應用程式密碼
SendGridsmtp.sendgrid.net587STARTTLSAPI 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` 狀態碼進行除錯。

copyright © 萬盛學電腦網 all rights reserved