Sencilla.Messaging.SourceGenerator 10.0.62

Sencilla.Messaging.SourceGenerator

A source generator that automatically creates extension methods for IMessageDispatcher based on command classes marked with the [ExtendDispatcher] attribute.

Installation

Install the NuGet package in your project:

dotnet add package Sencilla.Messaging.SourceGenerator

Or via Package Manager:

<PackageReference Include="Sencilla.Messaging.SourceGenerator" Version="9.0.0" />

Usage

1. Mark your command class with the attribute

using Sencilla.Messaging;

[ExtendDispatcher(Method = "PrepareSpreadImage")]
public class PrepareSpreadImageCommand
{
    public int ImageId { get; set; }
    public string ProcessingType { get; set; } = "Standard";
    public required string TargetPath { get; set; }
}

2. Use the generated extension method

using Sencilla.Messaging;
using Sencilla.Messaging.Extensions; // Generated namespace

public class ImageProcessor
{
    private readonly IMessageDispatcher _dispatcher;

    public ImageProcessor(IMessageDispatcher dispatcher)
    {
        _dispatcher = dispatcher;
    }

    public async Task ProcessImageAsync(int imageId, string targetPath)
    {
        // Instead of manually creating the command:
        // await _dispatcher.Send(new PrepareSpreadImageCommand 
        // { 
        //     ImageId = imageId, 
        //     TargetPath = targetPath 
        // });
        
        // Use the generated extension method:
        await _dispatcher.PrepareSpreadImage(
            imageId: imageId, 
            targetPath: targetPath, 
            processingType: "Enhanced" // Optional with default
        );
    }
}

Generated Code

For the example above, the generator creates:

// <auto-generated />
using System;
using System.Threading;
using System.Threading.Tasks;

namespace Sencilla.Messaging.Extensions
{
    /// <summary>
    /// Auto-generated extension methods for IMessageDispatcher.
    /// </summary>
    public static class MessageDispatcherExtensions
    {
        /// <summary>
        /// Sends a PrepareSpreadImageCommand command.
        /// </summary>
        /// <param name="dispatcher">The message dispatcher.</param>
        /// <param name="imageId">The ImageId value.</param>
        /// <param name="targetPath">The TargetPath value.</param>
        /// <param name="processingType">The ProcessingType value.</param>
        /// <param name="cancellationToken">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        public static Task PrepareSpreadImage(
            this IMessageDispatcher dispatcher, 
            int imageId, 
            string targetPath, 
            string processingType = "Standard", 
            CancellationToken cancellationToken = default)
        {
            return dispatcher.Send(new PrepareSpreadImageCommand
            {
                ImageId = imageId,
                TargetPath = targetPath,
                ProcessingType = processingType
            }, cancellationToken);
        }
    }
}

Features

• Automatic Extension Generation: Creates strongly-typed extension methods
• Support for Default Values: Respects property initializers as default parameter values
• Required Properties: Handles required properties as mandatory parameters
• Custom Method Names: Use Method property in attribute to specify custom method names
• Null Safety: Full nullable reference type support
• IDE Integration: Full IntelliSense and compile-time checking

Attribute Options

ExtendDispatcherAttribute

• Method (optional): Specifies the name of the generated extension method. If not provided, uses the class name (removing "Command" suffix if present).

Requirements

• .NET Standard 2.0+ or .NET Core 2.0+ or .NET Framework 4.6.1+
• C# 8.0+ for nullable reference types support

Examples

Basic Command

[ExtendDispatcher]
public class SendEmail
{
    public required string To { get; set; }
    public required string Subject { get; set; }
    public required string Body { get; set; }
}

// Usage:
await dispatcher.SendEmail(
    to: "user@example.com",
    subject: "Hello",
    body: "Hello World!"
);

Command with Default Values

[ExtendDispatcher(Method = "ProcessOrder")]
public class ProcessOrderCommand
{
    public required int OrderId { get; set; }
    public bool HighPriority { get; set; } = false;
    public string ProcessingMode { get; set; } = "Standard";
}

// Usage:
await dispatcher.ProcessOrder(orderId: 123); // Uses defaults
await dispatcher.ProcessOrder(orderId: 123, highPriority: true); // Override defaults

Complex Properties

[ExtendDispatcher]
public class CreateUser
{
    public required string Email { get; set; }
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
    public List<string> Roles { get; set; } = new();
    public DateTime? LastLoginDate { get; set; }
}

// Usage:
await dispatcher.CreateUser(
    email: "john@example.com",
    firstName: "John",
    lastName: "Doe",
    roles: new List<string> { "User", "Admin" },
    lastLoginDate: DateTime.Now
);

Troubleshooting

Generated files not appearing

1. Clean and rebuild your solution
2. Ensure the package is properly installed
3. Check that your command classes are marked with [ExtendDispatcher]
4. Verify that command classes have public properties with public getters and setters

Compilation errors

1. Ensure you're using Sencilla.Messaging.Extensions namespace
2. Check that all required properties are provided as parameters
3. Verify that the IMessageDispatcher interface is properly referenced

License

This package is licensed under the MIT License. { ImageId = imageId, }, cancellationToken); } }

## Complex Example

```csharp
[GenerateMessageDispatcherExtension(MethodName = "ProcessOrderImage")]
public class ProcessImageCommand
{
    public int OrderId { get; set; }
    public string FilePath { get; set; } = string.Empty;
    public int Width { get; set; }
    public int Height { get; set; }
    public double Quality { get; set; }
    public DateTime Deadline { get; set; }
    public bool IsUrgent { get; set; }
}

This generates:

public static Task ProcessOrderImage(this IMessageDispatcher dispatcher, 
    int orderId, 
    string filePath, 
    int width, 
    int height, 
    double quality, 
    DateTime deadline, 
    bool isUrgent, 
    CancellationToken cancellationToken = default)
{
    return dispatcher.Send(new ProcessImageCommand
    {
        OrderId = orderId,
        FilePath = filePath,
        Width = width,
        Height = height,
        Quality = quality,
        Deadline = deadline,
        IsUrgent = isUrgent,
    }, cancellationToken);
}

Features

• ✅ Automatic method name generation: Uses class name by default, removes "Command" suffix
• ✅ Custom method names: Use MethodName parameter in the attribute
• ✅ Type-safe parameters: All properties become method parameters with correct types
• ✅ Parameter name conversion: PascalCase properties become camelCase parameters
• ✅ Documentation generation: Automatic XML documentation for generated methods
• ✅ Cancellation token support: All generated methods include optional CancellationToken
• ✅ Multiple commands: Generate extensions for multiple command classes in the same project

Requirements

• The command class must have public properties with public getters and setters
• The class must be marked with [GenerateMessageDispatcherExtension] attribute
• The project must reference the Sencilla.Messaging.SourceGenerators project as an Analyzer

Installation

Add the source generator project reference to your project file:

<ItemGroup>
  <ProjectReference Include="../../libs/SourceGenerator/Sencilla.Messaging.SourceGenerators.csproj" 
                    OutputItemType="Analyzer" 
                    ReferenceOutputAssembly="true" />
</ItemGroup>