pvNugsLoggerNc10Abstractions 10.0.2

pvNugsLoggerNc10Abstractions

A comprehensive .NET Core 10 logging abstraction library that provides structured, contextual logging with support for multiple output destinations, user contexts, and typed logging capabilities.

Features

• Multiple Output Destinations: Support for console, SQL, and hybrid logging configurations
• Contextual Logging: Track user, company, and topic contexts across log entries
• Structured Logging: Detailed metadata for each log entry including machine name, method name, and line numbers
• Severity Levels: Comprehensive severity level system compatible with Microsoft's LogLevel
• Method Result Tracking: Built-in support for tracking method execution results and notifications
• Base Implementation: Ready-to-use abstract base class for creating custom logging implementations
• Async Support: Both synchronous and asynchronous logging methods
• Unit Testing Support: Specialized interfaces for testing logging behavior

Installation

Install via NuGet Package Manager:

Install-Package pvNugsLoggerNc10Abstractions

Or via .NET CLI:

dotnet add package pvNugsLoggerNc10Abstractions

Requirements

• .NET Core 10.0 or higher
• C# 13.0 or higher

Core Components

Logger Services

• ILoggerService: The main logging interface that provides comprehensive logging functionality
• BaseLoggerService: Abstract base class implementing ILoggerService with core functionality
• IConsoleLoggerService: Specialized service for console output
• IHybridLoggerService: Combines multiple logging outputs
• IUTestLoggerService: Specialized service for unit testing scenarios

Log Writers

• ILogWriter: Base interface for writing log entries to various destinations
• IConsoleLogWriter: Specialized writer for console output
• IUTestLogWriter: Writer with additional capabilities for testing scenarios

Method Results

• IMethodResult: Tracks method execution status and notifications
• IMethodResultNotification: Represents individual notifications within results
• MethodResult: Concrete implementation of IMethodResult for tracking method execution results
• MethodResult<T>: Generic method result that includes typed return values

HTTP Result Wrappers

• DsoHttpResult: HTTP response wrapper for downstream operations with status, notifications, and mutation tracking
• DsoHttpResult<T>: Generic HTTP result that includes typed data payloads
• DsoHttpResultMutationEnu: Enumeration defining mutation types (None, Create, Update, Delete)
• DsoHttpResultNotification: Notification message within an HTTP result with severity and message

Data Structures

• ILoggerServiceRow: Represents a structured log entry with metadata
• SeverityEnu: Defines available logging severity levels
• SqlRoleEnu: Defines SQL database access roles

Basic Usage

Method Results

The library includes a comprehensive method result tracking system:

public MethodResult ProcessData(string data)
{
    var result = new MethodResult();
    
    if (string.IsNullOrEmpty(data))
    {
        result.AddNotification("Data cannot be empty", SeverityEnu.Error);
        return result;
    }
    
    try
    {
        // Process data...
        result.AddNotification("Data processed successfully", SeverityEnu.Info);
    }
    catch (Exception ex)
    {
        return new MethodResult(ex); // Creates result from exception
    }
    
    return result;
}

// Generic method result with data
public MethodResult<UserDto> GetUser(string userId)
{
    try
    {
        var user = _repository.GetUser(userId);
        if (user == null)
        {
            return new MethodResult<UserDto>("User not found", SeverityEnu.Warning);
        }
        return new MethodResult<UserDto>(user);
    }
    catch (Exception ex)
    {
        return new MethodResult<UserDto>(ex);
    }
}

HTTP Result Wrappers

Convert method results to HTTP-friendly responses for APIs:

[HttpGet("{id}")]
public DsoHttpResult<UserDto> GetUser(string id)
{
    var methodResult = _userService.GetUser(id);
    
    // Convert method result to HTTP result
    if (methodResult.Failure)
    {
        return new DsoHttpResult<UserDto>(methodResult);
    }
    
    return new DsoHttpResult<UserDto>(methodResult.Data);
}

[HttpPost]
public DsoHttpResult<UserDto> CreateUser(CreateUserDto dto)
{
    try
    {
        var user = _userService.CreateUser(dto);
        
        // Return success with mutation tracking
        return new DsoHttpResult<UserDto>(
            user, 
            DsoHttpResultMutationEnu.Create);
    }
    catch (Exception ex)
    {
        // Convert exception to HTTP result
        return new DsoHttpResult<UserDto>(ex);
    }
}

// Paginated results
[HttpGet]
public DsoHttpResult<List<UserDto>> GetUsers(int page, int pageSize)
{
    var users = _userService.GetUsers(page, pageSize);
    var hasMore = _userService.HasMoreUsers(page, pageSize);
    
    return new DsoHttpResult<List<UserDto>>(users, hasMore);
}

The DsoHttpResult automatically sets the appropriate HTTP status code:

• Returns 200 OK for success scenarios
• Returns 500 InternalServerError for Error or Fatal severity levels
• Includes notifications collection for detailed error/warning messages
• Tracks mutation type (None, Create, Update, Delete) for auditing
• Supports pagination with HasMoreResults flag

Using Existing Implementations

public class ExampleService
{
    private readonly ILoggerService _logger;

    public ExampleService(ILoggerService logger)
    {
        _logger = logger;
    }

    public async Task DoSomethingAsync()
    {
        // Set context for subsequent log entries
        _logger.SetUser("user123", "company456");
        _logger.SetTopic("ImportantOperation");

        try
        {
            _logger.Log("Starting operation", SeverityEnu.Info);

            // Perform some work...

            await _logger.LogAsync(
                new[] { "Step 1 complete", "Step 2 complete" },
                SeverityEnu.Debug);
        }
        catch (Exception ex)
        {
            await _logger.LogAsync(ex);
            throw;
        }
    }
}

Creating Custom Implementations

public class CustomLoggerService : BaseLoggerService
{
    public CustomLoggerService(SeverityEnu minLevel, params ILogWriter[] logWriters)
        : base(minLevel, logWriters)
    {
    }

    // BaseLoggerService provides all the core functionality.
    // Override specific methods if needed for custom behavior.
}

public class CustomLogWriter : ILogWriter
{
    public void WriteLog(string? userId, string? companyId, string? topic,
        SeverityEnu severity, string machineName, string memberName,
        string filePath, int lineNumber, string message, DateTime dateUtc)
    {
        // Implement your custom log writing logic.
    }

    public async Task WriteLogAsync(string? userId, string? companyId, string? topic,
        SeverityEnu severity, string machineName, string memberName,
        string filePath, int lineNumber, string message, DateTime dateUtc)
    {
        // Implement your custom async log writing logic.
        await Task.CompletedTask;
    }

    public void Dispose() { }
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}

Unit Testing

public class LoggingTests
{
    private readonly IUTestLogWriter _logWriter;
    private readonly IUTestLoggerService _logger;

    [Fact]
    public void ShouldLogError()
    {
        _logger.Log("Test error", SeverityEnu.Error);

        Assert.True(_logWriter.Contains("Test error"));
        var logEntry = _logWriter.FindLastMatchingRow("Test error");
        Assert.Equal(SeverityEnu.Error, logEntry.Severity);
    }
}

Available Implementations

This abstractions package provides the foundation for logging implementations.

Companion implementation packages for the .NET Core 10 line can be documented here as they are published.

Microsoft.Extensions.Logging Integration

The BaseLoggerService implements the Microsoft.Extensions.Logging.ILogger interface, making it compatible with .NET Core 10 logging and dependency injection.