Class SmtpAppender

Namespace

log4net.Ext.Mail.Appender

Assembly

log4net.Ext.Mail.dll

Send an e-mail when a specific logging event occurs, typically on errors or fatal errors, using MailKit as the SMTP client.

public class SmtpAppender : BufferingAppenderSkeleton, IBulkAppender, IAppender, IOptionHandler, IFlushable

Inheritance

object

AppenderSkeleton

BufferingAppenderSkeleton

SmtpAppender

Implements

IBulkAppender

IAppender

IOptionHandler

IFlushable

Inherited Members

BufferingAppenderSkeleton.Lossy

BufferingAppenderSkeleton.BufferSize

BufferingAppenderSkeleton.Evaluator

BufferingAppenderSkeleton.LossyEvaluator

BufferingAppenderSkeleton.Fix

BufferingAppenderSkeleton.Flush()

BufferingAppenderSkeleton.Flush(bool)

BufferingAppenderSkeleton.Append(LoggingEvent)

BufferingAppenderSkeleton.SendFromBuffer(LoggingEvent, CyclicBuffer)

AppenderSkeleton.Threshold

AppenderSkeleton.ErrorHandler

AppenderSkeleton.FilterHead

AppenderSkeleton.Layout

AppenderSkeleton.Name

AppenderSkeleton.Close()

AppenderSkeleton.DoAppend(LoggingEvent)

AppenderSkeleton.DoAppend(LoggingEvent[])

AppenderSkeleton.FilterEvent(LoggingEvent)

AppenderSkeleton.AddFilter(IFilter)

AppenderSkeleton.ClearFilters()

AppenderSkeleton.IsAsSevereAsThreshold(Level)

AppenderSkeleton.Append(LoggingEvent[])

AppenderSkeleton.Append(IEnumerable<LoggingEvent>)

AppenderSkeleton.PreAppendCheck()

AppenderSkeleton.RenderLoggingEvent(LoggingEvent)

AppenderSkeleton.RenderLoggingEvent(TextWriter, LoggingEvent)

AppenderSkeleton.LockObj

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This appender exposes the same options as SmtpAppender, so an existing configuration can be pointed at this type without change. The difference is the transport: it sends through SmtpClient instead of the obsolete SmtpClient.

The number of logging events delivered in this e-mail depend on the value of BufferSize option. The SmtpAppender keeps only the last BufferSize logging events in its cyclic buffer. This keeps memory requirements at a reasonable level while still delivering useful application context.

Authentication is supported by setting the Authentication property to either Basic or Ntlm. If using Basic authentication then the Username and Password properties must also be set.

To set the SMTP server port use the Port property. The default port is 25.

Unlike SmtpClient, MailKit has no notion of a machine-wide default SMTP server, so SmtpHost is required.

Constructors

SmtpAppender()

Default constructor. Sends through log4net.Ext.Mail.Appender.Internal.MailKitSmtpTransport.

public SmtpAppender()

Properties

Authentication

The mode to use to authentication with the SMTP server

public SmtpAppender.SmtpAuthentication Authentication { get; set; }

Property Value

SmtpAppender.SmtpAuthentication

Remarks

Valid Authentication mode values are: None, Basic, and Ntlm. The default value is None. When using Basic you must specify the Username and Password to use to authenticate.

Ntlm authenticates with the NTLM SASL mechanism. Note that MailKit cannot reuse the Windows logon session of the current thread or process the way SmtpClient could, so Username and Password must be supplied for NTLM as well.

Bcc

Gets or sets a comma-delimited list of recipient e-mail addresses that will be blind carbon copied.

public string? Bcc { get; set; }

Property Value

string

A comma-delimited list of e-mail addresses.

Remarks

Semicolons are also accepted as separators, for backward compatibility.

BodyEncoding

Gets or sets the body encoding to be used.

public Encoding BodyEncoding { get; set; }

Property Value

Encoding

Remarks

The default encoding is UTF8.

Cc

Gets or sets a comma-delimited list of recipient e-mail addresses that will be carbon copied.

public string? Cc { get; set; }

Property Value

string

EnableSsl

Enable or disable use of SSL/TLS when sending e-mail message

public bool EnableSsl { get; set; }

Property Value

bool

Remarks

This is a shorthand for TransportSecurity: setting it to true selects Required and setting it to false selects None. The two properties are the same setting, so the one assigned last wins.

When true, which is the default, transport security is required: implicit TLS on port 465 and STARTTLS on every other port. Connecting fails if the server does not offer TLS, rather than continuing unencrypted, which matches the behaviour, though not the default, of EnableSsl. Use TransportSecurity when the server needs something else.

EnqueueTimeoutMillis

How long a logging call waits for room in a full queue. Defaults to 5000, 0 never waits.

