Cayaqui.MPS.ExcelExport 0.3.0

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.

v0.3.0 — Reportes con secciones + charts EVM nativos

Nueva API IExcelReportExporter para componer reportes multi-sheet con la Curva S de EVM y el Cashflow mensual + acumulado como IChart Excel nativos (no imágenes — refrescables y editables in-Excel):

@inject IExcelReportExporter ReportExporter

var report = new ExcelReport()
    .AddTitle("Talara U3 · Cut-off 2026-04-30")
    .AddEvmSCurveChart(new EvmSCurveChartSection
    {
        Points      = evmPoints,                  // PV, EV, AC, Forecast por mes
        Bac         = 10_000_000m,                // stripline horizontal
        ControlDate = new DateTime(2026, 4, 30),  // stripline vertical
        Currency    = "USD"
    })
    .AddCashflowChart(new CashflowChartSection
    {
        Points         = cashflowPoints,          // Plan, Actual, Forecast por mes
        CutOffDate     = new DateTime(2026, 4, 30),
        Currency       = "USD",
        ShowCumulative = true                     // 3 columnas + 3 líneas acumuladas (dual-axis)
    });

await using var stream = await ReportExporter.ExportAsync(report);

Output: workbook con sheet "Cover" (título + branding logos) + "Curva S" (4 series + striplines BAC/ControlDate) + "Cashflow" (combo dual-axis con 6 series + stripline CutOffDate).

DTOs propios del package (sin dependencia con MPS.Components):

public sealed record EvmSCurvePoint(DateTime Date, decimal? Pv, decimal? Ev, decimal? Ac, decimal? Forecast);
public sealed record CashflowPoint(DateTime Date, decimal Plan, decimal Actual, decimal Forecast);

Si tu data layer ya construye los del componente Blazor, mappeás con un LINQ (mismo shape, distinto namespace).

EvmChartPalette expone los colores canónicos (Plan, Earned, Actual, Forecast, Bac, CutOff) como Syncfusion.Drawing.Color reutilizables — paleta #2E5BFF Plan, #7F56D9 EV, #D92D20 Actual, #039855 Forecast. Forecast/EAC siempre dashed para indicar proyección. Las acumuladas las computa CumulativeBuilder con paridad tested vs MPS.Components.Evm.CashflowChart.BuildDisplayPoints — los valores que ves en Excel son los mismos que los del componente Blazor.

AddTable<T> queda para v0.4.0 (out of scope este release; los reportes que requieran tablas combinan IExcelExporter<T>.ExportAsync con IExcelReportExporter.ExportAsync por ahora).

Sin breaking changes. El IExcelExporter<T>.ExportAsync v0.2.0 sigue idéntico. Ver scripts/migrate-to-excelexport-0.3.0.md. +35 tests xUnit (49 total).

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)