==== NebolLogger ====

NebolLogger is a C# package for quick and simple logging to database, file, or other destinations.

See the nuget page at https://nuget.nebol.se for version history etc.

=== Quick example to give you an idea of how it works ===

<code csharp>
// First create the destination for the log output: 
var dailyfile = new Destination_File(@"C:\TEMP","NebolLoggerDemo", "log", Rotation.Daily); 

// adding the destination to the logger 
Logger.Instance.Destinations.Add(dailyfile); 

// while we're at it, let's output to the console as well, but only if it's an error or worse 
var console = new Destination_Console(); 
console.Filters.Add(new Filter_Level(LogType.error)); 
Logger.Instance.Destinations.Add(console); 

// now we can use the logger in our program, this line will appear only in the file 
Logger.Instance.Trace("Testing the new logger, it's working nicely!"); 

// this line will appear in both the file and in the console 
Logger.Instance.Error("Oops, something went wrong!");
</code>

=== What information is contained in a log entry? ===

  * Type - the LogType aka "Level" of the entry, an indication of its importance
  * Date  - the exact DateTime when the entry was created
  * Context - the context of the message, usually the name of the method where it was created
  * Line - the line number in the sourcecode where it was created
  * Machine - a Machine object containing Name of the machine and an IP address
  * Application - an Application object containing the name of the application
  * Component - a Component object containing the entire path of the sourcecode file

=== Levels ===

Each message that is logged has one of these the levels of importance:

  * Trace - least important - use this if you just want to follow the flow of your program
  * Debug
  * Information
  * Notice
  * Warning
  * Error
  * Critical
  * Fatal - most important - the most severe kind of error

=== Destinations ===

== Destination_Console - outputs to console (stdout) ==

<code csharp>
var dest =  new Destination_Console();
</code>

==Destination_ColorConsole - outputs to console (stdout) but with color (depending on level) ==

<code csharp>
var dest =  new Destination_ColorConsole();
</code>

== Destination_File - outputs to file ==

<code csharp>
var dest = new Destination_File(string folder,string suffix = "log", Rotation file_rolation = Rotation.None, Rotation folder_rotation = Rotation.None);
</code>

Rotation can be : None, Hourly, Daily, Monthly, Yearly

== Destination_Memory - outputs to memory ie the data is lost at application exit ==

<code csharp>
var dest = new Destination_Memory();
</code>

== Destination_Forwarder - forwards the output to one or more destinations ==

<code csharp>
var dest = new Destination_Forwarder(dest1, dest2, dest3...);
</code>

== Destination_Buffer - outputs to a memory buffer that flushes its contents to an other destination after a limit has been reached ==

<code csharp>
var dest = new Destination_Buffer(Destination dest, buffer_count = 100);
</code>

== Create a custom destination ==

To create a custom destination, create a class that inherits from Destination, then override the Write(Entry entry) method. That's the method that is called to perform the actual writing of the entry to the destination.

You may also override the Write(List<Entry> entries) if you want to provide special logic to handle writing a list of entries all at once. Otherwise the Write(Entry entry) method is called once for every item in the list.

=== Customization ===

The output format can be customized using Filters and using the FormattingDelegate delegate. You could also write your own class by inheriting from Destination.

Example on customizing output format using the delegate:

<code csharp>
dest.FormattingDelegate = new NebolLoggerFormattingDelegate(item =>
	item.Date.ToString("yyyy-MM-dd HH:mm:ss ")
	+ Entry.GetLogLevelAsText(item.Type)
	+ " "
	+ item.Context
	+ ": "
	+ item.Message
);
</code>

For console output this might be desired formatting:

<code csharp>
dest.FormattingDelegate = new NebolLoggerFormattingDelegate(item =>
	item.Date.ToString("HH:mm:ss")
	+ " : "
	+ item.Message
);
</code>


The method Entry.GetLogLevelAsText(item.Type) will return the 5 char length level text ie "TRACE" or "INFO "
The method Entry.GetLogLevelAsTrimmedText(item.Type) will remove any whitespace ie "TRACE" or "INFO"

=== Filters ===

== Filter_Level - limit output by level ==

<code csharp>
// this will create a new Filter_Level that limits output to messages of level Error (or higher/worse!)
var filter = new Filter_Level(LogType.error);

// now attach the filter to a destination
dest.Filters.Add(filter);
</code>

== Filter_Context - limit output by context ==

<code csharp>
// create a context filter that accepts only context that contains "Main"
var filter = new Filter_Context("Main");
</code>


== Filter_Message - limit output by message ==

<code csharp>
// create a message filter that accepts only messages containing the string "localhost"
var filter = new Filter_Message("localhost");
</code>


== Create a custom filter ==

You can also create your own filter by inheriting from Filter and overriding the Match() method. As an example, here is the complete code for Filter_Context:

<code csharp>
public class Filter_Context : Filter
{
	public string Context { get; set; }

	public Filter_Context(string context)
	{
		Context = context;
	}

	public override bool Match(Entry entry)
	{
		return (entry.Context.Contains(Context));
	}
}
</code>

=== Logging unhandled exceptions ===

To log unhandled exceptions in .NET Framework, add this class:

<code csharp>
public class NebolUnhandledExceptionLogger : ExceptionLogger
{
	public override void Log(ExceptionLoggerContext context)
	{
		Logger.Instance.Error(context.Exception.ToString());
	}
}
</code>

and this line in WebApiConfig.Register():

<code csharp>
config.Services.Replace(typeof(IExceptionLogger), new NebolUnhandledExceptionLogger());
</code>


and in .NET Core:

<code csharp>
public class NebolErrorHandlingFilter : ExceptionFilterAttribute
{
    public override void OnException(ExceptionContext context)
    {
        var exception = context.Exception;
        Logger.Instance.Error(context.Exception.ToString());

        context.ExceptionHandled = true; //optional 
    }
}
</code>

then add the filter in Startup.cs ConfigureServices():

<code csharp>
options.Filters.Add(new NebolErrorHandlingFilter());
</code>





=== Related packages ===

  * [[NebolLogger.EntityFramework]]
  * [[NebolLogger.Controller]]
  * [[NebolLogger.Mailer]]
  * [[NebolLogger.PushBullet]]
  * [[NebolLogger.SharpRepository]]


OBSOLETE!

NebolLogger.EntityFramework.Core - for logging to database using .NET Core

OBSOLETE!  .NET Core is now supported in [[NebolLogger.EntityFramework]]