Cayaqui.ExcelImport 0.3.8

Cayaqui.ExcelImport

Lee .xlsx y materializa DTOs tipados usando los atributos de Cayaqui.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.Metadata registrado (vía AddCayaquiExcelImport se registra automáticamente) + licencia Syncfusion válida.

Instalación

dotnet add package Cayaqui.ExcelImport

builder.Services.AddCayaquiExcelImport(); // registra también AddCayaquiMetadata

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.Metadata registrado
• Licencia Syncfusion Essential Studio (XlsIO)