TerraFluent
Get started
TerraFluent.Docx.Reporting · v1.4.0

Native Word documents, no Word required

Writes Open XML packages directly — real .docx reports, invoices, proposals, and branded templates from any .NET runtime on Windows, Linux, or macOS.

View on GitHub NuGet Feature guide
NuGet version NuGet downloads MIT license
dotnet add package TerraFluent.Docx.Reporting
Quick start

A complete document in one lambda

Metadata, page setup, header, page-numbered footer, and content — published straight to a .docx that opens cleanly in Word and LibreOffice.

  • No Word installation, no COM automation
  • Real page-number fields, not baked-in text
  • Metric and imperial units via Unit helpers
using TerraFluent.Docx.Reporting;

Document.Create(doc =>
{
    doc.MetadataTitle("Quarterly Report")
       .MetadataAuthor("Northwind Consulting");

    doc.Page(page =>
    {
        page.Size(PageSize.A4);
        page.Margin(Unit.Centimetre(2));
        page.Header().Text("Quarterly Report", t => t.Bold().AlignCenter());
        page.Footer().Text(t =>
        {
            t.Span("Page ");
            t.CurrentPageNumber();
            t.Span(" of ");
            t.TotalPages();
            t.AlignCenter();
        });

        page.Content().H1("Executive Summary");
        page.Content().Text("Revenue improved across every practice.");
    });
}).PublishDocx("quarterly-report.docx");
Tables

Styled tables with a real column model

Relative column widths, styled header rows, alternating row backgrounds, and per-cell text styling — the table structure Word users expect, defined fluently.

  • A full Colors palette (Material-style shade scales)
  • Cell padding, borders, and minimum row heights
  • Header and data rows declared separately
page.Content().Table(table =>
{
    table.CellPadding(5, 7)
         .HeaderBackground(Colors.Blue.L700)
         .AlternateRowBackground(Colors.Grey.L100)
         .Border(0.75f, Colors.Grey.L300);

    table.ColumnsDefinition(cols =>
    {
        cols.RelativeColumn(3);
        cols.RelativeColumn(1);
    });

    table.HeaderRow(row =>
    {
        row.Cell().Text("Item", t => t.Bold().FontColor(Colors.White.Default));
        row.Cell().Text("Amount", t => t.Bold().FontColor(Colors.White.Default).AlignRight());
    });

    table.Row(row =>
    {
        row.Cell().Text("Implementation");
        row.Cell().Text("$4,500", t => t.AlignRight());
    });
});
Charts

Bar, line, pie — as native Word charts

Charts are written as real Open XML chart parts, so they stay editable in Word. v1.3.0 adds legend placement, axis titles, data labels, stacked and percent-stacked bars, and custom sizing.

  • Multiple series with per-series colors
  • Legend(ChartLegendPosition.Bottom) or HideLegend()
  • Stacked() / PercentStacked() for bar charts
page.Content().Chart(chart => chart
    .Title("Stacked Revenue by Quarter")
    .Width(430).Height(250)
    .AlignCenter()
    .Legend(ChartLegendPosition.Bottom)
    .CategoryAxisTitle("Quarter")
    .ValueAxisTitle("Revenue ($M)")
    .DataLabels()
    .Stacked()
    .Series("Product",  s => s.Bar("Q1", 4.1).Bar("Q2", 4.3).Color(Colors.Blue.L700))
    .Series("Services", s => s.Bar("Q1", 2.2).Bar("Q2", 2.6).Color(Colors.Orange.L700)));
Images & barcodes

Wrapped images, vector barcodes, numbered captions

Images support square wrapping, floating, borders, rounding, and cropping. Code 128 barcodes render as crisp vector shapes — they stay sharp at any zoom and print resolution. Both take auto-numbered captions that feed a table of figures.

  • Alt text for accessibility
  • From file path or byte[]
  • Barcode color, size, and alignment control
page.Content().Image(bytes, "photo.png", img => img
    .Width(140)
    .WrapSquare(8)
    .FloatRight(8)
    .Border(1, Colors.Grey.L400)
    .Rounded()
    .Caption("Figure 1. Site photo"));

page.Content().Barcode("ACME-99887766", bc => bc
    .Width(220)
    .Height(50)
    .BarColor(Colors.Blue.L700)
    .AlignCenter()
    .Caption("Figure 2. Product tracking code"));
