Getting Started with TerraPDF

Installation

dotnet add package TerraPDF

Namespaces

Minimal Example

using TerraPDF.Core;
using TerraPDF.Helpers;

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSize.A4);
        page.Margin(2, Unit.Centimetre);
        page.PageColor(Color.White);
        page.DefaultTextStyle(s => s.FontSize(11));

        page.Header().Text("My First PDF").Bold().FontSize(20);

        page.Content().Column(col =>
        {
            col.Spacing(8);
            col.Item().Text("Hello, TerraPDF!");
            col.Item().Text("A second paragraph.").Italic();
        });

        page.Footer().AlignCenter().Text(t =>
        {
            t.Span("Page ");
            t.CurrentPageNumber();
            t.Span(" / ");
            t.TotalPages();
        });
    });
})
.PublishPdf("output.pdf");

Document Entry Points

// Inline callback
Document.Create(container => { ... }).PublishPdf("output.pdf");

// Reusable IDocument class
Document.Create(new MyReport(data)).PublishPdf("output.pdf");

Page Configuration

Every page is configured through PageDescriptor:

container.Page(page =>
{
    // Size
    page.Size(PageSize.A4);                        // standard size
    page.Size(PageSize.Landscape(PageSize.A4));    // landscape
    page.Size(210, 297, Unit.Millimetre);          // explicit dimensions

    // Margins
    page.Margin(2, Unit.Centimetre);               // all sides
    page.MarginVertical(1, Unit.Centimetre);       // top + bottom
    page.MarginHorizontal(1.5, Unit.Centimetre);   // left + right
    page.Margin(top: 72, right: 54, bottom: 72, left: 54); // individual (points)

    // Appearance
    page.PageColor(Color.White);
    page.DefaultTextStyle(s => s.FontSize(11).FontColor(Color.Grey.Darken2));

    // Layout slots
    page.Header()   // IContainer — drawn above content on every page
    page.Content()  // IContainer — main scrollable area
    page.Footer()   // IContainer — drawn below content on every page
});

Output Methods

var composer = Document.Create(...);

// Write to file
composer.PublishPdf("report.pdf");

// Return as byte array (API responses, email attachments)
byte[] bytes = composer.PublishPdf();

// Write to any stream
using var stream = new MemoryStream();
composer.PublishPdf(stream);

Next Steps

• Text & Spans — styling, underline, line-height, multi-span, page numbers
• Layout — Column, Row, Table
• Decorators — Padding, Margin, Background, Border, Rounded Border, Per-Edge Borders, Alignment, Lines, PageBreak, Hyperlink, ShowIf
• Images — PNG and JPEG embedding
• Encryption & Security - AES-256 encryption (with legacy AES-128 support), passwords, and permissions
• Vector Graphics - Canvas API, shapes, paths, grids, and charts
• Unicode & Encoding - WinAnsiEncoding, Windows-1252 specials, and Latin-1 coverage
• Table of Contents — headings, automatic TOC generation, internal links
• Bookmarks — PDF outlines / hierarchical navigation tree
• Metadata — document properties (Title, Author, Subject, Keywords, Creator)
• Colors — full built-in palette reference
• Page Sizes & Units — all standard sizes and unit conversions
• Components & Templates — reusable IComponent and IDocument
• Row & Column Layout — deep dive with diagrams