Tolitech.Logging.Extensions 1.0.0-preview.3

Tolitech.Logging.Extensions

Tolitech.Logging.Extensions enhances logging in .NET applications using Microsoft.Extensions.Logging, providing standardized, high-performance, and maintainable logging practices.

Overview

This library centralizes logger message definitions using Microsoft's LoggerMessage attribute, enabling source-generated logging methods for optimal performance and consistency.

Features

• Predefined Logger Messages: Centralized, strongly-typed logging methods for common scenarios.
• Source Generation: Uses LoggerMessage for compile-time generation, reducing runtime overhead.
• Consistency: Ensures uniform log messages across applications.
• Extensibility: Easily add new log definitions for your domain.

Usage

1. Add NuGet Reference

Add Tolitech.Logging.Extensions to your project:

# dotnet CLI
 dotnet add package Tolitech.Logging.Extensions

2. Use Predefined Logger Messages

using Microsoft.Extensions.Logging;
using Tolitech.Logging.Extensions;

public class MyService
{
    private readonly ILogger<MyService> _logger;

    public MyService(ILogger<MyService> logger)
    {
        _logger = logger;
    }

    public void DoWork()
    {
        try
        {
            // ...
        }
        catch (Exception ex)
        {
            _logger.UnexpectedError(ex);
        }
    }
}

3. Available Logger Methods

_logger.UnexpectedError(exception); // Logs unexpected errors
_logger.DatabaseConstraintError(exception); // Logs database constraint violations

4. Custom Logger Messages

You can extend the LoggerMessageDefinitions class with your own methods:

public static partial class LoggerMessageDefinitions
{
    [LoggerMessage(
        EventName = "CustomDomainError",
        Level = LogLevel.Warning,
        Message = "A domain-specific warning occurred.",
        SkipEnabledCheck = true)]
    public static partial void CustomDomainError(this ILogger logger, Exception exception);
}

5. Logging Configuration

Ensure your logging provider is configured in appsettings.json or programmatically:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Tolitech.Logging.Extensions": "Error"
    }
  }
}

FAQ

Q: What are the benefits of source-generated logging? A: It reduces allocations and improves performance by generating efficient code at compile time.

Q: Can I use this library with other logging providers? A: Yes, it works with any provider compatible with Microsoft.Extensions.Logging.

Q: How do I add new log message definitions? A: Add new partial methods to the LoggerMessageDefinitions class using the LoggerMessage attribute.

Advanced Scenarios

• AOT & Trimming: Fully compatible with .NET Native AOT and trimming.
• Unit Testing: Use mocking frameworks (e.g., Moq) to verify logging calls.

// Example unit test
var mockLogger = new Mock<ILogger<MyService>>();
mockLogger.Object.UnexpectedError(new Exception("Test"));
mockLogger.Verify(
    logger => logger.Log(
        LogLevel.Error,
        It.IsAny<EventId>(),
        It.IsAny<object>(),
        It.IsAny<Exception>(),
        It.IsAny<Func<object, Exception, string>>()),
    Times.Once);