QR codes

Native QR codes, rendered as vectors

IContainer.QrCode(...) encodes arbitrary UTF-8 text as a QR code and renders it as a vector DrawingML shape — no raster image, no media part — with a built-in quiet zone and a symbol version chosen automatically.

  • Four error correction levels — Low through High
  • Custom foreground/background colors and alignment
  • Usable anywhere an image can go, with the same caption support
page.Content().QrCode("https://example.com");

page.Content().QrCode("WIFI:T:WPA;S:MyNetwork;P:secret123;;", qr => qr
    .Size(140)
    .ErrorCorrection(QrErrorCorrectionLevel.High)
    .ForegroundColor(Colors.Blue.L800)
    .AlignCenter()
    .Caption("Guest Wi-Fi"));
Templates

Fill existing branded documents

When a .docx template already exists — a letterhead, a contract, a company form — open it, replace placeholders and content controls, and save. No document rebuild required.

  • Plain-text placeholder replacement
  • Content-control replacement for structured fields
  • Keeps every style and asset the template already has
DocxTemplate.Open("template.docx")
    .Replace("CustomerName", "Ada Lovelace")
    .ReplaceContentControl("InvoiceTotal", "$1,250.00")
    .SaveAs("output.docx");
Protection

Restrict editing, straight from code

Apply Word's "Restrict Editing" protection with an optional password — ReadOnly, CommentsOnly, TrackedChangesOnly, or FormsOnly. The password verifier is stored as a salted, spun SHA-512 hash per ISO/IEC 29500.

  • Ideal for policy documents and issued invoices
  • A guard rail against accidental edits (the file itself is not encrypted)
Document.Create(doc =>
{
    doc.RestrictEditing(DocumentProtection.ReadOnly, "secret123");
    doc.Page(page => page.Content().Text("Read-only content."));
}).PublishDocx("policy.docx");
v1.4.0

What's new

  • QR codes — IContainer.QrCode(...), rendered as vector shapes with four error correction levels.
  • RestrictEditing password fix — the verifier hash now matches what Word itself computes, so removing protection with the correct password works.
  • Fixed-plus-relative column sizing fix — a ConstantItem() mixed with RelativeItem()/AutoItem() no longer over-allocates width in Row()/Table().
  • Fail-fast validation — several silent-failure paths (null text, blank hyperlink URLs, empty rows, mismatched merge calls) now throw clear exceptions instead of producing a corrupt or data-losing document.

Full changelog →

Documentation

Guides, reference, and samples

Generated packages are validated with the Open XML SDK test suite and smoke-checked in Microsoft Word and LibreOffice.

Getting StartedYour first document Core ConceptsDocuments, pages, builders Feature GuideEvery feature, with examples API ReferenceThe full fluent surface SamplesInvoices, annual report, showcase TroubleshootingCommon issues, resolved
FAQ

Frequently asked questions

Do I need Microsoft Word or Office interop to generate .docx files?

No. TerraFluent.Docx.Reporting writes Open XML packages directly, so it creates real Word documents without Microsoft Office, Word automation, or COM interop — on Windows, Linux, and macOS, including Docker and serverless.

Are the charts real, editable Word charts?

Yes. Charts are written as native Open XML chart parts, so they open as live charts in Word — users can edit the data, and legends, axis titles, data labels, and stacked layouts are all supported.

Can I fill an existing branded Word template?

Yes. Open a .docx template, replace plain-text placeholders and content controls, and save — every style and asset the template already has is preserved, with no document rebuild.

Which .NET versions does TerraFluent.Docx.Reporting support?

It targets netstandard2.0 and net10.0, so it runs on .NET Framework 4.6.1+, .NET Core 2.0+, and every modern .NET release.

Can it generate QR codes?

Yes. IContainer.QrCode(...) encodes arbitrary UTF-8 text as a QR code and renders it as a vector DrawingML shape, not a raster image — sizing, four error correction levels, colors, alignment, and captions are all supported.

Runs everywhere .NET runs

netstandard2.0 for .NET Framework 4.6.1+ and .NET Core 2.0+, plus a dedicated net10.0 build. Windows, Linux, macOS. MIT licensed.

Get started Browse samples