Estructura libre de razones

En Greencore, un error describe qué operación falló y conserva sus causas como un árbol. Error es una raíz concreta que permite composición libre y Reason representa una causa que puede contener otras causas. Ambos exponen un mensaje (Message), causas (Reasons) y metadatos (Metadata).

Composición básica de errores

Un error puede comenzar con un único mensaje: Error.Create("No se pudo importar el archivo."). Error.Create(...) devuelve un Error, de modo que puedes encadenar los métodos de composición. También puedes construirlo con new Error(mensaje). Para explicar el fallo, agrega causas. Las siguientes variantes construyen el mismo árbol.

Composición no fluida

Crea los nodos en variables y agrégalos a su padre con llamadas independientes:

using Greencore.Platform.Errors;

var error = new Error("No se pudo importar el archivo de clientes.");
var fila = new Reason("La fila 42 contiene datos inválidos.");
var nombre = new Reason("El nombre es obligatorio.");
var correo = new Reason("El correo no tiene un formato válido.");

fila.AddReason(nombre);
fila.AddReason(correo);
error.AddReason(fila);

Reasons es una colección de solo lectura. Agrega causas mediante los métodos de composición, no con Reasons.Add(...).

Composición fluida

Encadena las llamadas para construir el árbol en una expresión:

using Greencore.Platform.Errors;
using Greencore.Platform.Errors.Extensions;

var error = Error.Create("No se pudo importar el archivo de clientes.")
    .AddReason("La fila 42 contiene datos inválidos.")
        .WithReason("El nombre es obligatorio.")
        .WithReason("El correo no tiene un formato válido.")
    .Root();

Método	Devuelve	Uso
AddReason(...)	La causa agregada	Continuar dentro de esa causa
WithReason(...)	El nodo receptor	Agregar causas hermanas
WithReasons(...)	El nodo receptor	Agregar varias causas de una vez
WithMetadata(...)	El nodo receptor	Asociar datos al nodo actual
Root()	La raíz como Error	Recuperar el error desde una causa vinculada

Dos llamadas consecutivas a AddReason(...) crean niveles anidados. Dos llamadas a WithReason(...) agregan causas al mismo nodo. La indentación ayuda a leer el código, pero los valores devueltos determinan la estructura.

Mostrar errores con y sin opciones

Sin opciones

Usando cualquiera de las variantes anteriores:

Console.WriteLine(error.ToString());

No se pudo importar el archivo de clientes.
└── La fila 42 contiene datos inválidos.
    ├── El nombre es obligatorio.
    └── El correo no tiene un formato válido.

Por defecto, ToString() muestra todo el árbol con caracteres Unicode y sin metadatos.

Con metadatos y opciones

Los metadatos conservan datos como el código, el archivo o la fila afectada. Cada llamada a WithMetadata(...) modifica el nodo que la recibe:

using Greencore.Platform.Errors;
using Greencore.Platform.Errors.Extensions;
using Greencore.Platform.Errors.Trees;

var errorConMetadatos = Error.Create("No se pudo importar el archivo de clientes.")
    .WithMetadata("Code", "IMPORT_FAILED")
    .WithMetadata("File", "customers.csv")
    .AddReason("La fila 42 contiene datos inválidos.")
        .WithMetadata("Row", 42)
        .WithReason(new Reason("El nombre es obligatorio.")
            .WithMetadata("Property", "Name"))
        .WithReason(new Reason("El correo no tiene un formato válido.")
            .WithMetadata("Property", "Email"))
    .Root();

Console.WriteLine(errorConMetadatos.ToString(new TreeFormatOptions
{
    IncludeMetadata = true,
    UseUnicode = true
}));

No se pudo importar el archivo de clientes. [Code=IMPORT_FAILED, File=customers.csv]
└── La fila 42 contiene datos inválidos. [Row=42]
    ├── El nombre es obligatorio. [Property=Name]
    └── El correo no tiene un formato válido. [Property=Email]

Llamar a errorConMetadatos.ToString() sin opciones muestra el mismo árbol sin los datos entre corchetes. Los metadatos siguen disponibles en Metadata: las opciones solo cambian la representación.

Opción	Valor predeterminado	Efecto
IncludeMetadata	false	Muestra los metadatos junto a cada nodo
UseUnicode	true	Usa ramas Unicode; con false, utiliza ASCII
IndentSize	4	Define el ancho de cada nivel; mínimo 2
MaxDepth	null	Limita la profundidad; 0 muestra la raíz y un indicador si hay causas omitidas

Continuar

• Referenciar causas como errores: devolver el fallo de una fila sin separarlo del diagnóstico del lote.

• Producir y consumir errores: métodos con y sin Result.

• Recorrer y consultar errores: enumeración con TreeTraversal y búsqueda con TreeQuery.