Chd.Library.Logging 8.7.2

Logging Library for .NET 8

Chd (Cleverly Handle Difficulty) library helps you cleverly handle difficulty, write code quickly, and keep your application stable.

The NuGet package id is Chd.Library.Logging. This package targets .NET 8 (net8.0).

If you are targeting .NET 10, use Chd.Logging instead.

Table of Contents

• About
• Features
• Installing
  • Upgrading from earlier versions
• Getting Started
• Configuration
• Usage
  • Aspect-Oriented Logging
  • Manual Logging
• Supported Sinks
• Test Results
• Examples & Tests
• Authors
• Acknowledgements

About

Chd.Library.Logging enables aspect-oriented and manual logging for .NET 8 applications.

It can write to Graylog, Microsoft SQL Server, a file, and the console. [Logged] is applied automatically at build time. No extra setup is needed. Log entries include the method name, parameters, return value, and, when an HTTP context is available, user details.

Features

• Aspect logging via the [Logged] attribute (supports async methods)
• Manual logging via the static Logger class (Library.Logging.Utils)
• Sinks: Graylog or Microsoft SQL Server (selected with LogConfig:Sink); file and console writers are also configured
• Log entries include method, class, parameter and return-value information
• .NET 8 (net8.0)
• Includes user and request information when HttpContext is present on the instance

Installing

dotnet add package Chd.Library.Logging --version 8.7.2

NuGet Package Manager:

Install-Package Chd.Library.Logging -Version 8.7.2

Package Reference (.csproj):

<PackageReference Include="Chd.Library.Logging" Version="8.7.2" />

That is the only package you need to add. Logging is applied automatically at build time. No extra setup is needed.

If the project already has a FodyWeavers.xml file, add <MethodBoundaryAspect /> to it so [Logged] runs with your other weavers:

<?xml version="1.0" encoding="utf-8"?>
<Weavers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="FodyWeavers.xsd">
  <MethodBoundaryAspect />
</Weavers>

Upgrading from earlier versions

Earlier versions of this package asked you to install MethodBoundaryAspect.Fody (and Fody) yourself. That setup keeps working: you can upgrade this package and leave those references and a FodyWeavers.xml file in place.

You may optionally remove the manual Fody and MethodBoundaryAspect.Fody package references; weaving is included in this package. If you keep a FodyWeavers.xml file, it must contain <MethodBoundaryAspect />.

Getting Started

1. Enable the logger in your API pipeline

In Program.cs:

var builder = WebApplication.CreateBuilder(args);
// ... register other services
var app = builder.Build();
app.UseLogger();

Call app.UseLogger() at startup, before methods marked with [Logged] run. There is also IServiceCollection.AddLogger(), which performs the same initialization.

Configuration

Logging config in appsettings.json

{
  "LogConfig": {
    "ApplicationName": "YourApp",
    "Sink": "Graylog",
    "SinkDBConnectionString": "Server=.;Database=LogsDb;User Id=sa;Password=YourPass;",
    "SinkTableName": "Logs",
    "Server": "localhost",
    "Port": "3003",
    "Path": "C:\\Logs\\YourApp\\log.txt",
    "PathFormat": "C:\\Logs\\YourApp\\log-{Date}.txt",
    "FileSizeLimitBytes": 1073741824,
    "RetainedFileCountLimit": 10,
    "IsLogSessionInfo": false
  }
}

UseLogger() reads appsettings.json and appsettings.{Environment}.json from the application base directory.

Usage

Aspect-Oriented Logging

Add [Logged] to any method (controller or service). The attribute is in the global namespace, so no extra using is required. AspectType lives in Library.Logging.Enums.

using Library.Logging.Enums;
using Microsoft.AspNetCore.Mvc;

public class LoggingTestController : ControllerBase
{
    public LoggingTestController() {}

    [Logged]
    [Route("Sum")]
    [HttpGet]
    public int? Sum(int a, int b)
    {
        return a + b;
    }

    // Optional: log only exceptions
    [Logged(AspectType.OnException)]
    [HttpPost("save")]
    public IActionResult Save(Order order)
    {
        // ...
        return Ok();
    }
}

• No other logging code is required on the method. Entry, successful completion (including the return value) and exceptions are written automatically.
• Constructors: [Logged], [Logged(AspectType)], and a third overload that also takes a FlowBehavior and an optional return value.
• AspectType values: OnEntry, OnExit, OnException, All (the default).

[Logged] also supports methods that return Task or Task<T>: on exit, the task is awaited and, for Task<T>, the result is logged.

Manual Logging

You can also write log messages directly:

using Library.Logging.Utils;

Logger.LogInformation("Custom info message...");
Logger.LogError("This went wrong!");
Logger.LogWarning("Something to watch");
Logger.LogFatal("Unrecoverable error");
Logger.LogTrace("Includes the calling method's name and type in the title");
Logger.CloseAndFlush();

LogInformation, LogError, LogWarning and LogFatal each take a message and an optional title string (not an exception object). Log is the general entry point: Logger.Log(message, LogType.Error, title).

Supported Sinks

• Graylog: the default. Set "Sink": "Graylog" and provide Server and Port. Transport is UDP.
• Microsoft SQL Server: set "Sink": "MSSql" and provide SinkDBConnectionString (or a LogsDb / Default connection string) and optionally SinkTableName. When MSSql is selected, the Graylog writer is not used.
• File and console: the embedded Serilog template always includes a console writer and a file writer. File output uses Path, PathFormat, FileSizeLimitBytes and RetainedFileCountLimit.

Test Results

• Logs can be inspected in the Graylog UI, in the SQL table, on the console, or in the file.

• Each [Logged] entry includes:

  • Method and parameters
  • Return value (or exception message and stack trace)
  • User and request information, when HttpContext is available on the instance
  • Timestamp

• Example:

  The LoggingTestController.Sum method started working with "[4,7]" parameters. The LoggingTestController.Sum method successfully completed with input ("[4,7]") and returned (11). ExecutionTimeMs: 1ms

Examples & Tests

Working samples, unit tests, load tests and benchmarks for CHD packages are available in the public Chd.Examples repository.

Authors

• Mehmet Yoldaş

See also other contributors on NuGet.

Acknowledgements

• Graylog
• MethodBoundaryAspect.Fody
• Thanks for using this library — issues and PRs are welcome.

For issues or feature requests, visit mehmet-yoldas/Chd.Examples