API Reference

This page lists the public fluent API exposed by TerraFluent.Docx.Reporting.

Public API Contract

TerraFluent.Docx.Reporting validates public inputs before writing packages. Null callbacks, empty paths or names, negative sizes or margins, unreadable streams, missing image files, empty image byte arrays, and barcode values outside ASCII 32-126 throw standard .NET exceptions such as ArgumentException, ArgumentOutOfRangeException, ArgumentNullException, or FileNotFoundException.

The fluent API clamps only where the Open XML concept is naturally bounded and documented by the API. Otherwise invalid input fails fast so production callers can catch configuration mistakes before distributing a damaged document.

Namespace

using TerraFluent.Docx.Reporting;
using TerraFluent.Docx.Reporting.Infra;

Most users only need TerraFluent.Docx.Reporting. Add TerraFluent.Docx.Reporting.Infra when implementing reusable components or receiving descriptor interfaces in your own helper methods.

Document

var document = Document.Create(doc =>
{
    doc.MetadataTitle("Quarterly Report");
    doc.Page(page => page.Content().Text("Hello from TerraFluent.Docx.Reporting."));
});

document.PublishDocx("report.docx");
byte[] bytes = document.PublishDocx();

Document Container

IDocumentContainer is the root builder received by Document.Create.

Document.Create(doc =>
{
    doc.MetadataTitle("Board Pack")
       .MetadataAuthor("Finance Team")
       .MetadataCreator("TerraFluent.Docx.Reporting")
       .Theme(theme => theme
           .DefaultFont("Aptos", 10.5f)
           .HeadingColor(Colors.Blue.L800)
           .AccentColor(Colors.Green.L700));

    doc.ParagraphStyle("FinePrint", text => text.FontSize(8).FontColor(Colors.Grey.L600));
});

Theme

Page

doc.Page(page =>
{
    page.Size(PageSize.A4)
        .Margin(Unit.Centimetre(2))
        .PageNumberStart(1)
        .PageNumberFormat("decimal")
        .Watermark("DRAFT", Colors.Grey.L300, 72);

    page.Header().Text("Confidential", t => t.AlignCenter().FontSize(9));
    page.Footer().Text(t =>
    {
        t.Span("Page ");
        t.CurrentPageNumber();
        t.Span(" of ");
        t.TotalPages();
        t.AlignCenter();
    });
});

Container

IContainer is used for page body content, headers, footers, columns, row items, and table cells.

Text

page.Content().Text(t =>
{
    t.Span("Revenue ").Bold();
    t.Span("increased 12%").FontColor(Colors.Green.L700);
    t.Span(" year over year.");
    t.SpacingAfter(8).KeepLinesTogether();
});

Lists

Tables

Column APIs:

Row APIs:

Cell APIs:

Images

Image paths are resolved when the document is published. A missing image path or empty image byte array throws instead of emitting placeholder text into the document.

Barcodes

Barcodes are rendered as vector shapes (grouped rectangles), not raster images, so they stay crisp at any zoom or print size. The value is validated eagerly: a null, empty, or non-ASCII-32-126 value throws ArgumentException at the fluent-call site, not at publish time.

Charts

Series APIs:

All series in a chart must use the same chart kind. Pie and doughnut charts support one series.

Layout Helpers

Row APIs:

Column APIs:

Templates

Template placeholder replacement is scoped to Word text nodes and supports placeholders split across multiple runs, as Word often stores formatted text. Replace("Name", value) targets ``; bare occurrences of Name are not replaced. Use content controls when you need strongly scoped replacements in authored Word templates.

Utilities

Unit

PageSize

Built-in sizes: A0, A1, A2, A3, A4, A5, A6, Letter, Legal, Ledger, Tabloid.

Use new PageSize(widthPoints, heightPoints) for custom sizes and PageSize.A4.Landscape() for a landscape value.

Colors

Colors provides common hex values under Black, White, Grey, Blue, Red, Green, and Orange. You can also pass any six-character hex color string, such as "1F4E79".

Enums

View this page's source on GitHub →