Nosabit.Adapters.Persistence.Mail.Abstractions 1.2.4

Nosabit.Adapters.Persistence.Mail.Abstractions

Biblioteca de abstracciones para servicios de correo electrónico en aplicaciones .NET. Define interfaces para facilitar la creación y el envío de correos electrónicos con soporte para múltiples configuraciones.

Instalación

Package Manager

Install-Package Nosabit.Adapters.Persistence.Mail.Abstractions

.NET CLI

dotnet add package Nosabit.Adapters.Persistence.Mail.Abstractions

Características principales

• Abstracciones para servicios de correo: Define interfaces para el envío de correos electrónicos
• Configuración basada en claves: Permite tener múltiples configuraciones de correo que pueden ser seleccionadas mediante enumeraciones
• Flexibilidad en los destinatarios: Soporta envío a destinatarios individuales o múltiples
• Soporte para copias (CC): Permite enviar copias a otros destinatarios
• Gestión de adjuntos: Facilita la inclusión de archivos adjuntos en los correos
• Personalización de asunto y cuerpo HTML: Define parámetros para personalizar el contenido

Interfaces principales

La biblioteca define la siguiente interfaz principal:

IMailService

public interface IMailService
{
    /// <summary>
    /// Crea un cliente SMTP usando una configuración específica
    /// </summary>
    /// <param name="KeyMail">Enumeración opcional que especifica qué configuración usar</param>
    /// <returns>Un cliente SMTP configurado</returns>
    SmtpClient CreateClientCorreo(Enum? KeyMail = null);
    
    /// <summary>
    /// Crea un mensaje de correo usando una configuración específica
    /// </summary>
    /// <param name="KeyMail">Enumeración opcional que especifica qué configuración usar</param>
    /// <returns>Un mensaje de correo electrónico</returns>
    MailMessage CreateMailMessage(Enum? KeyMail = null);
    
    /// <summary>
    /// Envía un correo electrónico a múltiples destinatarios
    /// </summary>
    /// <param name="Asunto">Asunto del correo</param>
    /// <param name="CuerpoCorreo">Contenido HTML del correo</param>
    /// <param name="DestinarioEmail">Array de direcciones de destinatarios</param>
    /// <param name="CopyEmail">Array opcional de direcciones en copia</param>
    /// <param name="attachments">Lista opcional de archivos adjuntos</param>
    /// <param name="UseMail">Enumeración opcional que especifica qué configuración usar</param>
    /// <returns>True si el envío fue exitoso</returns>
    bool Enviar(
        string Asunto, 
        string CuerpoCorreo, 
        MailAddress[] DestinarioEmail, 
        MailAddress[]? CopyEmail = null, 
        List<Attachment>? attachments = null, 
        Enum? UseMail = null
    );
    
    /// <summary>
    /// Envía un correo electrónico a un destinatario
    /// </summary>
    /// <param name="Asunto">Asunto del correo</param>
    /// <param name="CuerpoCorreo">Contenido HTML del correo</param>
    /// <param name="DestinarioEmail">Dirección del destinatario como string</param>
    /// <param name="CopyEmail">Dirección opcional de copia como string</param>
    /// <param name="attachments">Lista opcional de archivos adjuntos</param>
    /// <param name="UseMail">Enumeración opcional que especifica qué configuración usar</param>
    /// <returns>True si el envío fue exitoso</returns>
    bool Enviar(
        string Asunto, 
        string CuerpoCorreo, 
        string DestinarioEmail, 
        string? CopyEmail = null, 
        List<Attachment>? attachments = null, 
        Enum? UseMail = null
    );
}

Configuración

Para implementar esta interfaz, se requiere una estructura de configuración que defina las diferentes opciones de correo. A continuación se muestra un ejemplo de la estructura de configuración esperada:

// Clase de configuración para las opciones de correo
public class AppConfigCorreoConfiguration
{
    public string? Email { get; set; }
    public string? Password { get; set; }
    public string? EmailFake { get; set; }
    public string? EmailName { get; set; }
    public string? SmtpServer { get; set; }
    public int? SmtpPort { get; set; }
    public string? SmtpTargetName { get; set; }
}

La implementación esperada utilizará un diccionario de configuraciones a través de IOptions<IDictionary<string, AppConfigCorreoConfiguration>>, donde la clave del diccionario corresponde al nombre de la enumeración utilizada para seleccionar la configuración.

Uso de las abstracciones

