Cayaqui.MPS.ExcelImport 0.2.0

Cayaqui.MPS.ExcelImport

Lee .xlsx y materializa DTOs tipados usando los atributos de Cayaqui.MPS.Metadata. Header-name matching con [ImportAlias], fallback por property name, o column-position via [ImportColumn]. Parsing respeta [ImportCulture], [ImportDefault], [ImportTrim], [ImportRegex].

Distribución propietaria — requiere contrato comercial con Cayaqui. Ver LICENSE.txt.

Dependencias: Cayaqui.MPS.Metadata registrado (vía AddMpsExcelImport se registra automáticamente) + licencia Syncfusion válida.

Instalación

dotnet add package Cayaqui.MPS.ExcelImport

builder.Services.AddMpsExcelImport();   // registra también AddMpsMetadata

Uso

public sealed class InvoiceRow
{
    [ImportAlias("N°", "Number")]
    public int InvoiceNumber { get; set; }

    [ImportAlias("Cliente", "Customer Name")]
    [NotEmpty] [MaxLength(100)]
    public string CustomerName { get; set; } = "";

    [ImportCulture("es-CL")]
    public decimal Amount { get; set; }

    [Date("dd/MM/yyyy")]
    public DateTime IssueDate { get; set; }

    [ImportDefault(false)]
    public bool IsPaid { get; set; }

    [ImportIgnore]
    public int InternalId { get; set; }
}

public class ImportService(IExcelImporter<InvoiceRow> importer)
{
    public async Task<ImportSummary> ProcessAsync(Stream xlsx)
    {
        var result = await importer.ImportAsync(xlsx, new ExcelImportOptions
        {
            SheetName = "Invoices",
            HeaderRow = 1,
            ContinueOnRowError = true,
            DefaultCulture = CultureInfo.InvariantCulture
        });

        return new ImportSummary
        {
            Success = result.SuccessCount,
            Failed = result.Errors.Count,
            Items = result.Rows,
            Errors = result.Errors
        };
    }
}

ExcelImportResult

public sealed class ExcelImportResult<T>
{
    IReadOnlyList<T> Rows { get; }                // DTOs exitosamente materializados
    IReadOnlyList<ExcelImportRowError> Errors { get; }
    int TotalRowsRead { get; }
    int SuccessCount { get; }                     // = Rows.Count
    bool HasErrors { get; }
}

public sealed record ExcelImportRowError(
    int RowNumber,
    string PropertyName,
    string? CellValue,
    string Reason);

Reglas de column mapping (precedencia)

1. [ImportColumn(n)] si está presente → match por posición (1-based).
2. Si HasHeader = true (default): match por header name:
   • [ImportAlias("A", "B")] primero (ordenado) — case-insensitive por default. Opt-in strict: [ImportAlias("CODE", CaseInsensitive = false)].
   • Luego por [Label("text")] (siempre case-insensitive, fallback conveniente).
   • Finalmente por nombre de la propiedad (siempre case-insensitive).
3. [ImportIgnore] → propiedad nunca se importa.

Opciones

var opts = new ExcelImportOptions
{
    SheetName = "Data",           // null = primer sheet
    SheetIndex = 1,               // 1-based si no se usa SheetName
    HeaderRow = 1,
    HasHeader = true,
    FirstDataRow = 2,             // null → HeaderRow+1
    LastDataRow = null,           // null → UsedRange.LastRow
    ContinueOnRowError = true,    // agrega a Errors y sigue
    DefaultCulture = CultureInfo.InvariantCulture
};

Requisitos

• .NET 10.0 o superior
• Cayaqui.MPS.Metadata registrado
• Licencia Syncfusion Essential Studio (XlsIO)