SSA.DRetiro.MQManager 1.0.0

SSA.DRetiro.MQManager

Librería para consumo de IBM MQ desarrollada para el proyecto SSA.DRetiro.Cuentas. Proporciona una abstracción simplificada y moderna para trabajar con IBM MQ, con soporte para múltiples servidores, publicación/suscripción de mensajes y manejo automático de handlers.

📋 Tabla de Contenidos

• Características
• Instalación
• Configuración
• Uso
  • Publicación de Mensajes
  • Consumo de Mensajes
• Arquitectura
• Ejemplos Completos
• Requisitos
• Licencia

✨ Características

• 🌐 Soporte Multi-Servidor: Conexión y gestión de múltiples servidores IBM MQ simultáneamente
• 📨 Publicación de Mensajes: Envío de mensajes a colas y topics con soporte genérico
• 📥 Consumo Automático: Sistema de handlers que se suscriben automáticamente a colas y topics
• 🔧 Configuración Flexible: Uso del patrón Options para configuración mediante appsettings.json
• 🔄 Servicio en Background: Servicio hospedado que mantiene las suscripciones activas
• 🎯 Tipo Seguro: Uso de genéricos para manejo de mensajes con tipos específicos
• 📝 Logging Integrado: Integración completa con Microsoft.Extensions.Logging
• 🏗️ Inyección de Dependencias: Totalmente compatible con el contenedor DI de .NET

📦 Instalación

dotnet add package SSA.DRetiro.MQManager

⚙️ Configuración

1. Configuración en appsettings.json

Agrega la configuración de tus servidores IBM MQ en appsettings.json:

{
  "MqConfigMultiple": {
    "DefaultServer": "default",
    "Servers": {
      "default": {
        "QueueManager": "QM1",
        "HostName": "localhost",
        "Port": 1414,
        "Channel": "DEV.APP.SVRCONN",
        "Username": "mquser",
        "Password": "mqpass",
        "UseSsl": false,
        "SemaphoreTimeout": 30000,
        "MaxConcurrentConsumers": 5
      },
      "secondary": {
        "QueueManager": "QM2",
        "HostName": "mq-server-2.company.com",
        "Port": 1414,
        "Channel": "PROD.APP.SVRCONN",
        "Username": "mquser",
        "Password": "mqpass",
        "UseSsl": true,
        "SemaphoreTimeout": 30000,
        "MaxConcurrentConsumers": 10
      }
    }
  }
}

Parámetros de Configuración

2. Registro de Servicios

En tu archivo Program.cs o Startup.cs:

using SSA.DRetiro.MQManager;

var builder = WebApplication.CreateBuilder(args);

// Registrar servicios de MQ
builder.Services.AddMQServices(builder.Configuration);

var app = builder.Build();

Esto registrará automáticamente:

• IMqServiceFactory: Factory para obtener servicios MQ por servidor
• IMqPublishService: Servicio para publicación de mensajes
• MessageHandlerSubscriptionService: Servicio en background para suscripciones automáticas

🚀 Uso

Publicación de Mensajes

Publicar a una Cola

public class MyService
{
    private readonly IMqPublishService _mqPublishService;
    
    public MyService(IMqPublishService mqPublishService)
    {
        _mqPublishService = mqPublishService;
    }
    
    public async Task SendMessageAsync()
    {
        var myMessage = new MyMessage
        {
            Id = Guid.NewGuid(),
            Content = "Hello IBM MQ!"
        };
        
        // Enviar al servidor por defecto
        await _mqPublishService.PublishToQueueAsync(
            queueName: "DEV.QUEUE.1",
            message: myMessage
        );
        
        // Enviar a un servidor específico
        await _mqPublishService.PublishToQueueAsync(
            queueName: "PROD.QUEUE.1",
            message: myMessage,
            serverName: "secondary"
        );
    }
}

Publicar a un Topic

public async Task PublishEventAsync()
{
    var eventData = new OrderCreatedEvent
    {
        OrderId = 12345,
        CreatedAt = DateTime.UtcNow
    };
    
    var success = await _mqPublishService.PublishToTopicAsync(
        message: eventData,
        topic: "orders/created",
        serverName: "default" // Opcional
    );
    
    if (success)
    {
        Console.WriteLine("Evento publicado exitosamente");
    }
}

Consumo de Mensajes

1. Crear un Handler para Cola

Implementa la interfaz IQueueMessageHandler<T>:

using SSA.DRetiro.MQManager.Hanlder;

public class OrderQueueHandler : IQueueMessageHandler<OrderMessage>
{
    private readonly ILogger<OrderQueueHandler> _logger;
    
    public OrderQueueHandler(ILogger<OrderQueueHandler> logger)
    {
        _logger = logger;
    }
    
    // Nombre de la cola a consumir
    public string QueueName => "DEV.QUEUE.ORDERS";
    
    // Servidor MQ (null = servidor por defecto)
    public string ServerName => "default";
    
    // Lógica de procesamiento del mensaje
    public async Task HandleAsync(OrderMessage message, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Processing order: {OrderId}", message.OrderId);
        
        // Tu lógica de negocio aquí
        await ProcessOrderAsync(message);
        
        _logger.LogInformation("Order processed successfully: {OrderId}", message.OrderId);
    }
    
    private async Task ProcessOrderAsync(OrderMessage message)
    {
        // Implementación...
        await Task.CompletedTask;
    }
}

2. Crear un Handler para Topic