Este paquete contiene solo la interfaz y no la implementación. Para utilizarlo, sigue estos pasos:

1. Definir tus configuraciones en appsettings.json

{
  "EmailOptions": {
    "default": {
      "Email": "usuario@tudominio.com",
      "Password": "tu-contraseña",
      "EmailFake": "no-reply@tudominio.com",
      "EmailName": "Tu Nombre de Empresa",
      "SmtpServer": "smtp.tudominio.com",
      "SmtpPort": 587,
      "SmtpTargetName": "STARTTLS/smtp.tudominio.com"
    },
    "support": {
      "Email": "soporte@tudominio.com",
      "Password": "otra-contraseña",
      "EmailFake": "soporte@tudominio.com",
      "EmailName": "Soporte Técnico",
      "SmtpServer": "smtp.tudominio.com",
      "SmtpPort": 587,
      "SmtpTargetName": "STARTTLS/smtp.tudominio.com"
    }
  }
}

2. Configurar los servicios en Program.cs

// En Program.cs
var builder = WebApplication.CreateBuilder(args);

// Configurar las opciones de correo
builder.Services.Configure<Dictionary<string, AppConfigCorreoConfiguration>>(
    builder.Configuration.GetSection("EmailOptions")
);

// Registrar el servicio de correo
builder.Services.AddScoped<IMailService, YourMailServiceImplementation>();

3. Definir enumeración para tus configuraciones

// Define tus configuraciones como enum para facilitar el uso
public enum EmailConfig
{
    default,
    support
}

4. Utilizar el servicio en tu aplicación

public class NotificationService
{
    private readonly IMailService _mailService;
    
    public NotificationService(IMailService mailService)
    {
        _mailService = mailService;
    }
    
    public bool SendSupportTicketNotification(string userEmail, string ticketId, string description)
    {
        string subject = $"Nuevo ticket de soporte #{ticketId}";
        string body = $@"
            <html>
            <body>
                <h2>Nuevo ticket de soporte creado</h2>
                <p>Se ha registrado su solicitud con el ID: <strong>{ticketId}</strong></p>
                <p>Descripción: {description}</p>
                <p>Nos pondremos en contacto con usted a la brevedad.</p>
            </body>
            </html>";
            
        return _mailService.Enviar(
            subject,
            body,
            userEmail,
            UseMail: EmailConfig.support
        );
    }
    
    public bool SendMultipleNotification(List<string> emails, string subject, string htmlContent)
    {
        var recipients = emails.Select(email => new MailAddress(email)).ToArray();
        
        return _mailService.Enviar(
            subject,
            htmlContent,
            recipients,
            UseMail: EmailConfig.default
        );
    }
    
    public bool SendReportWithAttachment(string email, string reportName, byte[] reportContent)
    {
        using var ms = new MemoryStream(reportContent);
        var attachment = new Attachment(ms, $"{reportName}.pdf", "application/pdf");
        var attachments = new List<Attachment> { attachment };
        
        return _mailService.Enviar(
            $"Su reporte: {reportName}",
            "<p>Adjunto encontrará el reporte solicitado.</p>",
            email,
            attachments: attachments,
            UseMail: EmailConfig.default
        );
    }
}

Implementación esperada

La implementación de esta interfaz debería:

1. Recibir una configuración a través de IOptions<IDictionary<string, AppConfigCorreoConfiguration>>
2. Permitir seleccionar una configuración específica mediante un valor de enumeración
3. Crear clientes SMTP configurados según los parámetros especificados
4. Crear mensajes de correo con el remitente adecuado
5. Manejar el envío de correos con adjuntos y copias

Beneficios de utilizar estas abstracciones

• Múltiples configuraciones: Permite tener diferentes configuraciones de correo en una sola aplicación
• Selección dinámica: Usa enumeraciones para seleccionar qué configuración utilizar en cada envío
• Separación de responsabilidades: Desacopla la lógica de envío de correos de la lógica de negocio
• Testabilidad: Facilita la creación de mocks para pruebas unitarias

Integración con otros paquetes Nosabit

Este paquete de abstracciones está diseñado para trabajar con otros paquetes de la familia Nosabit:

• Nosabit.Core: Proporciona extensiones útiles como HasValue()
• Nosabit.Adapters.Persistence.Mail: Implementación concreta de estas abstracciones

Requisitos

• .NET 6.0 o superior
• System.Net.Mail (incluido en .NET Framework)