PayrollEngine.Document 0.10.0-beta.1

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 and Excel export via NPOI.

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 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;

var dataMerge = new DataMerge();

// load your FastReport template (.frx)
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",
    Application = "PayrollEngine.Document",
    Keywords = "payroll, report"
};

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

// generate PDF
using var pdfStream = dataMerge.Merge(
    templateStream, dataSet, DocumentType.Pdf, metadata, parameters);

// save to file
await using var fileStream = File.Create("report.pdf");
await pdfStream.CopyToAsync(fileStream);

Excel Export

using PayrollEngine.Document;

var dataMerge = new DataMerge();

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

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

// generate Excel workbook
using var excelStream = dataMerge.ExcelMerge(dataSet, metadata);

// save to file
await using var fileStream = File.Create("export.xlsx");
await excelStream.CopyToAsync(fileStream);

Check Supported Document Types

var dataMerge = new DataMerge();
bool canMergePdf   = dataMerge.IsMergeable(DocumentType.Pdf);    // true
bool canMergeExcel = dataMerge.IsMergeable(DocumentType.Excel);  // true

API Reference

IDataMerge

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

DataMerge

The main entry point implementing IDataMerge.

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

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 and DataReport commands
• FastReport Open Source documentation — template authoring reference