Gasolutions.Core.Patterns.Result 2.0.0.1

Gasolutions.Core.Patterns.Result

Español · English

<a name="español"></a>

🇪🇸 Español

Implementación del patrón Result para .NET 9. Permite manejar resultados y errores de forma explícita, evitando el uso de excepciones para flujos de control y proporcionando información contextual precisa sobre el origen del error.

Instalación

dotnet add package Gasolutions.Core.Patterns.Result

Clases principales

Inicio rápido

Retornar un éxito

public Result CrearUsuario(string nombre)
{
    // ... lógica de negocio
    return Result.Success();
}

public Result<Usuario> ObtenerUsuario(int id)
{
    var usuario = _repo.FindById(id);
    if (usuario is null)
        return Result<Usuario>.Failure(DatabaseErrors.NotFound("Usuario", id));

    return Result<Usuario>.Success(usuario);
}

Retornar un error

public Result<Producto> ObtenerProducto(int id)
{
    var producto = _db.Productos.Find(id);
    if (producto is null)
        return Result<Producto>.Failure(DatabaseErrors.NotFound("Producto", id));

    return Result<Producto>.Success(producto);
}

Consumir el resultado

var resultado = ObtenerProducto(42);

if (resultado.IsFailure)
{
    Console.WriteLine($"Error [{resultado.Error.Code}]: {resultado.Error.Description}");
    Console.WriteLine($"Origen: {resultado.Error.ClassName}.{resultado.Error.MethodName}");
    return;
}

Console.WriteLine($"Producto: {resultado.Value.Nombre}");

Usar ResultResponse<T> en una API

[HttpGet("{id}")]
public IActionResult GetProducto(int id)
{
    var resultado = _service.ObtenerProducto(id);

    if (resultado.IsFailure)
        return NotFound(new ResultResponse<Producto>
        {
            IsFailure = true,
            Error = resultado.Error
        });

    return Ok(new ResultResponse<Producto>
    {
        IsSuccess = true,
        Value = resultado.Value
    });
}

Fábricas de errores disponibles

Ejemplos por fábrica

// ArgumentErrors
ArgumentErrors.NoValid("string", "correo", "no tiene formato válido");

// AuthErrors
AuthErrors.InvalidCredentials();
AuthErrors.UserBlocked("jgalviz");
AuthErrors.InsufficientPermissions();
AuthErrors.SamlConfigNotFound(companyId: 5);

// AzureStorageErrors
AzureStorageErrors.BlobNotFound("mi-contenedor", "archivo.pdf");

// CommunicationErrors
CommunicationErrors.CommunicationError("PaymentService", "timeout después de 30s");

// ContainerErrors
ContainerErrors.InvalidContainerName();
ContainerErrors.LocalFileNotFound("/tmp/reporte.pdf");

// DatabaseErrors
DatabaseErrors.NotFound("Factura", 1001);                            // por ID
DatabaseErrors.NotFound("Factura", "NumeroFactura", "F-2024-001");   // por campo y valor
DatabaseErrors.NotFound("Caja", "CodigoCaja", isMale: false);        // género femenino
DatabaseErrors.TableWithoutRegisters("Producto");
DatabaseErrors.NotUpdated("Pedido", 55, "registro bloqueado");
DatabaseErrors.AssociatedRegisters("CajaVenta", stationId: 3);
DatabaseErrors.ForeingRelationViolated("el mensaje de error del motor de BD");

// EmailErrors
EmailErrors.InvalidResponse();
EmailErrors.InvalidResponse("SMTP 550: buzón lleno");
EmailErrors.Others("El proveedor rechazó el adjunto");   // mensaje libre

// EnviromentVariableErrors
EnviromentVariableErrors.NoFound("CONNECTION_STRING");

// ExceptionErrors
ExceptionErrors.ExceptionNotControlled(ex);
ExceptionErrors.ExceptionNotControlledInvokingServiceMethod("UserService", ex);

// HttpErrors
HttpErrors.UnAuthorized("https://api.pagos.com/cobros");
HttpErrors.BadResponse("FacturaDto", responseBody);
HttpErrors.InternalServerError(responseBody);            // mensaje del servidor, no localizado

// KeyValueErrors
KeyValueErrors.NoValid("clave-inv@lida");

// OtherErrors
OtherErrors.NotDefined("Ocurrió algo inesperado");       // mensaje libre
OtherErrors.CommunicationError(["ServicioA", "ServicioB"]);
OtherErrors.MessageMismatch(["ok", "procesado"], ["error", "timeout"]);

// TokenErrors
TokenErrors.GettingProblem("IdentityServer");

// TwoFactorErrors
TwoFactorErrors.EmailNotConfirmed();
TwoFactorErrors.UserNotFound("jgalviz");
TwoFactorErrors.OtpInvalid();
TwoFactorErrors.OtpExpired();
TwoFactorErrors.InvalidCredentials();

Soporte de idiomas (Español / Inglés)

Por defecto la librería devuelve todos los mensajes en español. Para cambiar el idioma usa ErrorLanguage.Current:

using System.Globalization;
using Gasolutions.Core.Patterns.Result.Localization;

// Cambiar a inglés
ErrorLanguage.Current = new CultureInfo("en");

// Volver a español
ErrorLanguage.Current = new CultureInfo("es");

Ejemplo de salida por idioma

// --- Español (por defecto) ---
var err = DatabaseErrors.NotFound("Producto", 42);
// Description → "Producto 42 no fue encontrado."

// --- Inglés ---
ErrorLanguage.Current = new CultureInfo("en");
var err = DatabaseErrors.NotFound("Product", 42);
// Description → "Product 42 was not found."

