Reporting

PouryaKit.Reporting has one renderer, IReportRenderer. A Module builds a ReportLayout from what it read: a title, an introduction of headings and paragraphs, one table of text cells, and its branding, a logo and an accent colour. Render turns the layout into a PDF, a CSV file or a spreadsheet in memory and returns a Result with the file's bytes, content type and extension. The layout stays in the Module; the Kit supplies the primitives, the font, the branding and the formats (what each format holds).

It stores nothing. The caller stores the rendered bytes through File storage, and the Report Module runs that whole job in the background for you.

When to use itCopy Anchor Link

• A Module produces a document for people to download, print or open in a spreadsheet.
• You brand a report with a logo and an accent colour.
• You store a rendered file, or need to know which layouts the renderer refuses.
• You test a rendered file with each format's standard reader.

How it worksCopy Anchor Link

In the Kit's testsCopy Anchor Link

A month's sales laid out once, with a heading and a paragraph of introduction, a page header and footer, and a logo and accent colour; the tests render it to every format and read each back:

private static readonly ReportLayout Sales = new(
    "Monthly sales",
    new ReportTable(
        [
            new("Product"),
            new("Quantity", ReportAlignment.Right),
            new("Amount", ReportAlignment.Right),
        ],
        Rows
    )
)
{
    Introduction =
    [
        new ReportHeading("October 2026"),
        new ReportParagraph("Every order the shop settled this month."),
    ],
    PageHeader = "Acme Shop",
    PageFooter = "Confidential",
    Branding = new() { Logo = Logo, Accent = new(0x1F, 0x4E, 0x79) },
};

Guarantees and failuresCopy Anchor Link

Next stepsCopy Anchor Link

ReferenceCopy Anchor Link

PouryaKit.Reporting: one renderer, IReportRenderer, that renders a Module's ReportLayout to a PDF, a CSV file or a spreadsheet in memory and returns a Result. The layout stays in the Module; the Kit supplies the primitives, the font, the branding and the three formats. Optional, namespace PouryaKit.Reporting; it references PouryaKit.Domain only, and stores nothing: the caller stores the rendered bytes, through storage.md.

• Registering
• A Module's layout
• Rendering and storing
• The three formats
• Limits
• Testing

RegisteringCopy Anchor Link

In the Composition Root of each Module that renders reports:

using Microsoft.Extensions.DependencyInjection.Extensions;
using PouryaKit.Reporting;

module.TryAddSingleton<IReportRenderer, ReportRenderer>();

• ReportRenderer keeps no state of its own, so one instance serves every caller at once; TryAddSingleton lets several Modules register it. The package has no registration call and no options.
• The PDF writer sets PDFsharp's process-wide font resolver to the Roboto faces the package embeds, the first time a PDF renders, unless the Host set its own resolver before; that one then resolves the report's fonts.

A Module's layoutCopy Anchor Link

A layout is a value the Module builds from what it read: a title, an introduction of headings and paragraphs, one table of text cells, and the branding. The Module formats every value, such as a number, an amount or a date, as the text the report shows, in the culture it chooses:

using System.Globalization;
using PouryaKit.Reporting;

internal static class SalesReport
{
    private static readonly ReportBranding Branding = new()
    {
        Logo = File.ReadAllBytes(Path.Combine(AppContext.BaseDirectory, "Reports", "logo.png")),
        Accent = new(0x1F, 0x4E, 0x79),
    };

    public static ReportLayout For(DateOnly month, IReadOnlyList<SalesLine> lines) =>
        new(
            "Monthly sales",
            new ReportTable(
                [new("Product"), new("Quantity", ReportAlignment.Right), new("Amount", ReportAlignment.Right)],
                [
                    .. lines.Select(line => (IReadOnlyList<string>)
                    [
                        line.Product,
                        line.Quantity.ToString(CultureInfo.InvariantCulture),
                        line.Amount.ToString("N2", CultureInfo.InvariantCulture),
                    ]),
                ]
            )
        )
        {
            Introduction =
            [
                new ReportHeading(month.ToString("MMMM yyyy", CultureInfo.InvariantCulture)),
                new ReportParagraph("Every order settled this month."),
            ],
            PageHeader = "Acme Shop",
            PageFooter = "Confidential",
            Branding = Branding,
        };
}

internal sealed record SalesLine(string Product, int Quantity, decimal Amount);

• ReportLayout(Title, Table): Introduction (ReportHeading and ReportParagraph, in order), PageHeader, PageFooter and Branding are optional.
• ReportTable(Columns, Rows): each ReportColumn has a header and an alignment, Left by default; each row has exactly one cell per column.
• ReportBranding: Logo, a PNG or JPEG image, and Accent, a ReportColor, dark grey by default, for the title and the table's header row.

Rendering and storingCopy Anchor Link

Render(layout, format) returns a RenderedReport with the file's Content, its ContentType and its FileExtension, ready for IFileStorage.UploadAsync. Store first, then record the key, as storage.md says:

var rendered = renderer.Render(SalesReport.For(command.Month, lines), ReportFormat.Pdf);
if (rendered.IsFailure)
{
    return rendered;
}

var report = rendered.Value;
var key = $"reports/sales/{Guid.CreateVersion7()}{report.FileExtension}";
var stored = await files.UploadAsync(key, new MemoryStream(report.Content), report.ContentType, cancellationToken);

Render refuses a layout it cannot draw, renders nothing, and returns an ErrorKind.Validation Error:

• ReportErrors.TableShape (Reporting.TableShape, target Table): the table has no column, or a row whose number of cells differs from its number of columns.
• ReportErrors.LogoFormat (Reporting.LogoFormat, target Logo): the logo is not a PNG or JPEG image PDFsharp can load, its signature checked, then its header and dimensions read, so a file cut short is refused, where MigraDoc would have drawn a placeholder in the PDF. A JPEG cut inside its image data still loads, since a PDF carries a JPEG as it is.

Rendering is synchronous and in memory, so the whole file is one byte array; render a large report from a background command, as the report Module does (reporting-module.md).

The three formatsCopy Anchor Link

LimitsCopy Anchor Link

• One table per report, of text cells; no charts, images in cells, merged cells or cell styles.
• One font, Roboto 2.138 regular and bold, with italic simulated: it holds Latin, Greek and Cyrillic glyphs, not Persian or Arabic, and the PDF writer lays out no right-to-left text.
• PDFsharp is pinned at 6.2.4, its last MIT release: 6.5.0 and later are AGPL-3.0-only, and the Kit takes no reciprocally licensed package.
• QuestPDF and ClosedXML are not used (licence), and no second file library.

TestingCopy Anchor Link

The Kit's tests render one layout to each format and read it back with that format's standard reader: the PDF with PDFsharp's PdfReader (its header, page count, logo and each page's fonts embedded with their font program), the spreadsheet with the Open XML SDK's SpreadsheetDocument.Open and its OpenXmlValidator (the cells as rows, escape-like text and control characters read back verbatim), and the CSV with CsvHelper's CsvReader (the rows, the escaped formulas, the numbers kept, the byte order mark and a one-column table's empty rows). A Module's own report test renders its layout the same way: build the layout from fixed rows, render it, and read back the cells it promises.