Implementa la interfaz ITopicMessageHandler<T>:

using SSA.DRetiro.MQManager.Hanlder;

public class OrderEventHandler : ITopicMessageHandler<OrderCreatedEvent>
{
    private readonly ILogger<OrderEventHandler> _logger;
    
    public OrderEventHandler(ILogger<OrderEventHandler> logger)
    {
        _logger = logger;
    }
    
    // Nombre del topic a suscribirse
    public string TopicName => "orders/created";
    
    // Servidor MQ (null = servidor por defecto)
    public string ServerName => null;
    
    // Lógica de procesamiento del evento
    public async Task HandleAsync(OrderCreatedEvent message, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Received order created event: {OrderId}", message.OrderId);
        
        // Tu lógica de negocio aquí
        await NotifyCustomerAsync(message);
    }
    
    private async Task NotifyCustomerAsync(OrderCreatedEvent evt)
    {
        // Implementación...
        await Task.CompletedTask;
    }
}

3. Registrar los Handlers

En tu Program.cs o clase de extensión de servicios:

// Registrar handlers como Transient
builder.Services.AddTransient<OrderQueueHandler>();
builder.Services.AddTransient<OrderEventHandler>();

Importante: Los handlers se descubren y suscriben automáticamente gracias al MessageHandlerSubscriptionService.

🏗️ Arquitectura

Componentes Principales

SSA.DRetiro.MQManager
├── Configuration
│   ├── MqConfiguration.cs              # Configuración individual de servidor
│   └── MqMultiServerConfiguration.cs   # Configuración multi-servidor
├── Handlers
│   └── IMessageHandlers.cs             # Interfaces para handlers
├── PublishService
│   ├── IMqPublishService.cs            # Interface de publicación
│   └── MqPublishService.cs             # Implementación de publicación
├── Services
│   ├── IMqServiceFactory.cs            # Factory de servicios MQ
│   └── MqServiceFactory.cs             # Implementación del factory
├── MessageHandlerSubscriptionService.cs # Servicio de suscripciones automáticas
└── ServiceRegistration.cs              # Registro de servicios DI

Flujo de Trabajo

1. Inicialización: El MessageHandlerSubscriptionService se ejecuta como servicio hospedado
2. Descubrimiento: Busca todos los handlers que implementan IQueueMessageHandler<T> o ITopicMessageHandler<T>
3. Suscripción: Suscribe automáticamente cada handler a su cola/topic correspondiente
4. Procesamiento: Los mensajes recibidos se deserializan y pasan al método HandleAsync del handler
5. Logging: Todas las operaciones se registran para monitoreo y debugging

📚 Ejemplos Completos

Ejemplo 1: Sistema de Procesamiento de Archivos

// Handler
public class FileProcessingHandler : IQueueMessageHandler<FileProcessingMessage>
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<FileProcessingHandler> _logger;
    
    public FileProcessingHandler(
        IServiceScopeFactory scopeFactory,
        ILogger<FileProcessingHandler> logger)
    {
        _scopeFactory = scopeFactory;
        _logger = logger;
    }
    
    public string QueueName => "FILES.PROCESSING.QUEUE";
    public string ServerName => "default";
    
    public async Task HandleAsync(FileProcessingMessage message, CancellationToken cancellationToken)
    {
        using var scope = _scopeFactory.CreateScope();
        var fileService = scope.ServiceProvider.GetRequiredService<IFileService>();
        
        await fileService.ProcessFileAsync(message.FilePath);
    }
}

// Registro
builder.Services.AddTransient<FileProcessingHandler>();
builder.Services.AddMQServices(builder.Configuration);

Ejemplo 2: Configuración con Múltiples Servidores

// appsettings.json
{
  "MqConfigMultiple": {
    "DefaultServer": "development",
    "Servers": {
      "development": {
        "QueueManager": "DEV.QM",
        "HostName": "dev-mq.company.local",
        "Port": 1414,
        "Channel": "DEV.SVRCONN"
      },
      "production": {
        "QueueManager": "PROD.QM",
        "HostName": "prod-mq.company.com",
        "Port": 1414,
        "Channel": "PROD.SVRCONN",
        "UseSsl": true
      }
    }
  }
}

// Uso
public class MultiServerService
{
    private readonly IMqPublishService _publishService;
    
    public async Task PublishToMultipleServersAsync(MyMessage message)
    {
        // Enviar a desarrollo
        await _publishService.PublishToQueueAsync(
            "DEV.QUEUE", 
            message, 
            serverName: "development"
        );
        
        // Enviar a producción
        await _publishService.PublishToQueueAsync(
            "PROD.QUEUE", 
            message, 
            serverName: "production"
        );
    }
}

🔧 Requisitos

• .NET 8.0 o superior
• IBM MQ Client 9.4.3 o superior
• Microsoft.Extensions.Configuration 9.0.3+
• Microsoft.Extensions.DependencyInjection 9.0.3+
• Microsoft.Extensions.Hosting 8.0.0+
• Microsoft.Extensions.Logging 9.0.3+
• Newtonsoft.Json 13.0.1+

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Ver el archivo LICENSE.txt para más detalles.

👨‍💻 Autor

Jose Carlos Vasquez
Sancor - 2026

🤝 Contribuciones

Para contribuir al proyecto, por favor contacta al equipo de desarrollo de Sancor.

📞 Soporte

Para problemas, preguntas o sugerencias, contacta al equipo de desarrollo interno.