PayrollEngine.Document 0.10.0-beta.3

Payroll Engine Document

Part of the Payroll Engine open-source payroll automation framework. Full documentation at payrollengine.org.

Document library for the Payroll Engine, providing data transformation for exchange and reporting. Supports PDF generation via FastReport templates, Excel export via NPOI, and FastReport template generation from a DataSet schema.

Features

• PDF Generation — Merge DataSet with FastReport templates (.frx) to produce PDF documents with metadata (author, title, keywords)
• Excel Export — Convert DataSet tables to .xlsx workbooks with auto-sized columns, header filters, and correct cell typing (numeric, boolean, date)
• Template Generation — Generate a FastReport skeleton (.frx) from a DataSet schema for use in the FastReport Designer, or update the Dictionary section of an existing template in CI pipelines
• Template Parameters — Pass custom key-value parameters into FastReport templates
• Document Metadata — Apply metadata (author, title, subject, keywords) to generated documents

NuGet Package

Available on NuGet.org:

dotnet add package PayrollEngine.Document

Quick Start

PDF Generation from FastReport Template

using PayrollEngine.Document;

IDocumentService documentService = new DocumentService();

// load your FastReport template (.frx)
await using var templateStream = File.OpenRead("report-template.frx");

// prepare your data
var dataSet = new DataSet();
// ... populate tables ...

// define document metadata
var metadata = new DocumentMetadata
{
    Title = "Payroll Report Q1 2026",
    Author = "Payroll Engine",
    Keywords = "payroll, report"
};

// optional: template parameters
var parameters = new Dictionary<string, object>
{
    ["CompanyName"] = "Acme Corp",
    ["ReportDate"] = DateTime.Now
};

// generate PDF
await using var pdfStream = await documentService.MergeAsync(
    templateStream, dataSet, DocumentType.Pdf, metadata, parameters);

// save to file
await pdfStream.WriteToFile("report.pdf");

Excel Export

IDocumentService documentService = new DocumentService();

var dataSet = new DataSet();
// ... populate tables (each DataTable becomes a worksheet) ...

var metadata = new DocumentMetadata { Title = "Payroll Data Export" };

// generate Excel workbook
await using var excelStream = await documentService.ExcelMergeAsync(dataSet, metadata);

// save to file
await excelStream.WriteToFile("export.xlsx");

FastReport Template Generation

IDocumentService documentService = new DocumentService();

var dataSet = new DataSet();
// ... populate tables and relations ...

// new skeleton — developer opens in FastReport Designer and builds the layout
await using var frxStream = await documentService.GenerateAsync(dataSet);
await frxStream.WriteToFile("MyReport.frx");

// CI mode — update Dictionary in an existing template, preserving layout
await using var templateStream = File.OpenRead("MyReport.frx");
await using var updatedStream = await documentService.GenerateAsync(dataSet, templateStream);
await updatedStream.WriteToFile("MyReport.frx");

API Reference

IDocumentService

The interface implemented by DocumentService, providing the contract for document generation.

DocumentService

The main entry point implementing IDocumentService.

¹⁾ The parameters argument of ExcelMergeAsync is part of the interface signature but is not applied during Excel export — Excel workbooks have no template parameter concept.

²⁾ The generated stream contains UTF-8 encoded .frx XML. Table relations defined on the DataSet are included as <Relation> elements in the Dictionary.

DocumentMetadata

Applied to generated documents. Fields and their PDF mapping:

Extension Methods

Type Mapping (Excel)

FastReport

Reports are based on FastReport Open Source:

• Report template format: *.frx (XML)
• Visual designer: FastReport Designer Community Edition

Build

dotnet build
dotnet pack

Environment variable used during build:

Third Party Components

See Also

• Payroll Engine WebApp — uses this library for report rendering
• Payroll Engine Console — uses this library for the Report, DataReport and ReportBuild commands
• FastReport Open Source documentation — template authoring reference