Sudzekai.AspNetCore.Toolkit.Logging 1.0.0

sudzekai's Toolkit for ASP.NET — Logging Modules

Overview

The Logging Module provides logging configuration for ASP.NET applications through the Toolkit.

Console Logging Module

The module supports:

• configuration through IConfiguration;
• programmatic configuration through ConsoleLoggingModule.Configure();
• built-in ASP.NET Core console formatters;
• the custom ToolkitConsoleFormatter;
• custom console formatters.

The module must be registered in the Toolkit before it can be configured:

toolkit.Modules.AddModule<ConsoleLoggingModule>();

Alternatively, an existing module instance can be registered:

var module = new ConsoleLoggingModule();

toolkit.Modules.AddModuleInstance(module);

Enabling the Module

The module can be enabled during programmatic configuration:

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;

    // ...
});

Alternatively, the module can be enabled separately:

toolkit.Modules
    .GetModule<ConsoleLoggingModule>()
    .Enable();

When using IConfiguration, the module is enabled by setting IsEnabled to true in the configuration section.

Formatters

The Console Logging Module supports the following formatters:

• Default console formatter — DefaultConsoleFormatterOptions
• JSON console formatter — JsonConsoleFormatterOptions
• Simple console formatter — SimpleConsoleFormatterOptions
• Systemd console formatter — SystemdConsoleFormatterOptions
• Toolkit console formatter — ToolkitConsoleFormatterOptions

All formatter options inherit from the abstract PolymorphicConsoleFormatterOptions class.

The module also supports custom console formatters through the ConfigureCustom() method.

Default Console Formatter

The default console formatter is the standard ASP.NET Core console formatter.

Configuration using IConfiguration

To configure the default console formatter through IConfiguration, add the following section to appsettings.json:

{
  "Toolkit": {
    "Logging": {
      "IsEnabled": true,
      "LogLevel": "Information",
      "FormatterName": "",
      "FormatterKind": "Default",
      "ConsoleFormatterOptions": {
        "$type": "default",
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true,
        "IncludeScopes": true
      }
    }
  }
}

The module can then be configured directly:

toolkit.Modules
    .GetModule<ConsoleLoggingModule>()
    .Configure(builder.Configuration);

Or together with all registered Toolkit modules:

toolkit.Modules.ConfigureAll(builder.Configuration);

Configuration using Configure()

The default formatter can also be configured programmatically:

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;
    o.LogLevel = LogLevel.Information;

    o.ConfigureDefault(t =>
    {
        t.TimestampFormat = "HH:mm:ss";
        t.UseUtcTimestamp = true;
        t.IncludeScopes = true;
    });
});

After applying the module configuration, logging through ILogger produces output similar to:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5021
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Toolkit Console Formatter

ToolkitConsoleFormatter is a custom console formatter provided by the Console Logging Module.

It provides additional formatting options, including separate foreground and background colors for different log levels, message, category, and timestamp.

Configuration using IConfiguration

Add the following section to appsettings.json:

{
  "Toolkit": {
    "Logging": {
      "IsEnabled": true,
      "LogLevel": "Information",
      "FormatterName": "Toolkit",
      "FormatterKind": "Toolkit",
      "ConsoleFormatterOptions": {
        "$type": "toolkit",
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true,
        "IncludeScopes": true,
        "TraceLevelForegroundColor": "Black",
        "TraceLevelBackgroundColor": "Gray",
        "DebugLevelForegroundColor": "Default",
        "DebugLevelBackgroundColor": "Default",
        "InformationLevelForegroundColor": "Blue",
        "InformationLevelBackgroundColor": "Default",
        "WarningLevelForegroundColor": "DarkYellow",
        "WarningLevelBackgroundColor": "Default",
        "ErrorLevelForegroundColor": "Red",
        "ErrorLevelBackgroundColor": "Default",
        "CriticalLevelForegroundColor": "Gray",
        "CriticalLevelBackgroundColor": "Red",
        "MessageForegroundColor": "Gray",
        "MessageBackgroundColor": "Default",
        "CategoryForegroundColor": "DarkGray",
        "CategoryBackgroundColor": "Default",
        "TimestampForegroundColor": "Gray",
        "TimestampBackgroundColor": "Default",
        "LineLength": 100,
        "SingleLine": false
      }
    }
  }
}

Configure the module using the application's configuration:

