RazorSoftware Logging Library

Simple and Lightweight Library for Logging Messages to different outputs like Files, Consoles, and Debuggers.

Quick links

API Reference | Downloads

Features

• Fast and Lightweight
• Automatic Console Window creation and management on GUI applications.
• Support for Windows Forms, WPF, CLI, and custom GUI Applications.
• Handles multiple File Outputs simultaneously.
• Per-Output message filtering via Log Levels.
• Attached debugger logging.
• Embedded Thread Synchronization compatible with multi App-Domain hosts.
• On the fly output management.
• Categorizable message output
• Fully documented.

Getting Started

Its recommended to use this library via the Nuget Packages available on the Downloads section of this repository or by using the Nuget Package manager of your preferred IDE.

Using NuGet

There are two packages available for download. Which to use depends mainly on your likes since both provides the same classes, but differs in the way the class files are included with your assemblies.

The Binary Package contains the precompiled library in the form of a single Dynamic Link Library (*.dll*) file. Adding this package results in adding the library as an assembly reference that is copied to the output directory of the application upon build, which is always required for the application to make use of it.

Binary packages are prefixed on the downloads section with the DLL_ or [DLL] tag.

The Source Package includes the plain code of the library and is added as new class files to your .NET project. These classes are compiled and included inside the resulting assembly upon build. By using this option, the code of the library can be freely modified to best suit your needs (like adding new method overloads, new functionalities, or speed tweaks.) directly from your own project.

Source packages are prefixed with the SRC_ or [SRC] tag on the downloads section. On the NuGet Package repository, Source packages have the **.Source** terminationon its Package name.

*(Download links here may be outdated, always refer to downloads section for the latest version)*

How to Compile

Download the latest source from the repository with:

git clone https://bitbucket.org/kderazorback/razorsoftware.logging.git

And open the solution file RazorSoftware.Logging.sln. Select the release type and architecture and build the solution.

For generating the precompiled binary library, select the Release configuration and build the solution.

For generating local NuGet packages, select the Release configuration and pack the solution. The Source package can be generated by selecting the Source Release configuration.

Debug vs Release

The library default output settings differ based on the release type set while building the library (for Dll packages) and while building your hosting application (for Source packages).

For Dll packages, the Release Type is defined when building the Library itself and is kept for its entire lifetime. Using Debug builds of the library is genrally not needed

For Source packages, the Release Type is defined when building your application, since the source code is included on the project itself. Select Debug to product a more detailed output of your application by default

For Debug Builds the default outputs are

• A ConsoleOutput for messages with a LogLevel of Debug or greater
• A DebuggerOutput for messages with a LogLevel of Warning or greater
• A FileOutput for messages with a LogLevel of Debug or greater
• A second FileOutput for messages with a LogLevel of Message or greater

For Release Builds the default outputs are

• A FileOutput for messages with a LogLevel of Message or greater
• A DebuggerOutput for messages with a LogLevel of Error or greater

A value of false can be used for the openDefaultOutputs parameter of the Initialize() method, to skip automatic output initialization, useful when you want to create and initialize the outputs manually.

Note: For Console Applications (CLI) the current Console Window is always used as an Output when initializing the library with default values in any Release configuration, unless its Enabled property is set to false.

API Reference

The library is completely documented online at its API Reference on RazorSoftware, where you can find a copy of this file. Class reference can be found at the Online Class Reference. All classes, and its members includes descriptions, exceptions information, parameter hints and usage tips.

Standalone help files are available in the single *.chm* and PDF formats on the downloads section for offline viewing. Visit the downloads section of the repository for the latest version of each file.

Note: On windows, after opening the compiled CHM help file, it can appear empty or show blank pages for all entries on the index. To fix this, you must right click the CHM file in explorer, and select Properties, then, click the Unblock button near the bottom of the properties page.

Quick Start

Initialization and Finalization code for the library is recommended to be included on the Main() method (Entry point) of the Application.

This single line of code is required for the library to perform its initialization with default outputs.

Log.Initialize();

After that, the logging library is fully initialized and messages can be written using any of the Write() and WriteLine() overloads for the Log static class. Example:

Log.Write("Hello ");
Log.Write("World");
Log.WriteLine("This is a Warning", LogLevel.Warning);
Log.WriteLine("Max value for a byte variable is: %@", LogLevel.Message, byte.MaxValue);
Log.WriteColoredLine("This is a line of text printed in red", ConsoleColor.Red);

The example outputs:

Hello World
This is Warning
Max Value for a byte variable is: 255
This is a line of text printed in red

Log level can be modified using the MinimumLevel property on the desired output.

Log.Console.MinimumLevel = LogLevel.Error;

When the application is about to quit, the library needs to be shutdown in order to append statistical data, flush and close File outputs. This is done with a single call too.

Log.Shutdown();

Logger Class

When using the library on large applications with multiple modules, its recommended to use the Logger class to categorize messages and avoid output congestion.

This class provides an isolated and controlled filter for messages logged by individual parts of your application, where each of them can be toggled On or Off individually, with additional support for message wrapping and embedded thread synchronization

A new instance is created using the constructor:

Logger myLogger = new Logger("My Module");

And messages can be sent to it by calling any of the Write() and WriteLine() overloads available.

myLogger.WriteLine("Hello World");

The last line writes to outputs:

[My Module] Hello World

Logger Entry Wrapping

The logger class provides another useful feature for large projects that usually logs equivalent entries in sequence. It collapses a block of equal consecutive entries into a summary block. Example:

myLogger.WriteLine("Hello World");
myLogger.WriteLine("Hello World");
myLogger.WriteLine("Hello World");
myLogger.WriteLine("Hello World");
myLogger.WriteLine("Wrapped Calls");

Outputs:

[My Module] Hello World
[My Module] The last entry repeats 3 times.
[My Module] Wrapped Calls

Summaries are only written when a new entry is sent to the logger class that is different from the last one, or when the logger class itself is being closed.

As always, more information can be found on the Online Doc or the offline Help files

Forcibly enable Console Output

When working with applications that normally dont display a Console interface, you can force its creation and attach it to the standard System.Console by using the helper methods provided by the com.RazorSoftware.Logging.Log.Console class.

When doing this, the Standard Output (STDOUT) and Standard Error (STDERR) streams will be redirected to the newly created Console window.

Log.Console.CreateConsole("My Console title");

So a complete syntax for Initializing the Library inside the Main() method of a GUI application with a forced Console Window will be as follows:

using com.RazorSoftware.Logging;
 
static void Main()
{
    // Pre-Initialization code
    ...
 
    // Initialize Library with default outputs
    Log.Initialize();
 
    // Force the creation of a new Console Window
    Log.Console.CreateConsole("My Debug Window");
    // Set the Console MinimumLogLevel
    Log.Console.MinimumLevel = LogLevel.Debug;
    // Enable the Console as an output
    Log.Console.Enabled = true;
 
    // Continue with your application logic
    // At this point the library is fully initialized and ready for logging with an active Console Window.
    ...
}

NOTE: Console creation methods are not available in .NET Core builds. A Console is always expected to be attached to the Application. This behavior can be disabled by setting Log.Console.Enabled = false.

License

This software is protected under the GNU Lesser General Public License.

Copyright © 2020 RazorSoftware
Fabian R. contact@razorsoftware.dev
This file is part of RazorSoftware Logging Library.

RazorSoftware Logging Library is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

RazorSoftware Logging Library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with RazorSoftware Logging Library.  If not, see <http://www.gnu.org/licenses/>.

http://www.gnu.org/licenses/