Cayaqui.MPS.ExcelExport 0.1.1

Cayaqui.MPS.ExcelExport

Exporta colecciones de DTOs a .xlsx usando los atributos del paquete Cayaqui.MPS.Metadata. Simétrico a Cayaqui.MPS.ExcelImport — decorás tu DTO una sola vez y se importa/exporta con formato consistente.

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

Dependencias: Cayaqui.MPS.Metadata (se registra automáticamente con AddMpsExcelExport) + licencia Syncfusion XlsIO.

Instalación

dotnet add package Cayaqui.MPS.ExcelExport

builder.Services.AddMpsExcelExport();

Atributos consumidos

[Mask] NO se aplica al export — exportar datos enmascarados sería un bug (pierde el valor original para ediciones). Se respeta el valor sin máscara para que Excel edite bien.

Convenciones importantes

[Percentage] — almacenar ratio 0.0–1.0

Excel interpreta el formato 0.0% multiplicando el valor por 100. Almacenar 75.6 en el DTO produciría 7560% en la celda. Convención correcta:

[Percentage(1)]
public decimal Cpi { get; set; }   // ← almacenar 0.756, NO 75.6

Al exportar, la celda se ve 75.6%. Al importar (round-trip), se recupera 0.756.

[Badge] con enum values — color por fila

Sobre una propiedad enum con [BadgeColor] en cada valor, cada fila recibe el color correspondiente al valor de esa fila:

public enum Status
{
    [BadgeColor(BadgeKind.Success)] Approved,
    [BadgeColor(BadgeKind.Error)]   Rejected
}

[Badge] public Status RowStatus { get; set; }
// En Excel: filas con Approved → verde, filas con Rejected → rojo

[Badge(BadgeKind.Success)] (FixedKind) → toda la columna del mismo color.

Uso

public sealed class InvoiceRow
{
    [Display(Name = "N°", Order = 1)]
    public int InvoiceNumber { get; set; }

    [Label("Cliente")] [Display(Order = 2)]
    public string CustomerName { get; set; } = "";

    [Currency("USD", 2)] [Align(TextAlign.Right)] [ColumnWidth(120)] [Display(Order = 3)]
    public decimal Amount { get; set; }

    [Date("dd-MMM-yyyy")] [Display(Order = 4)]
    public DateTime IssueDate { get; set; }

    [Badge(BadgeKind.Success)] [Display(Order = 5)]
    public bool IsPaid { get; set; }

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

public class InvoiceExportService(IExcelExporter<InvoiceRow> exporter)
{
    public async Task<Stream> GenerateAsync(IEnumerable<InvoiceRow> rows)
    {
        return await exporter.ExportAsync(rows, new ExcelExportOptions
        {
            SheetName = "Invoices",
            FreezeHeaderRow = true,
            AutoFilter = true,
            HeaderBackgroundColor = "#D9E1F2"
        });
    }
}

ExcelExportOptions

public sealed class ExcelExportOptions
{
    string SheetName = "Data";
    bool IncludeHeader = true;
    bool StyleHeader = true;                           // bold + background
    string HeaderBackgroundColor = "#D9E1F2";
    bool FreezeHeaderRow = true;
    bool AutoFilter = true;
    bool AutoFitColumns = false;                       // usa [ColumnWidth] cuando se declara
    CultureInfo Culture = CultureInfo.InvariantCulture;
}

Tipos nativos vs texto

El exporter respeta el tipo de .NET para que Excel los trate como datos reales (números son sumables, fechas son filtrables):

Round-trip Export → Import

var rows = new[] { new InvoiceRow { ... } };

await using var exported = await exporter.ExportAsync(rows);    // DTO → xlsx
var result = await importer.ImportAsync(exported);              // xlsx → DTO
// result.Rows[0] === rows[0] (values preserved)

Este roundtrip está cubierto por tests.

Tests

Proyecto MPS.Infrastructure.ExcelExport.Tests — 9 tests ✅:

• Header + row values con types nativos (number, text, bool)
• [Hidden] excluye columna
• [Display(Order)] respeta orden declarado
• [VisibleIn(Web)] (sin Excel flag) omite columna
• [Currency] aplica number format a celdas
• Header styled bold + freeze pane activa
• Empty collection produce output sólo con header
• Round-trip: Export → Import preserva valores (int, string, decimal)

Requisitos

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