Class AppenderSkeleton

Namespace

log4net.Appender

Assembly

log4net.dll

Abstract base class implementation of IAppender.

public abstract class AppenderSkeleton : IBulkAppender, IAppender, IOptionHandler, IFlushable

Inheritance

object

AppenderSkeleton

Implements

IBulkAppender

IAppender

IOptionHandler

IFlushable

Derived

AnsiColorTerminalAppender

AspNetTraceAppender

BufferingAppenderSkeleton

ColoredConsoleAppender

ConsoleAppender

DebugAppender

EventLogAppender

ForwardingAppender

LocalSyslogAppender

ManagedColoredConsoleAppender

MemoryAppender

OutputDebugStringAppender

TelnetAppender

TextWriterAppender

TraceAppender

UdpAppender

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Remarks

This class provides the code for common functionality, such as support for threshold filtering and support for general filters.

Appenders can also implement the IOptionHandler interface. Therefore they would require that the ActivateOptions() method be called after the appenders properties have been configured.

Constructors

AppenderSkeleton()

Default constructor

protected AppenderSkeleton()

Remarks

Empty default constructor

Properties

ErrorHandler

Gets or sets the IErrorHandler for this appender.

public virtual IErrorHandler ErrorHandler { get; set; }

Property Value

IErrorHandler

The IErrorHandler of the appender

Remarks

The AppenderSkeleton provides a default implementation for the ErrorHandler property.

FilterHead

The filter chain.

public virtual IFilter? FilterHead { get; }

Property Value

IFilter

The head of the filter chain.

Remarks

Returns the head Filter. The Filters are organized in a linked list and so all Filters on this Appender are available through the result.

Layout

Gets or sets the ILayout for this appender.

public virtual ILayout? Layout { get; set; }

Property Value

ILayout

The layout of the appender.

Remarks

See RequiresLayout for more information.

See Also

RequiresLayout

LockObj

Used for locking actions by this appender.

protected object LockObj { get; }

Property Value

object

Name

Gets or sets the name that uniquely identifies this appender.

public string Name { get; set; }

Property Value

string

RequiresLayout

Tests if this appender requires a Layout to be set.

protected virtual bool RequiresLayout { get; }

Property Value

bool

true if the appender requires a layout object, otherwise false.

Remarks

In the rather exceptional case, where the appender implementation admits a layout but can also work without it, then the appender should return true.

This default implementation always returns false.

Threshold

Gets or sets the threshold Level of this appender. Defaults to All.

public Level Threshold { get; set; }

Property Value

Level

The threshold Level of the appender.

Remarks

All log events with lower level than the threshold level are ignored by the appender.

In configuration files this option is specified by setting the value of the Threshold option to a level string, such as "DEBUG", "INFO" and so on.

Methods

ActivateOptions()

Initialize the appender based on the options set

public virtual 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.

AddFilter(IFilter)

Adds a filter to the end of the filter chain.

public virtual void AddFilter(IFilter filter)

Parameters

filter IFilter

the filter to add to this appender

Remarks

The Filters are organized in a linked list.

Setting this property causes the new filter to be pushed onto the back of the filter chain.

Append(IEnumerable<LoggingEvent>)

Appends logging events.

protected virtual void Append(IEnumerable<LoggingEvent> loggingEvents)

Parameters

loggingEvents IEnumerable<LoggingEvent>

The logging events

Remarks

This base class implementation calls the Append(LoggingEvent) method for each element in the bulk array.

A subclass that can better process a bulk array of events should override this method in addition to Append(LoggingEvent).

Append(LoggingEvent)

Subclasses of AppenderSkeleton should implement this method to perform actual logging.

