FractalDataWorks.MessageLogging.Abstractions 0.4.0-preview.6

FractalDataWorks.MessageLogging.Abstractions

Attribute definitions for source-generated logging methods that return IGenericMessage.

Overview

This package provides the [MessageLogging] attribute used to mark partial methods for source generation. The source generator (FractalDataWorks.MessageLogging.SourceGenerators) generates implementations that both log messages AND return them as IGenericMessage instances. This enables the FractalDataWorks pattern: every logged message is returned in the result.

Based on Microsoft's LoggerMessageAttribute with extensions for IGenericMessage return types.

Target Framework

• netstandard2.0

Installation

<PackageReference Include="FractalDataWorks.MessageLogging.Abstractions" />
<PackageReference Include="FractalDataWorks.MessageLogging.SourceGenerators"
                  OutputItemType="Analyzer"
                  ReferenceOutputAssembly="false" />

Dependencies

• FractalDataWorks.Messages - Provides IGenericMessage and MessageSeverity
• Microsoft.Extensions.Logging.Abstractions - Provides ILogger and LogLevel

API Reference

MessageLoggingAttribute

From MessageLoggingAttribute.cs:24-116:

[AttributeUsage(AttributeTargets.Method)]
public sealed class MessageLoggingAttribute : Attribute
{
    public MessageLoggingAttribute() { }
    public MessageLoggingAttribute(int eventId, LogLevel level, string message) { ... }
    public MessageLoggingAttribute(LogLevel level, string message) { ... }
    public MessageLoggingAttribute(LogLevel level) { ... }
    public MessageLoggingAttribute(string message) { ... }

    public int EventId { get; set; } = -1;
    public string? EventName { get; set; }
    public LogLevel Level { get; set; } = LogLevel.None;
    public string Message { get; set; } = string.Empty;
    public bool SkipEnabledCheck { get; set; }
    public MessageSeverity Severity { get; set; } = MessageSeverity.Information;
    public bool AutoMapSeverity { get; set; } = true;
}

Properties:

Method Requirements

From MessageLoggingAttribute.cs:12-22:

Methods decorated with [MessageLogging]:

• Must be a partial method
• Must return IGenericMessage or a type that implements it
• Must not be generic
• Must have an ILogger as one of its parameters
• None of the parameters can be generic

Usage

From Reference Solution OrderLog.cs:31-37:

[MessageLogging(
    EventId = 8001,
    Level = LogLevel.Debug,
    Message = "Starting order processing for order '{orderId}'")]
public static partial IGenericMessage ProcessingStarted(
    ILogger logger,
    string orderId);

From Reference Solution OrderLog.cs:114-120:

[MessageLogging(
    EventId = 8030,
    Level = LogLevel.Error,
    Message = "Order '{orderId}' not found")]
public static partial IGenericMessage OrderNotFound(
    ILogger logger,
    string orderId);

Log AND Return Pattern

From Reference Solution OrderService.cs:77-80:

// Log AND return success
// The message is logged internally AND returned in the result
var successMessage = OrderLog.OrderCreated(_logger, orderId, customerId);
return GenericResult<Order>.Success(order, successMessage);

From Reference Solution OrderService.cs:82-88:

catch (Exception ex)
{
    // CRITICAL PATTERN: Catch -> Log -> Return (never rethrow!)
    // The message is logged AND returned
    return GenericResult<Order>.Failure(
        OrderLog.ProcessingException(_logger, ex, orderId));
}

Related Packages

• FractalDataWorks.MessageLogging.SourceGenerators - Source generator that implements marked methods
• FractalDataWorks.Messages - IGenericMessage interface and implementations
• FractalDataWorks.Results - IGenericResult for returning messages in results

Next Steps

• See the Reference Solution MessageLogging concept for complete working examples
• See FractalDataWorks.Messages for message types and severity levels