Oakrey.Applications.Reporting 3.0.3

Oakrey.Applications.Reporting

A .NET 10 Windows library for structured, lifecycle-driven reporting. The library defines a generic reporting pipeline built around a TStatus : Enum and supports hierarchical report/block/item events, evidence attachment, key-value metadata, thread-safe file output, and multi-consumer fanout.

Main Features

• Generic IReporter<TStatus, TObject> and IReportConsumer<TStatus, TObject> contracts driven by a caller-defined TStatus enum.
• Hierarchical lifecycle: ReportBegin ? BlockBegin ? ItemBegin ? ItemCompleted ? BlockCompleted ? ReportCompleted.
• Evidence attachment on every item completion via Oakrey.Evidences.IEvidence.
• Key-value properties and trace list carried by ReportMetadata.
• RunnableReporter fans out all lifecycle events to multiple IReportConsumer instances simultaneously.
• FileReporter writes timestamped .txt report files with thread-safe locking.
• DocumentsReportFilePathProvider writes reports to %USERPROFILE%\Documents\Reports with compact date-time file names.
• Pluggable file path strategy via IReportFilePathProvider.
• Pluggable label strategy via IReporterTypeNameProvider.

Architecture

classDiagram
    class IReporter~TStatus,TObject~ {
        +ReportBegin(summary, metadata)
        +ReportCompleted(status, summary, passObject)
        +BlockBegin(name)
        +BlockCompleted(name)
        +ItemBegin(item)
        +ItemCompleted(item, status, evidence)
        +ItemCompleted(item, status, evidence, message)
    }

    class IReportConsumer~TStatus,TObject~ {
        +ReportBegin(summary, metadata)
        +ReportCompleted(status, summary, passObject)
        +BlockBegin(name)
        +BlockCompleted(name)
        +ItemBegin(item)
        +ItemCompleted(item, status, evidence)
    }

    class RunnableReporter~TStatus,TObject~ {
        +RunnableReporter(IEnumerable~IReportConsumer~)
    }

    class FileReporter~TStatus,TObject~ {
        +FileReporter(IReportFilePathProvider, IReporterTypeNameProvider)
        +Dispose()
    }

    class IReportFilePathProvider {
        +GetDirectoryPath() DirectoryInfo
        +GetFileInfo() FileInfo
    }

    class DocumentsReportFilePathProvider
    class IReporterTypeNameProvider {
        +ReportName string
        +BlockName string
        +ItemName string
    }

    class ReportMetadata {
        +Properties Dictionary~string,string~
        +Traces List~string~
    }

    IReporter~TStatus,TObject~ <|.. RunnableReporter~TStatus,TObject~
    IReportConsumer~TStatus,TObject~ <|.. FileReporter~TStatus,TObject~
    RunnableReporter~TStatus,TObject~ --> IReportConsumer~TStatus,TObject~
    FileReporter~TStatus,TObject~ --> IReportFilePathProvider
    FileReporter~TStatus,TObject~ --> IReporterTypeNameProvider
    IReportFilePathProvider <|.. DocumentsReportFilePathProvider

Requirements

• .NET 10 (Windows)
• Oakrey.Collections >= 2.0.0
• Oakrey.Evidences >= 2.0.0
• Oakrey.Files >= 3.0.0
• Oakrey.Strings >= 2.1.0

Installation

.NET CLI

dotnet add package Oakrey.Applications.Reporting

Package Manager Console

Install-Package Oakrey.Applications.Reporting

NuGet Package Manager

Search for Oakrey.Applications.Reporting under Tools > NuGet Package Manager > Manage NuGet Packages for Solution.

Configuration

File path strategy

Implement IReportFilePathProvider to control where reports are written. The built-in DocumentsReportFilePathProvider resolves to %USERPROFILE%\Documents\Reports\ and generates compact date-time file names via Oakrey.Files.FileNameSource.

// Built-in � Documents\Reports\
IReportFilePathProvider pathProvider = new DocumentsReportFilePathProvider();

// Custom
public class MyPathProvider : IReportFilePathProvider
{
    public DirectoryInfo GetDirectoryPath() => new(@"C:\MyApp\Reports");
    public FileInfo GetFileInfo() => new(Path.Combine(@"C:\MyApp\Reports", $"report_{DateTime.Now:yyyyMMddHHmmss}.txt"));
}

Label strategy

Implement IReporterTypeNameProvider to control the line prefixes in the output file.

public class MyLabels : IReporterTypeNameProvider
{
    public string ReportName => "REPORT";
    public string BlockName  => "BLOCK";
    public string ItemName   => "ITEM";
}

Example Usage

Single file consumer

using Oakrey.Applications.Reporting;

IReportFilePathProvider pathProvider = new DocumentsReportFilePathProvider();
IReporterTypeNameProvider labels = new MyLabels();

using FileReporter<MyStatus, string> consumer = new(pathProvider, labels);

ReportMetadata metadata = new()
{
    Properties = new Dictionary<string, string> { ["Environment"] = "Production" },
    Traces = ["Build 42"]
};

consumer.ReportBegin("Nightly run", metadata);
consumer.BlockBegin("Validation");
consumer.ItemBegin(myItem);
consumer.ItemCompleted(myItem, MyStatus.Passed, evidence);
consumer.BlockCompleted("Validation");
consumer.ReportCompleted(MyStatus.Passed, "All checks passed", null);

Multi-consumer fanout

IReportConsumer<MyStatus, string>[] consumers = [fileReporter, otherConsumer];
IReporter<MyStatus, string> reporter = new RunnableReporter<MyStatus, string>(consumers);

reporter.ReportBegin("Nightly run", metadata);
// All lifecycle calls are broadcast to every consumer.
reporter.ReportCompleted(MyStatus.Passed, "Done", null);

Development Notes

• The project targets net10.0-windows; it is not cross-platform.
• FileReporter uses System.Threading.Lock (C# 13 / .NET 9+) for thread safety � do not port to older runtimes without replacing the lock.
• FileReporter must be disposed to flush and close the underlying FileStream.
• RunnableReporter does not own or dispose its consumers; caller is responsible for lifetime management.
• ReportMetadata is a struct � pass by reference or assign explicitly to avoid unintended copies.

Project Information

License

This project is licensed under the MIT License.