Class FileAppender

Namespace

log4net.Appender

Assembly

log4net.dll

Appends logging events to a file.

public class FileAppender : TextWriterAppender, IBulkAppender, IAppender, IOptionHandler

Inheritance

object

AppenderSkeleton

TextWriterAppender

FileAppender

Implements

IBulkAppender

IAppender

IOptionHandler

Derived

RollingFileAppender

Inherited Members

TextWriterAppender.PreAppendCheck()

TextWriterAppender.OnClose()

TextWriterAppender.WriteFooterAndCloseWriter()

TextWriterAppender.ImmediateFlush

TextWriterAppender.Writer

TextWriterAppender.ErrorHandler

TextWriterAppender.RequiresLayout

TextWriterAppender.QuietWriter

AppenderSkeleton.Close()

AppenderSkeleton.DoAppend(LoggingEvent)

AppenderSkeleton.DoAppend(LoggingEvent[])

AppenderSkeleton.FilterEvent(LoggingEvent)

AppenderSkeleton.AddFilter(IFilter)

AppenderSkeleton.ClearFilters()

AppenderSkeleton.IsAsSevereAsThreshold(Level)

AppenderSkeleton.RenderLoggingEvent(LoggingEvent)

AppenderSkeleton.RenderLoggingEvent(TextWriter, LoggingEvent)

AppenderSkeleton.Threshold

AppenderSkeleton.FilterHead

AppenderSkeleton.Layout

AppenderSkeleton.Name

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Logging events are sent to the file specified by the File property.

The file can be opened in either append or overwrite mode by specifying the AppendToFile property. If the file path is relative it is taken as relative from the application base directory. The file encoding can be specified by setting the Encoding property.

The layout's Header and Footer values will be written each time the file is opened and closed respectively. If the AppendToFile property is true then the file may contain multiple copies of the header and footer.

This appender will first try to open the file for writing when ActivateOptions() is called. This will typically be during configuration. If the file cannot be opened for writing the appender will attempt to open the file again each time a message is logged to the appender. If the file cannot be opened for writing when a message is logged then the message will be discarded by this appender.

The FileAppender supports pluggable file locking models via the LockingModel property. The default behavior, implemented by FileAppender.ExclusiveLock is to obtain an exclusive write lock on the file until this appender is closed. The alternative models only hold a write lock while the appender is writing a logging event (FileAppender.MinimalLock) or synchronize by using a named system wide Mutex (FileAppender.InterProcessLock).

All locking strategies have issues and you should seriously consider using a different strategy that avoids having multiple processes logging to the same file.

Constructors

FileAppender()

Default constructor

public FileAppender()

Remarks

Default constructor

FileAppender(ILayout, string)

Construct a new appender using the layout and file specified. The file will be appended to.

[Obsolete("Instead use the default constructor and set the Layout & File properties")]
public FileAppender(ILayout layout, string filename)

Parameters

layout ILayout

the layout to use with this appender

filename string

the full path to the file to write to

Remarks

Obsolete constructor.

FileAppender(ILayout, string, bool)

Construct a new appender using the layout, file and append mode.

[Obsolete("Instead use the default constructor and set the Layout, File & AppendToFile properties")]
public FileAppender(ILayout layout, string filename, bool append)

Parameters

layout ILayout

the layout to use with this appender

filename string

the full path to the file to write to

append bool

flag to indicate if the file should be appended to

Remarks

Obsolete constructor.

Properties

AppendToFile

Gets or sets a flag that indicates whether the file should be appended to or overwritten.

public bool AppendToFile { get; set; }

Property Value

bool

Indicates whether the file should be appended to or overwritten.

Remarks

If the value is set to false then the file will be overwritten, if it is set to true then the file will be appended to.

The default value is true.

Encoding

Gets or sets Encoding used to write to the file.

public Encoding Encoding { get; set; }

Property Value

Encoding

The Encoding used to write to the file.

Remarks

The default encoding set is Default which is the encoding for the system's current ANSI code page.

File

Gets or sets the path to the file that logging will be written to.

public virtual string File { get; set; }

Property Value

string

The path to the file that logging will be written to.

Remarks

If the path is relative it is taken as relative from the application base directory.

LockingModel

Gets or sets the LockingModel used to handle locking of the file.

public FileAppender.LockingModelBase LockingModel { get; set; }

