KBUBComm.Reports 0.1.2

KBUBComm.Reports

Simple report builder wrapper for CSV, JSON, XML, and TXT output.

This package is intentionally small. It is built for the common KBUBComm pattern:

var result = await ReportBuilder.BuildBasicTextReportAsync(
    "AlarmReport_[FileTimestamp].csv",
    payload,
    ReportType.Csv);

Basic reports

Basic reports infer a wide table from CSV, JSON arrays, simple XML lists, or TXT lines.

var result = await ReportBuilder.BuildBasicTextReportAsync(
    "history.csv",
    payload,
    ReportType.Csv,
    new ReportFormatOptions
    {
        CanCreateDirectories = true,
        FileNameTimestampFormat = "yyyy-MM-dd_HHmmss",
        TimestampFormat = "yyyy-MM-dd HH:mm:ss",
        NullValueText = "NULL",
        BooleanHandling = ReportBooleanHandling.TrueFalseTitleCase
    },
    new BasicReportOptions
    {
        InputKind = ReportInputKind.Auto,
        TableShape = ReportTableShape.Wide,
        ColumnSort = ["Timestamp", "HA", "HB", "HC"]
    });

ColumnSort is a basic-only column ordering/filtering helper. When it is null, empty, or only contains blank values, the input column order is preserved. When it has values and the input has rows, only those existing input columns are included, in the requested order. Column names are matched case-insensitively before name replacements are applied.

When the input has zero rows and ColumnSort is provided, ColumnSort is treated as the intended header list so header-only reports can still be generated. This is useful for scheduled reports where no records were returned but the customer still expects a correctly shaped file.

Tall reports are intentionally advanced-only because they require observation grouping.

Advanced reports

Advanced reports map columns by source keys. JSON and XML payloads are flattened with dot paths.

var options = new AdvancedReportOptions
{
    TableShape = ReportTableShape.Wide,
    Columns =
    [
        ReportColumnMap.FromPath("Timestamp", "timestamp", ReportValueType.DateTime),
        ReportColumnMap.FromPath("Tag", "tagPath"),
        ReportColumnMap.FromPath("Value", "value"),
        ReportColumnMap.FromPath("Quality", "quality")
    ]
};

var result = await ReportBuilder.BuildAdvancedTextReportAsync(
    "alarms.csv",
    payload,
    ReportType.Csv,
    options);

Tall advanced reports use groups:

var options = new AdvancedReportOptions
{
    TableShape = ReportTableShape.Tall,
    TallGroups =
    [
        new ReportTallGroup
        {
            GroupName = "HA",
            Columns =
            [
                ReportColumnMap.FromPath("Timestamp", "timestamp", ReportValueType.DateTime),
                ReportColumnMap.FromLiteral("Tag", "HA"),
                ReportColumnMap.FromPath("Value", "ha.value"),
                ReportColumnMap.FromPath("Quality", "ha.quality")
            ]
        }
    ]
};

Filename tokens

Supported filename tokens:

• [FileTimestamp]
• [ReportTimestamp]
• [DataStartTime]
• [DataEndTime]
• [ReportName]

Output formats

Core v1 supports:

• ReportType.Csv
• ReportType.Json
• ReportType.Xml
• ReportType.Txt

ReportType.Xlsx, ReportType.Docx, and ReportType.Pdf are known values reserved for future grouped packages.