protected abstract void Append(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

The event to append.

Remarks

A subclass must implement this method to perform logging of the loggingEvent.

This method will be called by DoAppend(LoggingEvent) if all the conditions listed for that method are met.

To restrict the logging of events in the appender override the PreAppendCheck() method.

Append(LoggingEvent[])

Append a bulk array of logging events.

protected virtual void Append(LoggingEvent[] loggingEvents)

Parameters

loggingEvents LoggingEvent[]

the array of logging events

Remarks

This base class implementation calls the Append(LoggingEvent) method for each element in the bulk array.

A subclass that can better process a bulk array of events should override this method in addition to Append(LoggingEvent).

ClearFilters()

Clears the filter list for this appender.

public virtual void ClearFilters()

Remarks

Clears the filter list for this appender.

Close()

Closes the appender and releases resources.

public void Close()

Remarks

Release any resources allocated within the appender such as file handles, network connections, etc.

It is a programming error to append to a closed appender.

This method cannot be overridden by subclasses. This method delegates the closing of the appender to the OnClose() method which must be overridden in the subclass.

DoAppend(LoggingEvent)

Performs threshold checks and invokes filters before delegating actual logging to the subclasses specific Append(LoggingEvent) method.

public void DoAppend(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

The event to log.

Remarks

This method cannot be overridden by derived classes. A derived class should override the Append(LoggingEvent) method which is called by this method.

The implementation of this method is as follows:

• Checks that the severity of the loggingEvent is greater than or equal to the Threshold of this appender.
• Checks that the IFilter chain accepts the loggingEvent.
• Calls PreAppendCheck() and checks that it returns true.

If all of the above steps succeed then the loggingEvent will be passed to the abstract Append(LoggingEvent) method.

DoAppend(LoggingEvent[])

Performs threshold checks and invokes filters before delegating actual logging to the subclasses specific Append(LoggingEvent[]) method.

public void DoAppend(LoggingEvent[] loggingEvents)

Parameters

loggingEvents LoggingEvent[]

The array of events to log.

Remarks

This method cannot be overridden by derived classes. A derived class should override the Append(LoggingEvent[]) method which is called by this method.

The implementation of this method is as follows:

• Checks that the severity of the loggingEvents is greater than or equal to the Threshold of this appender.
• Checks that the IFilter chain accepts the loggingEvents.
• Calls PreAppendCheck() and checks that it returns true.

If all of the above steps succeed then the loggingEvents will be passed to the Append(LoggingEvent[]) method.

FilterEvent(LoggingEvent)

Test if the logging event should we output by this appender

protected virtual bool FilterEvent(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

the event to test

Returns

bool

true if the event should be output, false if the event should be ignored

Remarks

This method checks the logging event against the threshold level set on this appender and also against the filters specified on this appender.

The implementation of this method is as follows:

• Checks that the severity of the loggingEvent is greater than or equal to the Threshold of this appender.
• Checks that the IFilter chain accepts the loggingEvent.

~AppenderSkeleton()

Finalizes this appender by calling the implementation's Close() method.

protected ~AppenderSkeleton()

Remarks

If this appender has not been closed then the ~AppenderSkeleton() method will call Close().

Flush(int)

Flushes any buffered log data.

public virtual bool Flush(int millisecondsTimeout)

Parameters

millisecondsTimeout int

Returns

bool

true if all logging events were flushed successfully, else false.

Remarks

This implementation doesn't flush anything and always returns true

IsAsSevereAsThreshold(Level?)

Checks if the message level is below this appender's threshold.

protected virtual bool IsAsSevereAsThreshold(Level? level)

Parameters

level Level

Level to test against.

Returns

bool

true if the level meets the Threshold requirements of this appender. A null level always maps to true, the equivalent of All.

OnClose()

Is called when the appender is closed. Derived classes should override this method if resources need to be released.

protected virtual void OnClose()

Remarks

Releases any resources allocated within the appender such as file handles, network connections, etc.

It is a programming error to append to a closed appender.

PreAppendCheck()

Called before Append(LoggingEvent) as a precondition.

protected virtual bool PreAppendCheck()

Returns

bool

true if the call to Append(LoggingEvent) should proceed.

Remarks

This method is called by DoAppend(LoggingEvent) before the call to the abstract Append(LoggingEvent) method.

This method can be overridden in a subclass to extend the checks made before the event is passed to the Append(LoggingEvent) method.

A subclass should ensure that they delegate this call to this base class if it is overridden.

RenderLoggingEvent(TextWriter, LoggingEvent)

Renders the LoggingEvent to a string.

protected void RenderLoggingEvent(TextWriter writer, LoggingEvent loggingEvent)

Parameters

writer TextWriter

The TextWriter to write the formatted event to

loggingEvent LoggingEvent

The event to render.

Remarks

Helper method to render a LoggingEvent to a string. This appender must have a Layout set to render the loggingEvent to a string.

If there is exception data in the logging event and the layout does not process the exception, this method will append the exception text to the rendered string.

Use this method in preference to RenderLoggingEvent(LoggingEvent) where possible. If, however, the caller needs to render the event to a string then RenderLoggingEvent(LoggingEvent) does provide an efficient mechanism for doing so.

RenderLoggingEvent(LoggingEvent)

Renders the LoggingEvent to a string.

protected string RenderLoggingEvent(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

The event to render.

Returns

string

The event rendered as a string.

Remarks

Helper method to render a LoggingEvent to a string. This appender must have a Layout set to render the loggingEvent to a string.

If there is exception data in the logging event and the layout does not process the exception, this method will append the exception text to the rendered string.

Where possible use the alternative version of this method RenderLoggingEvent(TextWriter, LoggingEvent). That method streams the rendering onto an existing Writer which can give better performance if the caller already has a TextWriter open and ready for writing.