Property Value

FileAppender.LockingModelBase

The LockingModel used to lock the file.

Remarks

Gets or sets the LockingModel used to handle locking of the file.

There are three built in locking models, FileAppender.ExclusiveLock, FileAppender.MinimalLock and FileAppender.InterProcessLock . The first locks the file from the start of logging to the end, the second locks only for the minimal amount of time when logging each message and the last synchronizes processes using a named system wide Mutex.

The default locking model is the FileAppender.ExclusiveLock.

SecurityContext

Gets or sets the SecurityContext used to write to the file.

public SecurityContext SecurityContext { get; set; }

Property Value

SecurityContext

The SecurityContext used to write to the file.

Remarks

Unless a SecurityContext specified here for this appender the DefaultProvider is queried for the security context to use. The default behavior is to use the security context of the current thread.

Methods

ActivateOptions()

Activate the options on the file appender.

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.

This will cause the file to be opened.

Append(LoggingEvent)

This method is called by the AppenderSkeleton.DoAppend(LoggingEvent) method.

protected override void Append(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

The event to log.

Remarks

Writes a log statement to the output stream if the output stream exists and is writable.

The format of the output will depend on the appender's layout.

Append(LoggingEvent[])

This method is called by the AppenderSkeleton.DoAppend(LoggingEvent[]) method.

protected override void Append(LoggingEvent[] loggingEvents)

Parameters

loggingEvents LoggingEvent[]

The array of events to log.

Remarks

Acquires the output file locks once before writing all the events to the stream.

CloseFile()

Closes the previously opened file.

protected void CloseFile()

Remarks

Writes the Footer to the file and then closes the file.

CloseWriter()

Closes the underlying TextWriter.

protected override void CloseWriter()

Remarks

Closes the underlying TextWriter.

ConvertToFullPath(string)

Convert a path into a fully qualified path.

protected static string ConvertToFullPath(string path)

Parameters

path string

The path to convert.

Returns

string

The fully qualified path.

Remarks

Converts the path specified to a fully qualified path. If the path is relative it is taken as relative from the application base directory.

OpenFile(string, bool)

Sets and opens the file where the log output will go. The specified file must be writable.

protected virtual void OpenFile(string fileName, bool append)

Parameters

fileName string

The path to the log file. Must be a fully qualified path.

append bool

If true will append to fileName. Otherwise will truncate fileName

Remarks

If there was already an opened file, then the previous file is closed first.

This method will ensure that the directory structure for the fileName specified exists.

PrepareWriter()

Called to initialize the file writer

protected override void PrepareWriter()

Remarks

Will be called for each logged message until the file is successfully opened.

Reset()

Closes any previously opened file and calls the parent's Reset().

protected override void Reset()

Remarks

Resets the filename and the file stream.

SafeOpenFile(string, bool)

Sets and opens the file where the log output will go. The specified file must be writable.

protected virtual void SafeOpenFile(string fileName, bool append)

Parameters

fileName string

The path to the log file. Must be a fully qualified path.

append bool

If true will append to fileName. Otherwise will truncate fileName

Remarks

Calls OpenFile(string, bool) but guarantees not to throw an exception. Errors are passed to the ErrorHandler.

SetQWForFiles(Stream)

Sets the quiet writer used for file output

protected virtual void SetQWForFiles(Stream fileStream)

Parameters

fileStream Stream

the file stream that has been opened for writing

Remarks

This implementation of SetQWForFiles(Stream) creates a StreamWriter over the fileStream and passes it to the SetQWForFiles(TextWriter) method.

This method can be overridden by sub classes that want to wrap the Stream in some way, for example to encrypt the output data using a System.Security.Cryptography.CryptoStream.

SetQWForFiles(TextWriter)

Sets the quiet writer being used.

protected virtual void SetQWForFiles(TextWriter writer)

Parameters

writer TextWriter

the writer over the file stream that has been opened for writing

Remarks

This method can be overridden by sub classes that want to wrap the TextWriter in some way.

WriteFooter()

Writes a footer as produced by the embedded layout's Footer property.

protected override void WriteFooter()

Remarks

Writes a footer as produced by the embedded layout's Footer property.

WriteHeader()

Writes a header produced by the embedded layout's Header property.

protected override void WriteHeader()

Remarks

Writes a header produced by the embedded layout's Header property.