FractalDataWorks.MessageLogging.SourceGenerators 0.4.0-preview.6

FractalDataWorks.MessageLogging.SourceGenerators

Source generator that creates logger methods returning IGenericMessage. Fork of Microsoft's LoggerMessage source generator extended for the FractalDataWorks pattern where every logged message is also returned for Result integration.

Overview

This Roslyn incremental source generator processes methods decorated with [MessageLogging] and generates implementation code that:

1. Logs to ILogger using Microsoft.Extensions.Logging
2. Returns an IGenericMessage containing the same message text

Target Framework

• netstandard2.0 (required for Roslyn source generators)

Installation

Reference this package as an analyzer:

From Reference.MessageLogging.csproj:24-26:

<ItemGroup>
  <PackageReference Include="FractalDataWorks.MessageLogging.SourceGenerators" />
</ItemGroup>

Usage

Define a partial class with partial methods decorated with [MessageLogging]:

From OrderLog.cs:22-37:

public static partial class OrderLog
{
    // =========================================================================
    // DEBUG: Detailed internal operations
    // =========================================================================

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

From OrderLog.cs:107-120:

    // =========================================================================
    // ERROR: Explicit failure modes (each one returns IGenericMessage for Result)
    // =========================================================================

    /// <summary>
    /// Logs when an order is not found.
    /// </summary>
    [MessageLogging(
        EventId = 8030,
        Level = LogLevel.Error,
        Message = "Order '{orderId}' not found")]
    public static partial IGenericMessage OrderNotFound(
        ILogger logger,
        string orderId);

Use in service code with the "log AND return" pattern:

From OrderService.cs:115-126:

    public IGenericResult<Order> GetOrder(string orderId)
    {
        // Simulate order not found
        if (orderId.StartsWith("NOTFOUND"))
        {
            // Log AND return failure - the message is both logged and returned
            return GenericResult<Order>.Failure(
                OrderLog.OrderNotFound(_logger, orderId));
        }

        return GenericResult<Order>.Success(new Order { OrderId = orderId, Status = "Found" });
    }

Generator Requirements

From LoggerMessageGenerator.Parser.cs:21:

The generator looks for methods with the attribute FractalDataWorks.MessageLogging.MessageLoggingAttribute.

From LoggerMessageGenerator.Parser.cs:275-281:

// Validate return type is IGenericMessage or compatible
if (!IsCompatibleReturnType(logMethodSymbol.ReturnType, genericMessageSymbol))
{
    // logging methods must return IGenericMessage or a type that implements it
    Diag(DiagnosticDescriptors.LoggingMethodMustReturnVoid, method.ReturnType.GetLocation());
    keepMethod = false;
}

Methods must:

• Be partial methods
• Return IGenericMessage or a type implementing it
• Have an ILogger parameter (for static methods) or class field
• Not be generic

Generated Code

The generator creates implementation that logs to ILogger and returns IGenericMessage:

From LoggerMessageGenerator.Emitter.cs:487-493:

            _builder.Append($@"
            {nestedIndentation}return new global::FractalDataWorks.Messages.GenericMessage(
                {nestedIndentation}    {severityMapping},
                {nestedIndentation}    __messageText,
                {nestedIndentation}    {eventName},
                {nestedIndentation}    null);
        {nestedIndentation}}}");

Related Packages

• FractalDataWorks.MessageLogging.Abstractions - Contains the [MessageLogging] attribute
• FractalDataWorks.Messages - Contains IGenericMessage and GenericMessage
• FractalDataWorks.Results - Contains IGenericResult<T> for Result integration

API Reference

See MessageLogging wiki section for complete documentation.