CSharpEssentials.LoggerHelper 2.0.1

📦 CSharpEssentials.LoggerHelper

Introduction

A flexible and modular structured logging library for .NET ( 6.0/8.0 ) applications based on Serilog. Easily configure logging to Console, File, Email, PostgreSQL, ElasticSearch via simple JSON configuration. Includes automatic placeholder validation and multi-sink orchestration.

It allows you to:

• Send structured logs with guaranteed fields like Action, IdTransaction, ApplicationName, MachineName
• Dynamically enable multi-sink support (Console, File, HTML Email, PostgreSQL, ElasticSearch)
• Automatically validate message {} placeholders
• Centralize configuration through LoggerBuilder, just by editing the appsettings.json file

In common usage scenarios, it is advisable to avoid logging Information level events to sinks like Telegram, MSSQL, or PostgreSQL. This practice prevents issues such as HTTP 429 (rate limits) on Telegram and reduces risks of deadlocks or insufficient storage in database systems.

📚 Table of Contents

• ✨ Features
• 🚀 Installation
• ⚙️ Configuration
• 📌 Log Levels
• 🧪 ASP.NET Core Setup
• 🧑‍💻 Usage Examples
• 🧬 Database Schema
• 🔁 Demo API
• 🙌 Contributing
• 📄 License
• 👤 Author

✨ Features

• ✅ Multi-sink logging support:

  • Console
  • File
  • SQL Server
  • PostgreSQL
  • Elasticsearch
  • Email
  • Telegram

• ✅ Structured logs with custom properties

• ✅ Sync and async logging

• ✅ Request/response middleware logger

• ✅ Transaction ID, action, machine name

• ✅ Custom levels per sink

• ✅ JSON configuration via appsettings.LoggerHelper.json

⚠️ Version 2.0.0 - Breaking Change

Starting from version 2.0.0, the Email configuration section has been renamed.

If you are upgrading from 1.x.x, you MUST update your appsettings.LoggerHelper.json.

Old (before 2.0.0):

"Email": {
  "From": "...",
  "Host": "...",
  "Port": 587,
  "To": ["..."],
  "CredentialHost": "...",
  "CredentialPassword": "..."
}

New (since 2.0.0):

"Email": {
  "From": "...",
  "Host": "...",
  "Port": 587,
  "To": "...",
  "username": "...",
  "password": "...",
  "EnableSsl": true
}

🚨 Why Email Handling Changed

Starting from version 2.0.0, LoggerHelper no longer uses the standard Serilog.Sinks.Email for sending emails.

Reason:
The official Serilog Email Sink does not support custom body formatting (HTML templates, structured logs, color coding, etc).
It only supports plain text messages generated via RenderMessage(), without the ability to control the message content.

🔎 See discussion: GitHub Issue - serilog/serilog-sinks-email

What changed:

• LoggerHelper now uses a custom internal SMTP sink: LoggerHelperEmailSink.
• This allows sending fully customized HTML-formatted emails.
• Supports dynamic coloring based on log level (Information, Warning, Error).
• Supports secure SMTP with SSL/TLS.

✅ No third-party dependencies added.
✅ Full control over email appearance and content.

🚀 Installation

dotnet add package CSharpEssentials.LoggerHelper

⚙️ Configuration

Create a file named appsettings.LoggerHelper.json in your project root:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Debug",
        "System": "Debug"
      }
    },
    "SerilogConfiguration": {
      "ApplicationName": "TestApp",
      "SerilogCondition": [
        {"Sink": "ElasticSearch","Level": []},
        {"Sink": "MSSqlServer","Level": []},
        {"Sink": "Email","Level": []},
        {"Sink": "PostgreSQL","Level": ["Information","Warning","Error","Fatal"]},
        {"Sink": "Telegram","Level": []},
        {"Sink": "Console","Level": [ "Information" ]},
        {"Sink": "File","Level": ["Information","Warning","Error","Fatal"]}
      ],
      "SerilogOption": {
        "File": {
          "Path": "D:\\Logs\\ServerDemo",
          "RollingInterval": "Day",
          "RetainedFileCountLimit": 7,
          "Shared": true
        },
        "TelegramOption": {
          "chatId": "xxxxx",
          "Api_Key": "sssss:ttttttttt"
        },
        "PostgreSQL": {
          "connectionString": "<YOUR CONNECTIONSTRING>",
          "tableName": "public",
          "schemaName": "dbo",
          "needAutoCreateTable": true
        },
        "ElasticSearch": {
          "nodeUris": "http://10.0.1.100:9200",
          "indexFormat": "<YOUR INDEX FORMAT>"
        },
        "Email": {
          "From": "<Email Alert>",
          "Port": 587,
          "Host": "<Host EMail>",
          "To": [ "recipient#1", "recipient#2" ],
          "username": "<UserName SMTP>",
          "password": "<Password SMTP>"
        },
        "MSSqlServer": {
          "connectionString": "<YOUR CONNECTIONSTRING>",
          "sinkOptionsSection": {
            "tableName": "logs",
            "schemaName": "dbo",
            "autoCreateSqlTable": true,
            "batchPostingLimit": 100,
            "period": "0.00:00:10"
          },
          "columnOptionsSection": {
            "addStandardColumns": [
              "LogEvent"
            ],
            "removeStandardColumns": [
              "Properties"
            ]
          }
        },
        "GeneralConfig": {
          "EnableSelfLogging": false
        }
      }
    }
  }
}

