SquareLabs.OracleAQ.Extensions 1.0.0

Oracle AQ Extensions for .NET

Uma biblioteca .NET leve e resiliente para criar listeners (Hosted Services) para o Oracle Advanced Queuing (AQ). Integra-se com injeção de dependência para descobrir e gerenciar seus processadores de mensagens de forma automática, com lógica de reconexão e mapeamento de UDTs embutidos.

🤔 Por que usar esta biblioteca?

Interagir com o Oracle Advanced Queuing em uma aplicação .NET moderna pode ser verboso e complexo, especialmente ao tentar criar serviços de background robustos e resilientes. Esta biblioteca abstrai toda a complexidade de gerenciamento de conexões, transações de fila, mapeamento de objetos e descoberta de serviços, permitindo que você foque no que realmente importa: a sua lógica de negócio.

✨ Principais Recursos

• 🚀 Descoberta Automática: Apenas implemente a interface IOracleAQListener<T> e a biblioteca irá descobrir, registrar e executar seu listener automaticamente.
• 🔌 Integração com DI: Desenhado desde o início para funcionar perfeitamente com o container de injeção de dependência do .NET. Injete qualquer serviço (como um DbContext do EF Core ou um IHubContext do SignalR) em seus listeners.
• 💪 Resiliência Embutida: O serviço de escuta lida automaticamente com perdas de conexão com o Oracle, esperando um tempo e tentando se reconectar, garantindo que sua aplicação continue funcionando.
• 🔄 Mapeamento de UDT: Mapeie os User-Defined Types (UDT) do Oracle para classes C# (POCOs) de forma limpa e declarativa usando atributos.
• 🏗️ Arquitetura Limpa: Construído com os princípios da Clean Architecture para garantir um código desacoplado, testável e de fácil manutenção.
• 🕊️ Leve e Sem Dependências Externas: Além do driver oficial da Oracle, a biblioteca não adiciona dependências desnecessárias ao seu projeto.

📚 Documentação e Guia de Início Rápido

📦 Instalação

A instalação é feita através do gerenciador de pacotes NuGet:

dotnet add package SquareLabs.OracleAQ.Extensions

🔧 Configuração do Mapeamento UDT

Primeiro, você precisa criar uma factory para o seu tipo UDT do Oracle. Esta classe implementa as interfaces necessárias do driver Oracle:

using Oracle.ManagedDataAccess.Client;
using Oracle.ManagedDataAccess.Types;

public class PedidoUdtFactory : IOracleCustomType, IOracleCustomTypeFactory
{
    // Implementação da factory para mapear o UDT Oracle para a classe C#
    [OracleObjectMapping("ID")]
    public decimal? Id { get; set; }

    [OracleObjectMapping("DESCRICAO")]
    public string? Descricao { get; set; }

    [OracleObjectMapping("VALOR")]
    public decimal? Valor { get; set; }

    public IOracleCustomType CreateObject()
    {
        return new PedidoUdtFactory();
    }

    public void FromCustomObject(OracleConnection con, object udt)
    {
        if (udt is PedidoDto pedido)
        {
            Id = pedido.Id;
            Descricao = pedido.Descricao;
            Valor = pedido.Valor;
        }
    }

    public void ToCustomObject(OracleConnection con, object udt)
    {
        // Conversão do UDT Oracle para o objeto customizado
    }
}

📝 Definição da Mensagem (DTO)

Crie uma classe C# que representa sua mensagem, usando os atributos de mapeamento:

using SquareLabs.OracleAQ.Extensions.Domain.Attributes;

public class PedidoDto
{
    [OracleUdtProperty("ID")]
    public decimal? Id { get; set; }

    [OracleUdtProperty("DESCRICAO")]
    public string? Descricao { get; set; }

    [OracleUdtProperty("VALOR")]
    public decimal? Valor { get; set; }
}

🎯 Implementação do Listener

Implemente a interface IOracleAQListener<T> para processar as mensagens:

using Microsoft.Extensions.Logging;
using SquareLabs.OracleAQ.Extensions.Domain.Interfaces;

public class PedidoListener : IOracleAQListener<PedidoDto>
{
    private readonly ILogger<PedidoListener> _logger;
    private readonly IPedidoService _pedidoService;

    public PedidoListener(ILogger<PedidoListener> logger, IPedidoService pedidoService)
    {
        _logger = logger;
        _pedidoService = pedidoService;
    }