Configuración global en ASP.NET Core

Configura el idioma una sola vez en el arranque de la aplicación:

// Program.cs
ErrorLanguage.Current = new CultureInfo(
    builder.Configuration["AppLanguage"] ?? "es"
);

Nota: Los mensajes que son texto libre del llamador (p. ej., OtherErrors.NotDefined, AuthErrors.RequiredField, HttpErrors.InternalServerError) no se localizan; la librería los pasa tal cual.

La estructura del Error

public sealed record Error(
    string Code,         // Código auto-generado: "NombreClase.NombreMetodo"
    string Description,  // Mensaje localizado o texto del llamador
    string ClassName,    // Clase que invocó la fábrica
    string MethodName    // Método que invocó la fábrica
);

Ejemplo de inspección

var error = DatabaseErrors.NotFound("Orden", 99);

Console.WriteLine(error.Code);        // "DatabaseErrors.NotFound"
Console.WriteLine(error.Description); // "Orden 99 no fue encontrada."
Console.WriteLine(error.ClassName);   // Clase del llamador
Console.WriteLine(error.MethodName);  // Método del llamador

Patrón recomendado en capas

// Capa de dominio / servicio
public Result<Pedido> ProcesarPedido(int pedidoId)
{
    var pedido = _repo.Find(pedidoId);
    if (pedido is null)
        return Result<Pedido>.Failure(DatabaseErrors.NotFound("Pedido", pedidoId));

    if (!pedido.PuedesProcesarse())
        return Result<Pedido>.Failure(OtherErrors.NotDefined("El pedido no está en estado válido para procesarse."));

    pedido.Procesar();
    _repo.Save(pedido);
    return Result<Pedido>.Success(pedido);
}

// Capa de API
[HttpPost("{id}/procesar")]
public IActionResult Procesar(int id)
{
    var resultado = _service.ProcesarPedido(id);

    return resultado.IsSuccess
        ? Ok(resultado.Value)
        : BadRequest(resultado.Error);
}

<a name="english"></a>

🇺🇸 English

Result pattern implementation for .NET 9. Provides explicit handling of operation results and errors — avoiding exceptions for flow control — with precise contextual information about where each error originated.

Installation

dotnet add package Gasolutions.Core.Patterns.Result

Core classes

Quick start

Returning success

public Result CreateUser(string name)
{
    // ... business logic
    return Result.Success();
}

public Result<User> GetUser(int id)
{
    var user = _repo.FindById(id);
    if (user is null)
        return Result<User>.Failure(DatabaseErrors.NotFound("User", id));

    return Result<User>.Success(user);
}

Returning an error

public Result<Product> GetProduct(int id)
{
    var product = _db.Products.Find(id);
    if (product is null)
        return Result<Product>.Failure(DatabaseErrors.NotFound("Product", id));

    return Result<Product>.Success(product);
}

Consuming the result

var result = GetProduct(42);

if (result.IsFailure)
{
    Console.WriteLine($"Error [{result.Error.Code}]: {result.Error.Description}");
    Console.WriteLine($"Origin: {result.Error.ClassName}.{result.Error.MethodName}");
    return;
}

Console.WriteLine($"Product: {result.Value.Name}");

Using ResultResponse<T> in an API

[HttpGet("{id}")]
public IActionResult GetProduct(int id)
{
    var result = _service.GetProduct(id);

    if (result.IsFailure)
        return NotFound(new ResultResponse<Product>
        {
            IsFailure = true,
            Error = result.Error
        });

    return Ok(new ResultResponse<Product>
    {
        IsSuccess = true,
        Value = result.Value
    });
}

Available error factories

Language support (Spanish / English)

By default all messages are in Spanish. Switch languages with ErrorLanguage.Current:

using System.Globalization;
using Gasolutions.Core.Patterns.Result.Localization;

// Switch to English
ErrorLanguage.Current = new CultureInfo("en");

// Back to Spanish
ErrorLanguage.Current = new CultureInfo("es");

Sample output per language

// --- Spanish (default) ---
var err = DatabaseErrors.NotFound("Producto", 42);
// Description → "Producto 42 no fue encontrado."

// --- English ---
ErrorLanguage.Current = new CultureInfo("en");
var err = DatabaseErrors.NotFound("Product", 42);
// Description → "Product 42 was not found."

Global setup in ASP.NET Core

// Program.cs
ErrorLanguage.Current = new CultureInfo(
    builder.Configuration["AppLanguage"] ?? "es"
);

Note: Caller-supplied free-text messages (e.g., OtherErrors.NotDefined, AuthErrors.RequiredField, HttpErrors.InternalServerError) are not localized by the library — they are passed through as-is.

The Error record structure

public sealed record Error(
    string Code,         // Auto-generated: "ClassName.MethodName"
    string Description,  // Localized message or caller-supplied text
    string ClassName,    // Class that called the factory
    string MethodName    // Method that called the factory
);

Recommended layered pattern

// Domain / service layer
public Result<Order> ProcessOrder(int orderId)
{
    var order = _repo.Find(orderId);
    if (order is null)
        return Result<Order>.Failure(DatabaseErrors.NotFound("Order", orderId));

    if (!order.CanBeProcessed())
        return Result<Order>.Failure(OtherErrors.NotDefined("Order is not in a valid state for processing."));

    order.Process();
    _repo.Save(order);
    return Result<Order>.Success(order);
}

// API layer
[HttpPost("{id}/process")]
public IActionResult Process(int id)
{
    var result = _service.ProcessOrder(id);

    return result.IsSuccess
        ? Ok(result.Value)
        : BadRequest(result.Error);
}

License

MIT © Gasolutions SAS