Table of Contents

Class LogFileWriter

Namespace
Switchboard
Assembly
Switchboard.Logger.dll

Writes log entries to log files.

public sealed class LogFileWriter : ILogger, IDisposable
Inheritance
LogFileWriter
Implements
Extension Methods

Constructors

LogFileWriter(string, string)

Initializes a new instance of the class.

public LogFileWriter(string directory, string fileNamePrefix)

Parameters

directory string

The path to the directory where log files will be written.

fileNamePrefix string

The first part of the file name. A time stamp will be added to each file name, after the prefix, before the extension.

Exceptions

ArgumentNullException

Thrown if directory or fileNamePrefix are null.

ArgumentException

Thrown if directory or fileNamePrefix are Empty. \ OR \ Thrown if directory contains invalid path characters. \ OR \ Thrown if fileNamePrefix contains invalid file name characters for the current platform.

LogFileWriter(string, string, string)

Initializes a new instance of the class.

public LogFileWriter(string directory, string fileNamePrefix, string fileExtension)

Parameters

directory string

The path to the directory where log files will be written.

fileNamePrefix string

The first part of the file name. A time stamp will be added to each file name, after the prefix, before the fileExtension.

fileExtension string

The file name extension to use.

Exceptions

ArgumentNullException

Thrown if directory, fileNamePrefix, or fileExtension are null.

ArgumentException

Thrown if directory, fileNamePrefix, or fileExtension are Empty. \ OR \ Thrown if directory contains invalid path characters. \ OR \ Thrown if fileNamePrefix or fileExtension contain invalid file name characters for the current platform.

LogFileWriter(string, string, string, int)

Initializes a new instance of the class.

public LogFileWriter(string directory, string fileNamePrefix, string fileExtension, int fileSizeLimit)

Parameters

directory string

The path to the directory where log files will be written.

fileNamePrefix string

The first part of the file name. A time stamp will be added to each file name, after the prefix, before the fileExtension.

fileExtension string

The file name extension to use.

fileSizeLimit int

The maximum file size in bytes for log files. When a log file reaches the size limit, a new file will be created.

Exceptions

ArgumentNullException

Thrown if directory, fileNamePrefix, or fileExtension are null.

ArgumentException

Thrown if directory, fileNamePrefix, or fileExtension are Empty. \ OR \ Thrown if directory contains invalid path characters. \ OR \ Thrown if fileNamePrefix or fileExtension contain invalid file name characters for the current platform.

ArgumentOutOfRangeException

Thrown if the fileSizeLimit is less than MinFileSize.

LogFileWriter(string, string, string, int, ILogFormatter)

Initializes a new instance of the class.

public LogFileWriter(string directory, string fileNamePrefix, string fileExtension, int fileSizeLimit, ILogFormatter formatter)

Parameters

directory string

The path to the directory where log files will be written.

fileNamePrefix string

The first part of the file name. A time stamp will be added to each file name, after the prefix, before the fileExtension.

fileExtension string

The file name extension to use.

fileSizeLimit int

The maximum file size in bytes for log files. When a log file reaches the size limit, a new file will be created.

formatter ILogFormatter

The formatter to use for formatting log entries.

Exceptions

ArgumentNullException

Thrown if directory, fileNamePrefix, or fileExtension are null.

ArgumentException

Thrown if directory, fileNamePrefix, or fileExtension are Empty. \ OR \ Thrown if directory contains invalid path characters. \ OR \ Thrown if fileNamePrefix or fileExtension contain invalid file name characters for the current platform.

ArgumentOutOfRangeException

Thrown if the fileSizeLimit is less than MinFileSize.

Fields

DefaultFileExtension

Gets the default file name extension for log files.

public const string DefaultFileExtension = ".log"

DefaultFileSizeLimit

Gets the default file size limit in bytes.

public const int DefaultFileSizeLimit = 10000000

MinFileSize

Gets the minimum number of bytes required for each log file.

public const int MinFileSize = 3072

Properties

Directory

Gets the path to the directory for the current log file.

public string Directory { get; }

FileExtension

Gets the file extension for the current log file.

public string FileExtension { get; }

FileIsOpen

Indicates whether there is a log file with an open FileStream.

public bool FileIsOpen { get; }

FileNamePrefix

Gets file name prefix for the current log file, the part before the time stamp.

public string FileNamePrefix { get; }

FileSizeLimit

Gets or sets the maximum size of log files in bytes. When a log file reaches the size limit, a new file will be created.

public int FileSizeLimit { get; set; }

Exceptions

ArgumentOutOfRangeException

Thrown if the set value is less than MinFileSize.

Formatter

Gets or sets the formatter to use for formatting log entries.

public ILogFormatter Formatter { get; set; }

LogCallerInfo

Gets or sets whether information about the caller of the log method should be displayed.

public bool LogCallerInfo { get; set; }

LogLevel

Gets or sets the minimum level of significance required for a log entry to be processed.