    public string QueueName => "PEDIDOS_QUEUE";

    public async Task ProcessMessageAsync(PedidoDto message, CancellationToken cancellationToken)
    {
        _logger.LogInformation("Processando pedido {PedidoId}", message.Id);
        
        try
        {
            await _pedidoService.ProcessarPedidoAsync(message, cancellationToken);
            _logger.LogInformation("Pedido {PedidoId} processado com sucesso", message.Id);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Erro ao processar pedido {PedidoId}", message.Id);
            throw; // Re-throw para que a mensagem seja colocada de volta na fila
        }
    }
}

⚙️ Registro no Program.cs

Configure a biblioteca no seu Program.cs:

using SquareLabs.OracleAQ.Extensions.Infrastructure;

var builder = WebApplication.CreateBuilder(args);

// Registrar seus serviços de negócio
builder.Services.AddScoped<IPedidoService, PedidoService>();

// Registrar os listeners Oracle AQ
builder.Services.AddOracleAQListeners(options =>
{
    options.ConnectionStringName = "OracleConnection";
    
    // Configurar o mapeamento UDT
    options.RegisterQueueUdt("PEDIDOS_QUEUE", "PEDIDO_UDT");
    
    // NOVO: Para Oracle 10g, habilite o modo de compatibilidade
    // options.UseOracle10gCompatibilityMode = true;
});

var app = builder.Build();

// Configure o pipeline HTTP...

app.Run();

E no seu appsettings.json:

{
  "ConnectionStrings": {
    "OracleConnection": "Data Source=localhost:1521/XE;User Id=seu_usuario;Password=sua_senha;"
  }
}

🔧 Compatibilidade

.NET Framework

• .NET 6+ (suporte oficial)
• .NET Core 3.1+ (compatível)
• .NET Framework 4.8+ (compatível)

Banco de Dados Oracle

• Oracle 19c e superiores (suporte oficial do driver Oracle)
• Oracle 12c+ (testado e funcional)
• Oracle 11g (compatível, mas não oficialmente suportado pelo driver Oracle)
• Oracle 10g (compatível com modo de compatibilidade habilitado - veja seção abaixo)

Nota: Embora a biblioteca funcione com versões legadas como Oracle 11g e 10g, recomendamos usar Oracle 19c ou superior para melhor suporte e recursos de segurança.

🔧 Compatibilidade com Oracle 10g

Se você estiver usando Oracle 10g e encontrar o erro:

ORA-06550: linha 1, coluna 13:
PLS-00306: número incorreto de tipos de argumentos na chamada para 'GET_TYPE_SHAPE'

Habilite o modo de compatibilidade Oracle 10g:

services.AddOracleAQListeners(options =>
{
    options.ConnectionStringName = "OracleConnection";
    options.RegisterQueueUdt("SUA_FILA", "SEU_TIPO_UDT");
    
    // Habilita modo de compatibilidade com Oracle 10g
    options.UseOracle10gCompatibilityMode = true;
});

Este modo implementa estratégias de fallback específicas para contornar limitações do Oracle 10g com funções mais recentes do driver Oracle.

📖 Guia Completo Oracle 10g | Exemplo Prático

🤝 Como Contribuir

Contribuições são muito bem-vindas! Para contribuir com o projeto:

📋 Processo de Contribuição

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/minha-nova-feature)
3. Commit suas mudanças (git commit -am 'feat: adiciona nova feature')
4. Push para a branch (git push origin feature/minha-nova-feature)
5. Abra um Pull Request

📝 Commits Semânticos

Este projeto usa Commits Semânticos. Use os seguintes tipos:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Alterações na documentação
• style: Formatação, ponto e vírgula ausente, etc
• refactor: Refatoração de código
• test: Adição ou correção de testes
• chore: Manutenção, build, dependências

Exemplo: feat: adiciona suporte para múltiplas connection strings

👨‍💻 Autor e Licença

Autor: Rômulo Eduardo (@romuloedu)

Licença: MIT License

🌟 Apoie o Projeto

Se esta biblioteca foi útil para você, considere dar uma estrela ⭐ no repositório do GitHub! Isso ajuda outros desenvolvedores a descobrirem o projeto e motiva a continuidade do desenvolvimento.

⭐ Dar uma estrela no GitHub