toolkit.Modules
    .GetModule<ConsoleLoggingModule>()
    .Configure(builder.Configuration);

Or configure all registered Toolkit modules:

toolkit.Modules.ConfigureAll(builder.Configuration);

Configuration using Configure()

The Toolkit formatter can also be configured programmatically:

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;
    o.LogLevel = LogLevel.Information;

    o.ConfigureToolkit(t =>
    {
        t.TimestampFormat = "HH:mm:ss";
        t.UseUtcTimestamp = true;
        t.IncludeScopes = true;

        t.TraceLevelForegroundColor = Color.Black;
        t.TraceLevelBackgroundColor = Color.Gray;
        t.DebugLevelForegroundColor = Color.Default;
        t.DebugLevelBackgroundColor = Color.Default;
        t.InformationLevelForegroundColor = Color.Blue;
        t.InformationLevelBackgroundColor = Color.Default;
        t.WarningLevelForegroundColor = Color.DarkYellow;
        t.WarningLevelBackgroundColor = Color.Default;
        t.ErrorLevelForegroundColor = Color.Red;
        t.ErrorLevelBackgroundColor = Color.Default;
        t.CriticalLevelForegroundColor = Color.Gray;
        t.CriticalLevelBackgroundColor = Color.Red;
        t.MessageForegroundColor = Color.Gray;
        t.MessageBackgroundColor = Color.Default;
        t.CategoryForegroundColor = Color.DarkGray;
        t.CategoryBackgroundColor = Color.Default;
        t.TimestampForegroundColor = Color.Gray;
        t.TimestampBackgroundColor = Color.Default;
        t.LineLength = 100;
        t.SingleLine = false;
    });
});

After applying the module configuration, logging through ILogger produces output similar to:

05:28:05 INFO Microsoft.Hosting.Lifetime
         Now listening on: http://localhost:5021
05:28:05 INFO Microsoft.Hosting.Lifetime
         Application started. Press Ctrl+C to shut down.
05:28:05 INFO Microsoft.Hosting.Lifetime
         Hosting environment: Development

Simple Console Formatter

SimpleConsoleFormatter is a built-in ASP.NET Core console formatter.

It provides options for controlling single-line output, timestamps, scopes, and console colors.

Configuration using IConfiguration

Add the following section to appsettings.json:

{
  "Toolkit": {
    "Logging": {
      "IsEnabled": true,
      "LogLevel": "Information",
      "FormatterName": "simple",
      "FormatterKind": "Simple",
      "ConsoleFormatterOptions": {
        "$type": "simple",
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true,
        "IncludeScopes": true,
        "SingleLine": false,
        "ColorBehavior": "Enabled"
      }
    }
  }
}

Configure the module using the application's configuration:

toolkit.Modules
    .GetModule<ConsoleLoggingModule>()
    .Configure(builder.Configuration);

Or configure all registered Toolkit modules:

toolkit.Modules.ConfigureAll(builder.Configuration);

Configuration using Configure()

The Simple formatter can also be configured programmatically:

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;
    o.LogLevel = LogLevel.Information;

    o.ConfigureSimple(t =>
    {
        t.TimestampFormat = "HH:mm:ss";
        t.UseUtcTimestamp = true;
        t.IncludeScopes = true;
        t.SingleLine = false;
        t.ColorBehavior = LoggerColorBehavior.Enabled;
    });
});

After applying the module configuration, logging through ILogger produces output similar to:

03:16:39 info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5021
03:16:39 info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
03:16:39 info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Systemd Console Formatter

SystemdConsoleFormatter is a built-in ASP.NET Core console formatter designed for logging in systemd environments.

It supports timestamp formatting, UTC timestamps, and logging scopes.

Configuration using IConfiguration

Add the following section to appsettings.json:

{
  "Toolkit": {
    "Logging": {
      "IsEnabled": true,
      "LogLevel": "Information",
      "FormatterName": "systemd",
      "FormatterKind": "Systemd",
      "ConsoleFormatterOptions": {
        "$type": "systemd",
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true,
        "IncludeScopes": true
      }
    }
  }
}

Configure the module using the application's configuration:

toolkit.Modules
    .GetModule<ConsoleLoggingModule>()
    .Configure(builder.Configuration);

Or configure all registered Toolkit modules:

toolkit.Modules.ConfigureAll(builder.Configuration);