public int EnqueueTimeoutMillis { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value specified is negative.

From

Gets or sets the e-mail address of the sender.

public string? From { get; set; }

Property Value

string

The e-mail address of the sender.

Password

The password to use to authenticate with the SMTP server

public string? Password { get; set; }

Property Value

string

Remarks

A Username and Password must be specified when Authentication is set to Basic or Ntlm, otherwise the password will be ignored.

Port

The port on which the SMTP server is listening

public int Port { get; set; }

Property Value

int

Remarks

The port on which the SMTP server is listening. The default port is 25.

Priority

Gets or sets the priority of the e-mail message

public MailPriority Priority { get; set; }

Property Value

MailPriority

One of the MailPriority values.

Remarks

Sets the priority of the e-mails generated by this appender. The default priority is Normal.

If you are using this appender to report errors then you may want to set the priority to High.

The value is mapped onto the MIME Priority header: Low becomes NonUrgent, Normal becomes Normal and High becomes Urgent.

ReplyTo

Gets or sets the reply-to e-mail address.

public string? ReplyTo { get; set; }

Property Value

string

RequiresLayout

This appender requires a Layout to be set.

protected override bool RequiresLayout { get; }

Property Value

bool

SendQueueSize

How many rendered mails may wait to be sent. Defaults to 500.

public int SendQueueSize { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value specified is not positive.

SendTimeoutMillis

A deadline for the whole send, in milliseconds. Defaults to 15000.

public int SendTimeoutMillis { get; set; }

Property Value

int

Remarks

MailKit's own timeout applies per operation, so a server answering just inside it can still take a multiple of it. The mail goes out under the appender lock.

Exceptions

ArgumentOutOfRangeException

The value specified is not positive.

SmtpHost

Gets or sets the name of the SMTP relay mail server to use to send the e-mail messages.

public string? SmtpHost { get; set; }

Property Value

string

The name of the e-mail relay server.

Remarks

This option is required. MailKit, unlike SmtpClient, has no machine-wide default SMTP server to fall back on.

Subject

Gets or sets the subject line of the e-mail message.

public string? Subject { get; set; }

Property Value

string

The subject line of the e-mail message.

SubjectEncoding

Gets or sets the subject encoding to be used.

public Encoding SubjectEncoding { get; set; }

Property Value

Encoding

Remarks

The default encoding is UTF8.

To

Gets or sets a comma-delimited list of recipient e-mail addresses.

public string? To { get; set; }

Property Value

string

TransportSecurity

Gets or sets how the connection to the SMTP server is secured.

public SmtpTransportSecurity TransportSecurity { get; set; }

Property Value

SmtpTransportSecurity

One of the SmtpTransportSecurity values. The default is Required; set it to None to allow a cleartext connection.

Remarks

EnableSsl is a shorthand for this property and covers the usual cases; set this one when the server expects implicit TLS on a port other than 465, or when only opportunistic STARTTLS is possible.

Username

The username to use to authenticate with the SMTP server

public string? Username { get; set; }

Property Value

string

Remarks

A Username and Password must be specified when Authentication is set to Basic or Ntlm, otherwise the username will be ignored.

Methods

ActivateOptions()

Initialize the appender based on the options set

public override void ActivateOptions()

Remarks

This is part of the IOptionHandler delayed object activation scheme. The ActivateOptions() method must be called on this object after the configuration properties have been set. Until ActivateOptions() is called this object is in an undefined state and must not be used.

If any of the configuration properties are modified then ActivateOptions() must be called again.

CreateMessage(string)

Builds the MimeMessage for the given body text from the configured options.

[CLSCompliant(false)]
protected virtual MimeMessage CreateMessage(string messageBody)

Parameters

messageBody string

the body text to include in the mail

Returns

MimeMessage

the message to send

Remarks

Not CLS compliant, because MimeMessage comes from MimeKit, which does not declare itself CLS compliant.

Flush(int)

Flushes any buffered log data.

public override bool Flush(int millisecondsTimeout)

Parameters

millisecondsTimeout int

Unused: the buffer is sent on the calling thread, so there is nothing to wait for.

Returns

bool

false when events are still buffered afterwards, which is what a Lossy appender does: it keeps them until a triggering event arrives.

OnClose()

Close this appender instance.

protected override void OnClose()

Remarks

Close this appender instance. If this appender is marked as not Lossy then the remaining events in the buffer must be sent when the appender is closed.

SendBuffer(LoggingEvent[])

Sends the contents of the cyclic buffer as an e-mail message.

protected override void SendBuffer(LoggingEvent[] events)

Parameters

events LoggingEvent[]

The logging events to send.

SendEmail(string)

Send the email message

protected virtual void SendEmail(string messageBody)

Parameters

messageBody string

the body text to include in the mail