Getting Started with TerraPDF

Installation

Add TerraPDF to your .NET project via NuGet:

Copy Command

Package Information

• Package ID: TerraPDF
• Latest Version: v1.3.0
• Target Frameworks: .NET 8, .NET 9
• License: MIT (free for commercial use)

Namespace Imports

TerraPDF uses two main namespaces:

using TerraPDF.Core;      // Fluent API entry points, descriptors
using TerraPDF.Helpers;  // Color, PageSize, Unit, TextStyle

Your First PDF

Here's a complete "Hello World" example to get you started:

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

This creates output.pdf with:

• A4 page size with 2cm margins
• "My First PDF" header
• Two paragraphs of text
• Centered page numbers in the footer

Document Entry Points

TerraPDF offers two ways to create documents:

Inline Callback (Quick & Simple)

Document.Create(container => { /* build your PDF */ })
       .PublishPdf("report.pdf");

Reusable Document Class (DRY, reusable templates)

public class InvoiceDocument : IDocument
{
    private readonly InvoiceData _data;
    public InvoiceDocument(InvoiceData data) => _data = data;

    public void Compose(IDocumentContainer container)
    {
        container.Page(page =>
        {
            page.Size(PageSize.A4);
            page.Margin(2, Unit.Centimetre);
            page.Content().Text($"Invoice #{_data.Number}").Bold();
        });
    }
}

// Usage:
Document.Create(new InvoiceDocument(data))
       .PublishPdf("invoice.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

Choose the output format that suits your needs:

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

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

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

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