👁 Image
Oakrey.Applications.Reporting 3.0.4

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.