⚠️ Important: The logger will only write to a sink if the Level array in SerilogCondition contains at least one valid log level (e.g., "Error", "Warning"). If the Level array is empty (e.g., "Level": []), that sink will be ignored, and WriteTo** will not be applied**, even if the sink configuration exists.

🧩 PostgreSQL is preconfigured with a default column mapping for logs. The following columns are used automatically: message, message_template, level, raise_date, exception, properties, props_test, machine_name. No custom mapping is required in the JSON.

📌 Log Levels

🖼️ Example of a Telegram-formatted log message:

💬 Telegram Notice: When using the Telegram sink, log messages are formatted for human readability, and may include emojis or markdown. For this reason, it's strongly recommended to set the Level to only Error or Fatal to avoid exceeding Telegram's rate limits and to prevent excessive message noise.

🛠 Tip: Before publishing to production, test each sink you plan to use. You can enable Serilog self-logging to capture internal errors using:

Serilog.Debugging.SelfLog.Enable(msg =>
    File.AppendAllText(Path.Combine(logPath, "serilog-selflog.txt"), msg));

Replace logPath with your local or shared log directory. This helps identify misconfigurations or sink loading issues early.

Each sink only receives log levels specified in the SerilogCondition array. If a sink's Level array is empty, that sink will be ignored entirely, and no log will be written to it, even if it's configured elsewhere:

🧪 ASP.NET Core Setup

Request/Response Logging Middleware

The LoggerHelper package includes a built-in middleware that logs every incoming HTTP request and outgoing response automatically. It captures:

• HTTP method, path, status code
• Request body (if available)
• Response body (if possible)
• Duration in milliseconds

To enable it, just call:

app.UseMiddleware<RequestResponseLoggingMiddleware>();

📌 This middleware uses LogEventLevel.Information by default and is automatically compatible with sinks that accept that level.

🔥 Register the logger in Program.cs

🚀 Important Setup

⚠️ IMPORTANT: You must call AddLoggerConfiguration during the Program.cs setup. Without it, LoggerHelper will NOT work. No logs will be captured, and no middleware will be active.

ℹ️ Important: depending on the target framework version, you must configure LoggerHelper differently.

If you are using .NET 6.0, you must call the configuration directly on the builder. If you are using .NET 8.0, you must call it on the builder.Services.

Here’s how you should do it:

using CSharpEssentials.LoggerHelper;

var builder = WebApplication.CreateBuilder(args);

// Add LoggerHelper configuration
#if NET6_0
    builder.AddLoggerConfiguration();
#else
    builder.Services.AddLoggerConfiguration(builder);
#endif

builder.Services.AddControllers();

var app = builder.Build();

// Logs every HTTP request and response
app.UseMiddleware<RequestResponseLoggingMiddleware>();

app.MapControllers();
app.Run();

🧠 Explanation

This ensures full compatibility across different .NET versions.

🧑‍💻 Usage Examples

🔹 With request object

loggerExtension<MyRequest>.TraceSync(
    request,
    LogEventLevel.Information,
    null,
    "Operation successful: {OperationName}",
    "CreateUser"
);

🔹 Async logging

await loggerExtension<MyRequest>.TraceAsync(
    request,
    LogEventLevel.Error,
    exception,
    "Error during operation: {OperationName}",
    "UpdateUser"
);

🔹 Without request object

loggerExtension<IRequest>.TraceSync(
    null,
    LogEventLevel.Warning,
    null,
    "System warning: {WarningMessage}",
    "Low disk space"
);

Database Schema

PostgreSQL

SQL Server

Swagger Example

HTML Email Screenshot

Demo API

Try it live with a demo Web API to validate each log level dynamically:

🔗 GitHub Repository (Demo)

🧪 Troubleshooting

File access denied?

• ❌ If you get System.IO.IOException like: "file is being used by another process", make sure:

  • No other process (e.g. text editor, logging library) is locking the file.
  • The file is not open in append-only exclusive mode.

• ✅ For self-log output (serilog-selflog.txt), ensure that:

  • The target folder exists.
  • The executing process has write permission to it.
  • Use FileShare.ReadWrite if needed.

Sink not writing logs?

• ✅ Make sure the Level array in SerilogCondition is not empty.
• ✅ Check serilog-selflog.txt if enabled — it often reveals silent misconfigurations.

🙌 Contributing

Contributions, ideas and issues are welcome! Feel free to open a pull request or discussion on GitHub.

📄 License

This project is licensed under the MIT License.

👤 Author

Alessandro Chiodo 📧 GitHub · NuGet · LinkedIn 📦 NuGet Package