Cayaqui.MPS.Reports 0.3.0

Cayaqui.MPS.Reports — 0.3.0

Generación de reportes Excel · Word · PowerPoint · PDF basada en templates OpenXML, para .NET 10. Usa Syncfusion File Formats (XlsIO, DocIO, Presentation) — .xlsx/.docx/.pptx nativos con MailMerge, template markers y placeholder replacement.

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

Dependencias: Cayaqui.MPS.Storage registrado (para cargar templates + GenerateAndStoreAsync) + licencia Syncfusion válida del consumidor.

Novedades 0.3.0

• 🐛 Fix XlsIO markers — root cause del issue 0.2.0: el parser de XlsIO 33.2.3 captura el % de cierre como parte del variable name. Workaround aplicado; markers ahora reemplazan correctamente.
• 📄 PDF metadata — Title, Author, Subject, Keywords, Creator via DocumentInformation
• 🗄️ PDF/A-1b / 2b / 3b conformance para archivio ISO 19005
• ✅ RequiredFields + RequiredFieldsMode — fail-fast/warn/ignore si el data context no trae los campos esperados
• 🖼️ Image injection — placeholders {{image:key}} (Word/PPT) y %image:key% (Excel) mapean a ReportImage del dict
• 🧱 ReportContext fluent builder — ReportContext.Create().With(...).WithCollection(...).WithImage(...)
• 💧 Excel + PowerPoint watermark — cierra la limitación documentada en 0.2.0 (watermark shape por sheet/slide)
• 🧪 +16 tests (total 50) — PDF metadata, PDF/A smoke, RequiredFields (4 modos), ReportContext, image injection (Word/Excel/PPT), XlsIO regression

Novedades 0.2.0 (referencia)

Security (path traversal), ReportRenderException, logging, ReportRenderOptions (Header/Footer/Watermark/PdfPassword/DryRun), GenerateAndStoreAsync, GenerateExcelMultiSheetAsync, ValidateTemplateAsync, ITemplateCatalog, Word watermark + PDF post-processor.

Instalación

dotnet add package Cayaqui.MPS.Reports
dotnet add package Cayaqui.MPS.Storage

Uso — ReportContext fluent

var ctx = ReportContext.Create()
    .With("ProjectCode", "LBX-01")
    .With("ControlDate", DateTime.UtcNow)
    .With("Customer", new { FullName = "Acme Corp", TaxId = "12345-6" })
    .WithCollection("Items", invoice.Lines)
    .WithImage("logo", File.ReadAllBytes("logo.png"), "image/png")
    .WithImage("signature", signatureBytes);

await using var pdf = await reports.GenerateAsync(
    "invoice.docx",
    ctx.Build(),
    format: ReportFormat.Pdf,
    options: ctx.ToOptions(new ReportRenderOptions
    {
        PdfTitle = "Invoice {invoice.Number}",
        PdfAuthor = "Cayaqui",
        PdfConformance = PdfConformance.PdfA2b,
        RequiredFields = new[] { "ProjectCode", "ControlDate" },
        RequiredFieldsMode = RequiredFieldsMode.Throw
    }));

Uso — Image injection

Template Word (invoice.docx):

Invoice for {{image:logo}} — issued {{ControlDate}}
...
Signature: {{image:signature}}

Template Excel (report.xlsx), cell B1: %image:logo%, cell B20: %image:signature%.

Template PowerPoint (cover.pptx), text box with content {{image:logo}} en el centro del slide 1.

await reports.GenerateAsync("invoice.docx", data,
    options: new ReportRenderOptions
    {
        Images = new Dictionary<string, ReportImage>
        {
            ["logo"] = new ReportImage { Data = logoBytes, ContentType = "image/png",
                                          WidthPx = 120, HeightPx = 40 },
            ["signature"] = new ReportImage { Data = sigBytes, ContentType = "image/png" }
        }
    });

Uso — PDF metadata + PDF/A

var opts = new ReportRenderOptions
{
    PdfTitle = "Monthly Status — April 2026",
    PdfAuthor = "Project Controls Team",
    PdfSubject = "EVM snapshot for LBX-01",
    PdfKeywords = "evm;cpi;spi;monthly;lbx-01",
    PdfCreator = "MPS",
    PdfConformance = PdfConformance.PdfA2b
};
await using var pdf = await reports.GenerateAsync("monthly-status.docx", data,
    format: ReportFormat.Pdf, options: opts);

Uso — RequiredFields

try
{
    await reports.GenerateAsync("invoice.docx", data,
        options: new ReportRenderOptions
        {
            RequiredFields = new[] { "CustomerName", "InvoiceTotal", "DueDate" },
            RequiredFieldsMode = RequiredFieldsMode.Throw
        });
}
catch (ReportRenderException ex) when (ex.Message.Contains("Required fields"))
{
    _log.LogError("Invoice data incomplete: {Message}", ex.Message);
}

Watermark (all formats 0.3.0)

await reports.GenerateAsync("doc.docx", data,
    options: new ReportRenderOptions
    {
        Watermark = "CONFIDENTIAL",
        WatermarkColor = "#E5E7EB"
    });

Convenciones de template (unchanged)

Limitaciones conocidas

• Excel watermark: shape no rotado en 0.3.0 (XlsIO 33.x limitation en ITextBoxShape.Rotation). El watermark aparece horizontal. Workaround: diseñar watermark en el template mismo o usar PDF output con rotation.
• Image injection: el placeholder literal se reemplaza pero el fit/scale de la imagen depende de las dims provistas; si no se especifican, se usa el tamaño natural — puede desbordar el layout.

Requisitos

• .NET 10.0 o superior
• Cayaqui.MPS.Storage registrado
• Licencia Syncfusion Essential Studio registrada en el consumidor