Configuration using Configure()

The Systemd formatter can also be configured programmatically:

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;
    o.LogLevel = LogLevel.Information;

    o.ConfigureSystemd(t =>
    {
        t.TimestampFormat = "HH:mm:ss";
        t.UseUtcTimestamp = true;
        t.IncludeScopes = true;
    });
});

After applying the module configuration, logging through ILogger produces output similar to:

<6>03:17:28Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:5021
<6>03:17:28Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down.
<6>03:17:28Microsoft.Hosting.Lifetime[0] Hosting environment: Development

JSON Console Formatter

JsonConsoleFormatter is a built-in ASP.NET Core console formatter that writes log entries in JSON format.

It is useful when logs are consumed by log aggregation, monitoring, or other machine-readable systems.

Configuration using IConfiguration

Add the following section to appsettings.json:

{
  "Toolkit": {
    "Logging": {
      "IsEnabled": true,
      "LogLevel": "Information",
      "FormatterName": "json",
      "FormatterKind": "Json",
      "ConsoleFormatterOptions": {
        "$type": "json",
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true,
        "IncludeScopes": true,
        "JsonWriterOptions": {
          "Indented": false
        }
      }
    }
  }
}

Configure the module using the application's configuration:

toolkit.Modules
    .GetModule<ConsoleLoggingModule>()
    .Configure(builder.Configuration);

Or configure all registered Toolkit modules:

toolkit.Modules.ConfigureAll(builder.Configuration);

Configuration using Configure()

The JSON formatter can also be configured programmatically:

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;
    o.LogLevel = LogLevel.Information;

    o.ConfigureJson(t =>
    {
        t.TimestampFormat = "HH:mm:ss";
        t.UseUtcTimestamp = true;
        t.IncludeScopes = true;

        t.JsonWriterOptions = new JsonWriterOptions
        {
            Indented = false
        };
    });
});

After applying the module configuration, logging through ILogger produces output similar to:

{"Timestamp":"03:18:59","EventId":14,"LogLevel":"Information","Category":"Microsoft.Hosting.Lifetime","Message":"Now listening on: http://localhost:5021","State":{"address":"http://localhost:5021","{OriginalFormat}":"Now listening on: {address}"},"Scopes":[]}
{"Timestamp":"03:18:59","EventId":0,"LogLevel":"Information","Category":"Microsoft.Hosting.Lifetime","Message":"Application started. Press Ctrl\u002BC to shut down.","State":{"{OriginalFormat}":"Application started. Press Ctrl\u002BC to shut down."},"Scopes":[]}
{"Timestamp":"03:18:59","EventId":0,"LogLevel":"Information","Category":"Microsoft.Hosting.Lifetime","Message":"Hosting environment: Development","State":{"EnvName":"Development","{OriginalFormat}":"Hosting environment: {EnvName}"},"Scopes":[]}

Custom Console Formatter

The Console Logging Module supports custom console formatters through the ConfigureCustom() method.

ConfigureCustom() accepts only the name of the console formatter. It only selects the formatter by name and does not register, instantiate, or configure the formatter.

The formatter must be registered in the application's dependency injection container separately.

Configuration using Configure()

Specify the name of the registered console formatter using ConfigureCustom():

toolkit.Modules.GetModule<ConsoleLoggingModule>().Configure(o =>
{
    o.IsEnabled = true;
    o.LogLevel = LogLevel.Information;

    o.ConfigureCustom("MyFormatter");
});

Register the formatter in DI:

builder.Services.AddSingleton<ConsoleFormatter, MyConsoleFormatter>();

The name passed to ConfigureCustom() must match the formatter name specified by the registered ConsoleFormatter.

The Console Logging Module does not register custom formatters automatically. Registration and lifetime management of custom formatters remain the responsibility of the application.

Configuration using IConfiguration

Custom formatters can also be selected through IConfiguration:

{
  "Toolkit": {
    "Logging": {
      "IsEnabled": true,
      "LogLevel": "Information",
      "FormatterName": "MyFormatter",
      "FormatterKind": "Custom"
    }
  }
}

The formatter must still be registered in DI separately:

builder.Services.AddSingleton<ConsoleFormatter, MyConsoleFormatter>();

The FormatterName value must match the name of the registered formatter.

The module only selects the formatter; it does not create, register, or configure the custom formatter.