CodeDesignPlus.Net.ServiceBus.Abstractions 1.0.0-beta.13054

CodeDesignPlus.Net.ServiceBus

Description

CodeDesignPlus.Net.ServiceBus implementa el contrato de publicación y suscripción del SDK sobre Azure Service Bus. Es un transporte alternativo a CodeDesignPlus.Net.RabbitMQ: los handlers, los eventos de dominio y los atributos EventKey y QueueName no cambian, solo cambia por dónde viajan los mensajes.

Tabla de contenido

• Sobre el proyecto
• Cómo se traduce el modelo de RabbitMQ
• Instalación
• Uso
• Autenticación
• Reintentos y dead-letter
• Pruebas
• Límites que conviene conocer
• Contributing
• License
• Contact

Sobre el proyecto

La librería implementa IMessage de CodeDesignPlus.Net.PubSub. Todo lo que rodea al transporte —el descubrimiento de handlers, los servicios en segundo plano que abren las suscripciones, el seguimiento de cuáles están listas y la cola en memoria opcional— lo sigue aportando CodeDesignPlus.Net.PubSub sin cambios.

Cómo se traduce el modelo de RabbitMQ

El nombre del topic es el mismo que el del exchange, así que el inventario de eventos no cambia. El nombre de la suscripción sí: Azure lo limita a 50 caracteres y casi todos los nombres de cola actuales los superan. La librería lo resuelve sola, sin tocar los [QueueName]:

subscription = "{appName}.{action}"                  si cabe en 50
             = prefijo[41] + "-" + sha256(logico)[8] si no cabe

El resumen se calcula sobre el nombre lógico completo (negocio, versión y entidad incluidos), de modo que dos handlers cuyo prefijo coincide tras el recorte siguen resolviendo a suscripciones distintas.

Instalación

dotnet add package CodeDesignPlus.Net.ServiceBus

Uso

builder.Services.AddServiceBus<Program>(builder.Configuration);

{
  "Core": { "AppName": "ms-invoicing", "Business": "kappali", "Version": "v1" },
  "ServiceBus": {
    "Enable": true,
    "FullyQualifiedNamespace": "sb-kappali-stg.servicebus.windows.net",
    "UseQueue": false,
    "EnableDiagnostic": true
  }
}

Autenticación

Por defecto se usa DefaultAzureCredential contra FullyQualifiedNamespace, lo que en AKS se traduce en Workload Identity. La identidad necesita el rol Azure Service Bus Data Owner, porque AutoProvisionEntities crea entidades; con las entidades ya creadas y AutoProvisionEntities en false bastan Data Sender y Data Receiver.

ConnectionString existe para el desarrollo local y el emulador, que no admiten Entra ID.

Reintentos y dead-letter

error de negocio (CodeDesignPlusException)  ->  DLQ inmediata, motivo "BusinessError"
error de infraestructura, quedan reintentos ->  espera creciente y AbandonMessageAsync
error de infraestructura, agotados          ->  DLQ, motivo "MaxRetriesExceeded"

La espera crece de forma exponencial desde RetryIntervalMs hasta MaxRetryIntervalMs, con una dispersión de hasta el 20% para que varias réplicas que fallaron a la vez no reintenten a la vez. Transcurre en proceso, con el bloqueo del mensaje retenido y renovándose solo. La alternativa —completar el mensaje y reprogramar una copia— libera el bloqueo antes, pero completar y reprogramar no son operaciones atómicas y una caída entre ambas pierde el evento.

La suscripción se crea con MaxDeliveryCount = MaxRetry + 1: decide primero el consumidor, que es quien sabe distinguir un error de negocio, y el broker queda como red de seguridad para el caso de que el proceso muera antes de decidir.

Pruebas

Las pruebas de integración usan el emulador oficial (mcr.microsoft.com/azure-messaging/servicebus-emulator más su SQL Server), levantado por ServiceBusCollectionFixture de CodeDesignPlus.Net.xUnit.

El emulador impone topes que Azure no tiene y que obligan a bajar los valores de producción en las pruebas:

Límites que conviene conocer

• 256 KB por mensaje en el nivel Standard, propiedades incluidas. La librería comprueba el tamaño antes de enviar y lanza un ServiceBusPubSubException que nombra el evento y su tamaño.
• 1.000 operaciones por segundo por namespace en Standard.
• Un mensaje publicado en un topic con N suscripciones son N entregas facturables.
• 10.000 topics por namespace y 2.000 suscripciones por topic.

Contributing

Please read CONTRIBUTING for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

CodeDesignPlus - @CodeDesignPlus - custom.software@codedesignplus.com