Tagua 0.22.0

Tagua

A .NET reporting engine. A template, written in YAML or JSON, describes the document; your application supplies the data; Tagua renders an accessible, archival PDF.

Documentation, guides and examples: taguareports.com.

• Accessible: tagged PDF with a structure tree, alt text and reading order, PDF/UA-1 and PDF/UA-2.
• Archival: PDF/A-2b, PDF/A-3b, PDF/A-4 and PDF/A-4f, with embedded, subset fonts (TrueType and CFF).
• E-invoices: Factur-X / ZUGFeRD hybrid invoices, with the XML attached and described.
• Reports: bands, groups with totals, tables that break across pages, charts, barcodes (QR, Data Matrix, PDF417, Code 128, EAN-13), subreports, "page n of m".
• Any script: right-to-left text, font fallback, and Unicode line breaking (Chinese, Japanese, Thai). Add Tagua.Shaping.HarfBuzz for Arabic, Indic and other scripts whose letters join or reorder.
• Safe and fast: templates hold no SQL or code, expressions are sandboxed and type-checked before any data is read, and there is no reflection: the engine runs under native AOT.

Example

orders.report.yaml:

title: Orders
culture: en-US
data:
  orders: { fields: { Customer: string, Total: decimal } }
body:
  detail:
    - layout: row
      content:
        - { type: text, value: "{Customer}", width: 3fr }
        - { type: text, value: "{Total:C}", width: 1fr, align: end }
  reportFooter:
    - content:
        - { type: text, value: "Total {Sum(Total):C}", fontWeight: bold, align: end }

using Tagua;
using Tagua.Fill;
using Tagua.Pipeline;
using Tagua.Serialization;

TaguaSettings.License = LicenseType.Community;   // once, at startup (see the licensing terms)

var report = CompiledReport.Compile(TemplateLoader.LoadFile("orders.report.yaml"));
var inputs = new ReportInputs
{
    Data = new Dictionary<string, IDataSet>
    {
        ["orders"] = DataSources.FromRows([
            new Dictionary<string, object?> { ["Customer"] = "Contoso", ["Total"] = 1250.00m },
            new Dictionary<string, object?> { ["Customer"] = "Fabrikam", ["Total"] = 480.50m },
        ]),
    },
    // Fonts, images and subreports named in the template are opened from here.
    Resources = new DirectoryResourceResolver("."),
};

await using var pdf = File.Create("orders.pdf");
var result = await Reports.RenderPdfAsync(report, inputs, pdf);
foreach (var diagnostic in result.Diagnostics) Console.WriteLine(diagnostic);

Rows can also come from any DbDataReader (DataSources.FromDataReader).

Your application's functions

Expressions can call .NET functions your application provides, beside the built-in ones. Their parameter and result types are checked like any other call:

var functions = new ReportFunctions()
    .Add("RowColor", (int row) => row % 2 == 0 ? "#F2F2F2" : "#FFFFFF")
    .Add("Words", (decimal amount) => AmountInWords(amount));

var template = TemplateLoader.LoadFile("invoice.report.yaml");
var report = CompiledReport.Compile(template, functions);
// value: "{Words(Total)}", styleFrom: { background: =RowColor(RowNumber()) }

Subreports can call them too. A report filled on several threads calls them on those threads.

Templates

TemplateSchema.Json is the JSON Schema of templates, for editors and for LLM structured output; the Tagua.Cli tool prints it (tagua schema) and renders templates as you edit them (tagua render --watch).

License

Tagua is free under the Community licenses: PolyForm Small Business, for companies with fewer than 100 people and less than USD 1 million in revenue, and PolyForm Noncommercial, for personal use, charities, education, research and government. Anyone may evaluate it for less than 32 days under the PolyForm Free Trial license (LicenseType.Trial). Other companies need a Professional license (per developer) or an Enterprise license (unlimited developers, redistribution in products sold to others, and support): licensing@taguareports.com.

Declare the license once, at startup, with TaguaSettings.License, or with the environment variable TAGUA_LICENSE (community, trial, professional or enterprise). Nothing is checked online and the output is the same under every license: the declaration states that you qualify for it. The terms are in LICENSE.txt.