CrispyWaffle.Utils

CrispyWaffle.Utils contains communication helpers: an FTP client for uploading files and managing a remote directory, and an SMTP mailer for sending plain-text and HTML e-mail with attachments. It also has an extension that renders a MailMessage as raw EML and the exceptions these helpers throw.

SmtpMailer currently sends only when the application runs on .NET Framework (through the netstandard2.0 build). On .NET (Core) SendAsync throws before sending; see SMTP mailer.

How it works

FTP client

FtpClient works on one remote directory, set in the constructor. A trailing / on the directory is removed. Every URL is built as ftp://{host}:{port}/{remoteDirectory}/{path}. Requests use FtpWebRequest in passive mode with the configured credentials. Public methods take a lock, so one instance can be shared between threads, but calls run one at a time.

Whether a path is treated as a file or a directory depends on whether it has a file extension. A path with an extension is uploaded or deleted as a file; a path without one is created or removed as a directory.

Upload creates the remote directory if it does not exist, deletes an existing file with the same name, and then uploads the bytes. ClearDirectory deletes every entry listed in the remote directory, removes the directory, and creates it again empty.

FTP errors are wrapped in FtpClientException. An existence check that fails with a WebException is treated as "does not exist".

FtpWebRequest is marked obsolete in .NET 6 and later, and Microsoft recommends a third-party FTP library for new development.

SMTP mailer

SmtpMailer wraps one SmtpClient and one MailMessage. Create one instance per e-mail and dispose it after sending. The client always uses SSL and a timeout of 300 seconds. The sender comes from SmtpMailerOptions.FromAddress and FromName.

Build the message in this order:

1. SetSubject, SetRecipients, SetReplyTo, SetReadNotificationTo, SetPriority in any order.
2. SetMessageBody once. A second call throws MessageException.
3. AddAttachment, only after SetMessageBody with an HTML body; otherwise it throws (see the reference below).
4. SendAsync.

The plain-text body is the main body. When an HTML body is given, it is added as a text/html alternate view, so mail clients that support HTML show it instead.

SendAsync behaves as follows:

• It first renders the message with MailMessageExtensions.RawMessage, even when debug is off. That method only works on .NET Framework (see its reference entry), so on .NET (Core) SendAsync throws NullReferenceException before anything is sent.
• When SmtpMailerOptions.EnableDebug is true, the raw message is written as an .eml file through LogConsumer.DebugTo<TextFileLogProvider>, named {subject} {timestamp}.{guid}.eml.
• When SmtpMailerOptions.IsSandbox is true, nothing is sent. A trace entry is written and the method returns.
• Otherwise the message is sent with SmtpClient.SendMailAsync.

Send errors are tracked with TelemetryAnalytics.TrackMetric("SMTPError", message) and then handled by type:

• Socket errors (an inner-inner SocketException) and SMTP replies containing 4.7.1 or 5.0.3 store a flag in CacheManager for 15 minutes, keyed by the calling method. While the flag exists, SendAsync calls from the same method skip sending without an error. The exception is not rethrown. This only works when a cache repository is registered with CacheManager.
• Replies containing 4.4.2 or 4.7.0 are rethrown.
• Any other exception is passed to LogConsumer.Handle and not rethrown.

In other words, SendAsync completing does not mean the e-mail was delivered.

Getting started

using System.Collections.Generic;
using CrispyWaffle.Utils.Communications;

using var mailer = new SmtpMailer(
    "smtp.example.com",
    587,
    "user@example.com",
    "password",
    "Example App",
    "no-reply@example.com"
);

mailer.SetSubject("Welcome");
mailer.SetRecipients(new Dictionary<string, string> { ["Jane Doe"] = "jane@example.com" });
mailer.SetMessageBody("Welcome to Example App.", "<p>Welcome to <b>Example App</b>.</p>");

await mailer.SendAsync();

Reference

SmtpMailer

public class SmtpMailer : IMailer — builds and sends one e-mail through an SMTP server.

The class has [ConnectionName("SMTP")].

IMailer

public interface IMailer : IDisposable — contract for a mailer. SmtpMailer is the only implementation in the package.

SmtpMailerOptions

public class SmtpMailerOptions — sender and behavior settings for SmtpMailer.

FtpClient

public class FtpClient — uploads files to and manages one directory on an FTP server.

MailMessageExtensions

public static class MailMessageExtensions — extension methods for System.Net.Mail.MailMessage.

FtpClientException

public class FtpClientException : Exception — thrown by FtpClient when an FTP operation fails. Marked [Serializable].

MessageException

public class MessageException : Exception — thrown by SmtpMailer.SetMessageBody when the body was already set. Message: The message cannot be set more than once for the same instance of Email class. Marked [Serializable].

NullMessageException

public class NullMessageException : Exception — thrown by SmtpMailer.AddAttachment when the body has not been set. Message: Unable to set the attachment of message before the message itself. Marked [Serializable].

Examples

Send an e-mail with a stored connection and an attachment

Use a Connection from configuration and SmtpMailerOptions to keep sending off in test environments.

using System.Collections.Generic;
using System.IO;
using System.Net.Mail;
using System.Text;
using CrispyWaffle.Configuration;
using CrispyWaffle.Utils.Communications;

var connection = new Connection
{
    Host = "smtp.example.com",
    Port = 587,
    Credentials = { Username = "user@example.com", Password = "password" },
};

var options = new SmtpMailerOptions
{
    FromAddress = "reports@example.com",
    FromName = "Reports",
    IsSandbox = false,
};

using var mailer = new SmtpMailer(connection, options);

mailer.SetSubject("Daily report");
mailer.SetRecipients(new Dictionary<string, string> { ["Ops"] = "ops@example.com" });
mailer.SetReplyTo("Support", "support@example.com");
mailer.SetPriority(MailPriority.High);
mailer.SetMessageBody("The daily report is attached.", "<p>The daily report is attached.</p>");

var csv = new MemoryStream(Encoding.UTF8.GetBytes("date,total\n2024-01-01,10\n"));
mailer.AddAttachment(new Attachment(csv, "report.csv", "text/csv"));

await mailer.SendAsync();

Upload a file over FTP

Upload a file to /exports on the server, replacing any file with the same name.

using System.IO;
using CrispyWaffle.Utils.Communications;
using CrispyWaffle.Utils.GoodPractices;

var ftp = new FtpClient("ftp.example.com", 21, "user", "password", "exports/");

try
{
    var uploaded = ftp.Upload("report.csv", File.ReadAllBytes("report.csv"));
}
catch (FtpClientException e)
{
    // e.Message: "Unable to create the path/file report.csv in the FtpClient host. Status code: 0"
}

Save a message as an EML file

RawMessage returns the message exactly as it would be sent. This works on .NET Framework only.

using System.IO;
using System.Net.Mail;
using CrispyWaffle.Utils.Extensions;

using var message = new MailMessage("from@example.com", "to@example.com", "Subject", "Body");
using var raw = message.RawMessage();
using var file = File.Create("message.eml");
raw.CopyTo(file);

See also

• CrispyWaffle.Configuration
• Logging
• Caching
• Telemetry