CSharpEssentials.LoggerHelper 1.2.2

📦 CSharpEssentials.LoggerHelper

Introduction

LoggerHelper is a library designed to simplify, standardize, and enhance logging management in .NET applications, using Serilog as the core engine.

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

🚀 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.119:9200",
          "indexFormat": "PixeloApp"
        },
        "Email": {
          "From": "<Email Alert>",
          "Port": 587,
          "Host": "<Host EMail>",
          "To": [ "recipient#1", "recipient#2" ],
          "CredentialHost": "<UserName SMTP>",
          "CredentialPassword": "<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:

using CSharpEssentials.LoggerHelper;

var builder = WebApplication.CreateBuilder(args);

// Add LoggerHelper configuration
builder.Services.addloggerConfiguration(builder);
builder.Services.AddControllers();

var app = builder.Build();

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

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

🧑‍💻 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