Omnia.Utility 9.0.0

Omnia.Utility

Libreria di utility comuni per il framework Omnia, che fornisce classi e helper per sviluppare applicazioni ASP.NET Core con funzionalità avanzate.

Funzionalità

🔐 Autenticazione e Autorizzazione

• JWT Token Handling - Gestione completa dei token JWT
• Authentication Extensions - Extension methods per ASP.NET Core
• Authorization Utilities - Helper per politiche di autorizzazione

📁 Gestione File

• FileStatic - Utility per file statici
• FormFileUtility - Helper per upload e gestione FormFile
• File Controllers - Controller base per operazioni sui file

🛡️ Gestione Eccezioni

• Exception Handling Middleware - Middleware centralizzato per la gestione delle eccezioni
• Structured Error Responses - Risposte di errore strutturate e consistenti
• HTTP Status Mapping - Mapping automatico delle eccezioni ai codici HTTP appropriati

🗃️ Repository e Service Pattern

• Service Repository - Pattern base per servizi
• Generic Service - Implementazioni generiche riutilizzabili
• Standard Controller - Controller base con operazioni CRUD

📊 Paginazione e DTO

• Pagination Utilities - Sistema di paginazione completo
• QDTO (Query DTO) - Pattern per query complesse
• AutoMapper Integration - Profili di mapping automatico

📝 Logging e Monitoring

• Logger Utilities - Sistema di logging strutturato
• Mapping Profiles - Profili AutoMapper preconfigurati

Installazione

dotnet add package Omnia.Utility

Utilizzo Base

Configurazione in Program.cs

using Omnia.Utility;

var builder = WebApplication.CreateBuilder(args);

// Aggiungi servizi Omnia
builder.Services.AddOmniaUtilities();

var app = builder.Build();

Exception Handling Middleware

Il middleware centralizzato gestisce automaticamente tutte le eccezioni non gestite e le converte in risposte HTTP strutturate.

Configurazione

using Omnia.Utility.Extensions;

var app = builder.Build();

// Aggiungi il middleware per la gestione centralizzata delle eccezioni
// DEVE essere uno dei primi middleware nella pipeline
app.UseExceptionHandling();

// Altri middleware...
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

Eccezioni Gestite

Il middleware mapba automaticamente le eccezioni ai seguenti codici HTTP:

Formato della Risposta

Tutte le risposte di errore seguono questo formato:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Order PAYID-12345678 not found",
  "timestamp": "2026-01-09T10:30:45.123Z",
  "traceId": null
}

Esempio di Utilizzo

using PaymentPaypal.Interfaces;

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IPayPalOrderRepository _repository;

    public OrdersController(IPayPalOrderRepository repository)
    {
        _repository = repository;
    }

    [HttpGet("{orderId}")]
    public async Task<IActionResult> GetOrder(string orderId)
    {
        // Se orderId non esiste, il middleware catturerà KeyNotFoundException
        // e ritornerà 404 automaticamente
        var order = await _repository.GetOrderAsync(orderId);
        return Ok(order);
    }

    [HttpPost("capture/{orderId}")]
    public async Task<IActionResult> CaptureOrder(string orderId)
    {
        // Se lo stato non è APPROVED, sarà lanciata InvalidOperationException
        // che il middleware converte in 409 Conflict
        var result = await _repository.CaptureOrderAsync(orderId);
        return Ok(result);
    }
}

Logging

Il middleware registra automaticamente tutte le eccezioni non gestite usando ILogger<ExceptionHandlingMiddleware>. Puoi configurare il livello di logging nel appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Omnia.Utility.ExceptionHandling": "Error"
    }
  }
}

File Upload

public class MyController : ControllerBase
{
    [HttpPost("upload")]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        var result = await FormFileUtility.ProcessFileAsync(file);
        return Ok(result);
    }
}

Paginazione

public async Task<PagedResult<Product>> GetProducts(PaginationRequest request)
{
    return await _repository.GetPagedAsync(request);
}

JWT Authentication

// Configura JWT
builder.Services.AddJwtAuthentication(builder.Configuration);

// Nel controller
[Authorize]
public class SecureController : ControllerBase
{
    // Endpoint sicuri
}

Dipendenze

• AutoMapper - Mapping tra oggetti
• Microsoft.AspNetCore.Authentication.JwtBearer - Autenticazione JWT
• Newtonsoft.Json - Serializzazione JSON
• System.IdentityModel.Tokens.Jwt - Gestione token JWT

Compatibilità

• .NET 8.0 o superiore
• ASP.NET Core 8.0 o superiore
• Entity Framework Core (per repository pattern)

Esempio Completo

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Omnia.Utility;

[ApiController]
[Route("api/[controller]")]
public class ProductsController : StandardController<Product>
{
    private readonly IProductService _service;

    public ProductsController(IProductService service) : base(service)
    {
        _service = service;
    }

    [HttpGet("paged")]
    public async Task<IActionResult> GetPaged([FromQuery] PaginationRequest request)
    {
        var result = await _service.GetPagedAsync(request);
        return Ok(result);
    }

    [HttpPost("upload")]
    [Authorize]
    public async Task<IActionResult> UploadFile(IFormFile file)
    {
        var result = await FormFileUtility.ProcessFileAsync(file);
        return Ok(result);
    }
}

Contribuire

1. Fork del repository
2. Crea un branch per la tua feature
3. Commit delle modifiche
4. Push del branch
5. Crea una Pull Request

Licenza

Questo progetto è distribuito sotto licenza LGPL-3.0-or-later.

Autore

Luca Gualandi - Sviluppatore del framework Omnia

Supporto

Per supporto e domande, contatta il team di sviluppo o apri una issue nel repository.