Przejdź do treści

TailoredApps.Shared.Mediator.Email

NuGet License: MIT


Opis

Integracja wysyłania emaili z pipeline'em mediatora. Biblioteka dostarcza command SendMail oraz jego handler SendMailCommandHandler, dzięki czemu wysyłka emaila staje się naturalną częścią architektury CQRS — możesz wysłać email przez _mediator.Send(new SendMail { ... }) bez bezpośredniej zależności od IEmailProvider.

To podejście umożliwia łatwe wzbogacenie procesu wysyłki o logowanie, retry i auditing z poziomu pipeline behaviors, bez modyfikowania handlera.


Instalacja

dotnet add package TailoredApps.Shared.Mediator.Email

Rejestracja w DI

// Program.cs
using TailoredApps.Shared.Email;
using TailoredApps.Shared.Mediator.Email.Handlers;
using TailoredApps.Shared.Email.MailMessageBuilder;

// 1. Zarejestruj email provider (SMTP lub konsola)
builder.Services.RegisterSmtpProvider();

// 2. Zarejestruj mail message builder
builder.Services.AddTransient<IMailMessageBuilder, TokenReplacingMailMessageBuilder>();
builder.Services.Configure<TokenReplacingMailMessageBuilderOptions>(o =>
{
    o.Location = "EmailTemplates/";
    o.FileExtension = "html";
});

// 3. Mediator: przeskanuj także assembly biblioteki — tam znajduje się SendMailCommandHandler
builder.Services.AddMediator(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.RegisterServicesFromAssembly(typeof(SendMailCommandHandler).Assembly);
});

Pakiet nie ma własnej metody rejestrującej. Mediator rozwiązuje handler jako IRequestHandler<SendMail, SendMailResponse>, więc rejestracja SendMailCommandHandler wyłącznie pod ISendMailCommandHandler nie wystarczy, żeby _mediator.Send(new SendMail { ... }) go znalazł. Przeskanuj assembly biblioteki jak wyżej albo samodzielnie zarejestruj handler pod interfejsem mediatora:

builder.Services.AddTransient<IRequestHandler<SendMail, SendMailResponse>, SendMailCommandHandler>();

W aplikacji trimowanej lub publikowanej z NativeAOT skanowanie nie jest dostępne — handler rejestruje się po nazwie:

builder.Services.AddMediator(cfg =>
    cfg.AddRequestHandler<SendMail, SendMailResponse, SendMailCommandHandler>());

Biblioteka jest zgodna z NativeAOT razem z providerem SMTP i konsolowym z TailoredApps.Shared.Email; provider Email.Office365 nie jest. Pozostałe zasady: Mediator: Trimming i NativeAOT.


Przykład użycia

using TailoredApps.Shared.Mediator.Email.Messages.Commands;

public class UserRegistrationService
{
    private readonly IMediator _mediator;

    public UserRegistrationService(IMediator mediator) => _mediator = mediator;

    public async Task RegisterUserAsync(string email, string userName)
    {
        // Logika rejestracji...

        // Wyślij email powitalny przez pipeline mediatora
        var result = await _mediator.Send(new SendMail
        {
            Recipent = email,
            Subject = "Witaj w naszym serwisie!",
            Template = "welcome.html",
            TemplateVariables = new Dictionary<string, string>
            {
                { "UserName", userName },
                { "ActivationUrl", $"https://app.example.com/activate/{Guid.NewGuid()}" }
            },
            Attachments = null
        });

        Console.WriteLine($"Email wysłany, MessageId: {result.MessageId}");
    }

    public async Task SendInvoiceAsync(
        string email,
        string invoiceNumber,
        byte[] pdfContent)
    {
        await _mediator.Send(new SendMail
        {
            Recipent = email,
            Subject = $"Faktura #{invoiceNumber}",
            Template = "invoice.html",
            TemplateVariables = new Dictionary<string, string>
            {
                { "InvoiceNumber", invoiceNumber }
            },
            Attachments = new Dictionary<string, byte[]>
            {
                { $"faktura_{invoiceNumber}.pdf", pdfContent }
            }
        });
    }
}

API Reference

Typ Rodzaj Opis
SendMail Command (IRequest<SendMailResponse>) Dane emaila: Recipent, Subject, Template, TemplateVariables, Templates, Attachments
SendMailResponse Klasa Wynik wysyłki: MessageId (provider-specific identifier)
SendMailCommandHandler Handler Buduje treść z szablonu i wysyła przez IEmailProvider
ISendMailCommandHandler Interfejs Kontrakt handlera

🤖 AI Agent Prompt

## TailoredApps.Shared.Mediator.Email — Instrukcja dla agenta AI

Używasz TailoredApps.Shared.Mediator.Email do wysyłania emaili przez pipeline mediatora.

### Rejestracja
```csharp
builder.Services.RegisterSmtpProvider(); // lub RegisterConsoleProvider()
builder.Services.AddTransient<IMailMessageBuilder, TokenReplacingMailMessageBuilder>();
builder.Services.AddMediator(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.RegisterServicesFromAssembly(typeof(SendMailCommandHandler).Assembly); // handler SendMail
});
```

### Wysyłanie emaila
```csharp
var result = await _mediator.Send(new SendMail
{
    Recipent = "user@example.com",
    Subject = "Temat",
    Template = "template.html",           // nazwa pliku szablonu
    TemplateVariables = new() { { "Name", "Jan" } },
    Attachments = null                     // lub Dictionary<string, byte[]>
});
// result.MessageId — ID przypisany przez provider
```

### Zasady
- Mediator musi znaleźć handler jako IRequestHandler<SendMail, SendMailResponse>: przeskanuj assembly biblioteki; sama rejestracja jako ISendMailCommandHandler nie wystarczy
- Template i Recipent są wymagane — handler rzuca ArgumentException, gdy któreś jest null
- Template to klucz szablonu przekazywany do IMailMessageBuilder.Build()
- TemplateVariables zastępują {{token}} w szablonie
- Podaj Templates (Dictionary<string,string>) gdy szablony są inline, nie z pliku
- SendMail rzuci jeśli template nie zostanie znaleziony w IMailMessageBuilder
- Aplikacja z PublishAot: zamiast skanowania cfg.AddRequestHandler<SendMail, SendMailResponse, SendMailCommandHandler>(); provider Email.Office365 nie jest zgodny z NativeAOT