Differences

This shows you the differences between two versions of the page.

--- nebollogger [2021/05/07 23:45] – nebol
+++ nebollogger [2021/11/30 02:13] (current) – nebol
@@ Line 1: / Line 1: @@
 ==== NebolLogger ====
-Use a script from the "Database Scripts"-folder to create the database.
+NebolLogger is a C# package for quick and simple logging to database, file, or other destinations.
-Adding the database destination in .NET Core with NebolLogger.EntityFramework :
+See the nuget page at https://nuget.nebol.se for version history etc.
-<code>
+=== Quick example to give you an idea of how it works ===
-var optionsBuilder = new DbContextOptionsBuilder<NebolLoggerDbContext>();
-optionsBuilder.UseSqlServer(Config.ConnectionString);
-var dest = new Destination_Database(optionsBuilder.Options);
-Logger.Instance.Destinations.Add(dest);
-Logger.Instance.Trace("Logging initialized");
+<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]]

Nebol's Wiki

User Tools

Site Tools

Differences

Page Tools