public LogLevel LogLevel { get; set; }

Path

Gets the file path for the current log file.

public string Path { get; }

StringMakerPoolCount

Gets the number of StringMakers stored in the shared pool. May not be perfectly accurate while other threads are modifying the pool.

public static int StringMakerPoolCount { get; }

StringMakerPoolMaxCount

Gets the maximum number of StringMakers that can be stored in the shared pool.

public static int StringMakerPoolMaxCount { get; }

Methods

Close()

Closes the FileStream for the current log file. Closing the FileStream does not automatically FlushLogs().

public void Close()

Exceptions

InvalidOperationException

Thrown if another file operation is in progress, such as OpenNewFile(), Open(), or FlushLogs().

FlushLogs()

Flushes queued log entries so that they are written to the log file. If necessary, a new log file will be created, and the FileStream will be opened. It should be called regularly to prevent too many logs from accumulating in the queue.

public void FlushLogs()

Exceptions

InvalidOperationException

Thrown if another file operation is in progress, such as OpenNewFile(), Open(), or Close().

SecurityException

A new file needs to be created, and the caller does not have the required permission.

DirectoryNotFoundException

A new file needs to be created, and the specified path is invalid.

UnauthorizedAccessException

A new file needs to be created, and write access is not permitted by the operating system for the specified path, such as when the file or directory is set for read-only access.

PathTooLongException

A new file needs to be created, and the specified path exceeds the system-defined maximum length.

Log(LogLevel, Exception, ReadOnlySpan<char>)

Queues an exception to be written to the log file. If the Formatter throws an exception when formatting the exception, the formatting exception, the message, and original exception will be queued without formatting. No exception will be thrown.

public void Log(LogLevel logLevel, Exception exception, ReadOnlySpan<char> message)

Parameters

logLevel LogLevel

The level of significance assigned to the exception.

exception Exception

The exception to log.

message ReadOnlySpan<char>

A log message to be included with the exception.

Exceptions

ArgumentNullException

Thrown if the exception is null.

Log(LogLevel, ReadOnlySpan<char>, string, string, int)

Queues a message to be written to the log file. If the Formatter throws an exception when formatting the message, the message will be queued without formatting. Then, the formatting exception will be re-thrown.

public void Log(LogLevel logLevel, ReadOnlySpan<char> message, string memberName = null, string filePath = null, int lineNumber = 0)

Parameters

logLevel LogLevel

The level of significance assigned to the message.

message ReadOnlySpan<char>

The log message.

memberName string

The name of the member that called the method. Do not provide an argument. The compiler will automatically assign the correct value.

filePath string

The name of the file that contains the member that called the method. Do not provide an argument. The compiler will automatically assign the correct value.

lineNumber int

The line number within the file that contains the member that called the method. Do not provide an argument. The compiler will automatically assign the correct value.

Open()

Opens a FileStream for the current log file. If there is no current log file a new one will be created.

public void Open()

Exceptions

InvalidOperationException

Thrown if another file operation is in progress, such as OpenNewFile(), Close(), or FlushLogs().

FileNotFoundException

The file cannot be found.

SecurityException

The caller does not have the required permission.

DirectoryNotFoundException

The specified path is invalid.

UnauthorizedAccessException

Write access is not permitted by the operating system for the specified path, such as when the file or directory is set for read-only access.

PathTooLongException

The specified path exceeds the system-defined maximum length.

OpenNewFile()

Opens a FileStream for a new log file. The file name will start with the file name prefix, followed by a time stamp and the file name extension.

public void OpenNewFile()

Exceptions

InvalidOperationException

Thrown if another file operation is in progress, such as Open(), Close(), or FlushLogs().

SecurityException

The caller does not have the required permission.

DirectoryNotFoundException

The specified path is invalid.

UnauthorizedAccessException

Write access is not permitted by the operating system for the specified path, such as when the file or directory is set for read-only access.

PathTooLongException

The specified path exceeds the system-defined maximum length.

AggregateException

Thrown if multiple exceptions occur during the course of the method.

SetFileSizeLimit(int)

Sets the maximum log file size in bytes. When a log file reaches the size limit, a new file will be created.

public void SetFileSizeLimit(int fileSizeLimit)

Parameters

fileSizeLimit int

The maximum file size in bytes.

Exceptions

ArgumentOutOfRangeException

Thrown if the fileSizeLimit is less than MinFileSize.

SetStringMakerPoolMaxCount(int)

Sets the maximum number of StringMakers that can be stored in the shared pool.

public static void SetStringMakerPoolMaxCount(int maxCount)

Parameters

maxCount int

The maximum number of StringMakers that can be stored.

Exceptions

ArgumentOutOfRangeException

Thrown if maxCount is less than zero.

Events

FileClosed

Occurs when the FileStream for the current log file is closed. Provides an opportunity to clean up old log files.

public event Action<LogFileWriter> FileClosed