PdfDocument 1.0.0

📄 PDF Generation with DANFE, DACTE and Barcode Support

.NET 10 library for generating PDF documents from code.
Render text, shapes, tables, JPEG images and barcodes (Code 39 / EAN-13 / Code 128).
Plugin-based architecture with NFe/DANFE and CTe/DACTE support — parse Brazilian fiscal XMLs and render their auxiliary documents.

📋 Table of Contents

• Why PdfDocument?
• Installation
• Quick Start
• Architecture
• API Reference
• Barcodes
• DANFE / NFe · DACTE / CTe
• Playground
• Benchmarks
• Performance Optimizations
• Tests
• Security
• Code Quality
• Project Structure
• License

🎯 Why PdfDocument?

Generate PDFs without heavy dependencies. PdfDocument is a lightweight library that writes PDFs directly — no JNI, no C++ wrappers, no commercial licensing.

📦 Installation

NuGet

dotnet add package PdfDocument --version 1.0.0

Via direct reference (recommended for development)

git clone https://github.com/valdomirogalo/PdfDocument.git
cd PdfDocument
dotnet restore
dotnet build

Dependencies

The library requires only one NuGet package:

Note: The playground, tests and benchmark projects are excluded from the NuGet package (<IsPackable>false</IsPackable>).

⚡ Quick Start

1. Create a document with text and shapes

using PdfDocument;

using var pdf = new PdfBuilder();
var page = pdf.AddPage();
var canvas = page.Canvas;

canvas.DrawText("Hello, PDF!", 50, 700, 16);
canvas.DrawLine(50, 680, 400, 680);
canvas.DrawRectangle(50, 600, 200, 80);
canvas.FillRectangle(300, 600, 200, 80);

pdf.Save("example.pdf");

2. Add a table

var data = new string[,]
{
    { "Product", "Qty", "Price" },
    { "Item A", "10", "$50.00" },
    { "Item B", "5", "$25.00" },
};

canvas.DrawTable(data, 50, 500, new[] { 120.0, 80, 100 }, 24);

3. Generate a barcode

var bars = Code39.Generate("ABC-123");
canvas.DrawBarcode(bars, 50, 400, 1.5, 40);

4. Generate a DANFE/DACTE from fiscal XML (NFe or CTe)

using PdfDocument;
using PdfDocument.NFe;   // or PdfDocument.CTe

var factory = new PdfPluginFactory();

// One-step convenience method
factory.RegisterParser(new NFeParser());
factory.RegisterRenderer(new NFeRenderer());
factory.Generate("nfe.xml", "danfe.pdf");

// Or explicit two-step pipeline with decorators
factory.RegisterParser(new LoggingDataParser<NFeData>(new NFeParser(), Console.WriteLine));
factory.RegisterRenderer(new LoggingLayoutRenderer<NFeData>(new NFeRenderer(), Console.WriteLine));
var data = factory.Parse<NFeData>("nfe.xml");
factory.Render(data, "danfe.pdf");

🏗️ Architecture

PdfPluginFactory (Plugin Registry + Routing)
├── IDataParser<T>          ← Parsers: XML → IPdfData
│   ├── NFeParser            (PdfDocument.NFe)
│   └── CTeParser            (PdfDocument.CTe)
├── ILayoutRenderer<T>      ← Renderers: IPdfData → PDF
│   ├── NFeRenderer          (PdfDocument.NFe)
│   └── CTeRenderer          (PdfDocument.CTe)
└── Decorators (cross-cutting)
    ├── LoggingDataParser<T>
    └── LoggingLayoutRenderer<T>

PdfBuilder (Document)
├── PdfPage (Page)
│   └── PdfCanvas (Drawing area)
│       ├── DrawLine / DrawRectangle / FillRectangle
│       ├── DrawText / DrawTextAligned / DrawCell
│       ├── DrawGrid / DrawTable
│       ├── DrawImage (JPEG)
│       └── DrawBarcode
├── Code39 (Barcode generator)
├── EAN13 (Barcode generator)
└── Code128 (Barcode generator)

Plugin Pipeline

                     PdfPluginFactory
                    ┌──────────────────┐
  input.xml ───────▶│ parser.CanParse? │
                    │        │         │
                    │   parser.Parse() │──▶ IPdfData (CTeData / NFeData)
                    │        │         │
                    │ renderer.Render()│──▶ output.pdf (DACTE / DANFE)
                    └──────────────────┘

  Explicit two-step:
  var data = factory.Parse<CTeData>("cte.xml");   // typed intermediate
  factory.Render(data, "dacte.pdf");               // separate render step

PDF Generation Flow

C# Code     →  PdfCanvas (PDF command StringBuilder)
                    ↓
              PdfBuilder.Save()
                    ↓
           ┌────────┴────────┐
           │  PDF Objects    │
           │  (Font, Images, │
           │   Pages, Catalog)│
           └────────┬────────┘
                    ↓
           ┌────────┴────────┐
           │  xref table     │
           │  trailer        │
           └────────┬────────┘
                    ↓
              .pdf File

Memory Management

• Streaming: PdfBuilder.Save() writes directly to FileStream — no buffering of the entire PDF in memory
• Pre-allocated StringBuilder: PdfCanvas._cmds pre-allocated with 4096 capacity — fewer resizes
• ArrayPool buffers: EscapePdfString rents byte/char buffers from System.Buffers.ArrayPool — zero intermediate allocations per DrawText call
• No content duplication: Removed unused _objects dictionary that was storing every PDF object's content in memory (written but never read)
• No LOH allocations: All drawing operations use StringBuilder.AppendLine — no large temporary arrays
• ReadOnlySpan: EAN13 uses spans for digit validation — no Substring allocations
• c6g.large optimized: 2 vCPUs, 4 GB RAM — single-threaded, no parallel overhead, 512 KB image limit, 32K text limit

📚 API Reference

PdfBuilder — Main class

public sealed class PdfBuilder : IDisposable

PdfPage

PdfCanvas — Drawing surface

Coordinate system: The coordinate system is top-down (origin at top-left). y decreases as you go down the page.

🔢 Barcodes

Code 39

Full alphanumeric support (A-Z, 0-9, -.$/+%):

var bars = Code39.Generate("ABC-123");
canvas.DrawBarcode(bars, x, y, moduleWidth: 1.5, height: 40);

Features:

• Auto uppercase conversion
• Automatic * start/stop
• Inter-character gaps inserted automatically
• Bar widths: black = 3 modules, white = 1 module

EAN-13

// 12 digits → check digit auto-calculated
var bars = EAN13.Generate("789123456789");

// 13 digits → validation
var bars = EAN13.Generate("7891234567895");

Features:

• Accepts 12 digits (auto-calculation) or 13 digits (validation)
• Accepts hyphens and spaces as separators
• Automatic left (101), center (01010) and right (101) guards
• Uses ReadOnlySpan<char> for validation — zero extra allocations

🧾 DANFE / NFe · DACTE / CTe

Plugin Factory — Unified API

var factory = new PdfPluginFactory();

// Register plugins (programmatic or assembly scanning)
factory.RegisterParser(new NFeParser());
factory.RegisterRenderer(new NFeRenderer());
factory.RegisterParser(new CTeParser());
factory.RegisterRenderer(new CTeRenderer());

// Auto-routing: the factory discovers which parser to use via CanParse()
factory.Generate("nfe.xml", "danfe.pdf");   // → NFeParser + NFeRenderer
factory.Generate("cte.xml", "dacte.pdf");   // → CTeParser + CTeRenderer

// Explicit pipeline with decorators
factory.RegisterParser(new LoggingDataParser<CTeData>(new CTeParser(), Console.WriteLine));
var data = factory.Parse<CTeData>("cte.xml");   // typed CTeData
factory.Render(data, "dacte.pdf");               // separate render

NFeParser (NFe 4.00 XML)

var parser = new NFeParser();
if (parser.CanParse("nfe.xml"))
{
    NFeData data = parser.Parse("nfe.xml");
    // Returns NFeData with all fields:
    // - Identification (cUF, natOp, mod, serie, nNF, dhEmi...)
    // - Issuer (CNPJ, name, address, IE, CRT...)
    // - Recipient (CNPJ, name, address...)
    // - Product (code, description, NCM, CFOP, qty, price...)
    // - Totals (vBC, vICMS, vProd, vNF...)
    // - Carrier (CNPJ, name, IE, address...)
    // - Payment (method, amount)
}

CTeParser (CTe 3.00 XML)

var parser = new CTeParser();
if (parser.CanParse("cte.xml"))
{
    CTeData data = parser.Parse("cte.xml");
    // Returns CTeData with all fields:
    // - Identification (cUF, nCT, dhEmi, modal, tpServ...)
    // - Route (origin/destination municipalities)
    // - Issuer — transport company (CNPJ, IE, name, address)
    // - Sender (CPF/CNPJ, name, address)
    // - Recipient (CNPJ, IE, name, address)
    // - Cargo (product, quantity, value)
    // - Tax documents (type, number, date, value)
    // - Service values (total, received)
    // - ICMS tax (CST, Simples Nacional)
    // - Road transport (RNTRC)
}

NFeRenderer / CTeRenderer

var renderer = new CTeRenderer();
renderer.Render(data, "dacte.pdf");

Generates a complete DACTE/DANFE with:

• Header with document data
• Issuer, sender and recipient information
• Route (origin → destination) for CTe
• Cargo/document details
• Tax calculations
• Road transport info
• Additional observations

Enhanced DANFE (Playground)

The playground includes an enhanced layout that replicates the official DANFE format, including:

• Issuer logo in the header
• 44-digit access key
• Authorization protocol
• Complete product table
• Side-by-side tax layout
• Carrier section with volumes
• Additional data and complementary information

🎮 Playground

The samples/Playground project contains complete usage examples:

cd samples/Playground
dotnet run

Generates 6 sample PDFs: | File | Content | |------|---------| | exemplo_basico.pdf | Geometric shapes, grid, aligned cells | | exemplo_tabela.pdf | 4×4 table with header | | exemplo_barcode39.pdf | Code39 barcodes | | exemplo_ean13.pdf | EAN-13 barcodes | | exemplo_danfe.pdf | Simplified DANFE via NFeRenderer | | exemplo_danfe_enhanced.pdf | Official DANFE layout with logo |

⚡ Benchmarks

Measured with BenchmarkDotNet 0.14.0 · .NET 10.0.10 · AMD Ryzen 7 5700U · GC Workstation

PdfCanvas — Drawing operation throughput

PdfBuilder — Complete document generation

How to run

# Specific benchmark
dotnet run -c Release --project benchmarks/PdfDocument.Benchmarks -- 1

# All benchmarks
dotnet run -c Release --project benchmarks/PdfDocument.Benchmarks -- 6

Results saved to benchmarks/PdfDocument.Benchmarks/BenchmarkDotNet.Artifacts/results/.

🔧 Performance Optimizations

Based on dotnet-dump analysis (core dump from Playground sample on 2026-07-18), the following optimizations were implemented to reduce memory and prevent OOM in batch/high-throughput scenarios.

Improvements Applied

Memory Comparison: Before vs After (DrawText ASCII 1k)

Before:  458 KB allocated (byte[] + StringBuilder + char[] + string)
After:   290 KB allocated (string only + pooled buffers)
         └── 37% reduction in managed allocations

🧪 Tests

150 tests · xUnit · All passing ✅

dotnet test

Highlighted tests

• PDF character escaping: Verifies parentheses, backslashes and non-ASCII chars are properly escaped
• EAN-13 check digit: Cross-validation of check digit calculation with 13 provided digits
• Grid with invalid dimensions: Ensures DrawGrid with 0 columns/rows draws nothing
• Save with image: Verifies the saved PDF is valid with all expected components
• PDF injection prevention: Validates image names are rejected when containing dangerous characters
• Parse XML with missing fields: Parser resilience when XML lacks expected nodes
• Code128C barcode: Validates check digit, bar alternation, and digit filtering from mixed input

🔒 Security

CWE Coverage

Secure by Design

• ✅ No deserialization: Zero System.Text.Json or unsafe deserialization
• ✅ No logging: Library has zero ILogger, Console, or log statements (CWE-117 mitigated)
• ✅ XXE prevention: XmlReaderSettings.DtdProcessing = Prohibit in NFeParser (CWE-611 mitigated)
• ✅ PDF injection prevention: Image names validated [a-zA-Z0-9_-]+ (CWE-79 mitigated)
• ✅ OOB read prevention: JPEG SOF0 bounds check before dimension extraction (CWE-125 mitigated)
• ✅ Encoding control: Explicit WinAnsi (1252), no dependency on system default
• ✅ No string interpolation in exceptions: Static labels, user data as parameters
• ✅ No thread pool starvation: 100% synchronous execution (ideal for 2 vCPU c6g.large)

📐 Code Quality

Clean Code Practices

• ✅ No magic numbers: PdfConstants.cs centralizes all named constants (40+ constants)
• ✅ DRY: WriteIndirectObject eliminates repetition of offset recording
• ✅ DRY: IsValidPdfName shared between PdfBuilder.AddImage and PdfCanvas.DrawImage
• ✅ DRY: DrawInfoLine, DrawSection eliminate repetition in DANFE renderer
• ✅ Single Responsibility: Each class has a clear responsibility
• ✅ Null Safety: Nullable enabled, ArgumentNullException.ThrowIfNull on all public APIs
• ✅ XML Documentation: All public classes and methods documented with <summary>
• ✅ Primary constructors: PdfPage uses primary constructor syntax (IDE0290)
• ✅ Early Return: Early exit pattern with no nested else blocks
• ✅ ReadOnlySpan: EAN13 uses spans to avoid Substring allocations

Error Handling

📁 Project Structure

PdfDocument/
├── PdfDocument.slnx                          # .NET 10 Solution
├── README.md                                 # This file
├── LICENSE                                   # MIT License
│
├── src/PdfDocument/                          # 📚 Core library (NuGet 1.0.0)
│   ├── PdfDocument.csproj                    #   Target: net10.0
│   ├── PdfDocument.cs                        #   PdfBuilder — PDF construction
│   ├── PdfPage.cs                            #   Individual page
│   ├── PdfCanvas.cs                          #   Drawing canvas (shapes, text, tables, barcode)
│   ├── PdfConstants.cs                       #   Named constants + IsValidPdfName
│   ├── PdfPluginFactory.cs                   #   Plugin registry: Parse<T>() + Render<T>() + Generate()
│   ├── IDataParser.cs                        #   Interface: XML → IPdfData
│   ├── ILayoutRenderer.cs                    #   Interface: IPdfData → PDF
│   ├── IPdfData.cs                           #   Marker interface for data models
│   ├── Bar.cs                                #   Barcode bar struct
│   ├── Code39.cs                             #   Code 39 generator
│   ├── EAN13.cs                              #   EAN-13 generator
│   ├── Code128.cs                            #   Code 128 generator
│   └── Decorators/                           #   Cross-cutting concerns
│       ├── LoggingDataParser.cs              #   Logging decorator for IDataParser<T>
│       └── LoggingLayoutRenderer.cs          #   Logging decorator for ILayoutRenderer<T>
│
├── src/PdfDocument.NFe/                      # 🧾 NFe plugin (NuGet PdfDocument.NFe)
│   ├── PdfDocument.NFe.csproj                #   Target: net10.0
│   ├── NFeConstants.cs                       #   DANFE layout constants
│   ├── NFeData.cs                            #   Data model (record, implements IPdfData)
│   ├── NFeParser.cs                          #   XML NFe 4.00 parser (XXE-safe, XDocument)
│   └── NFeRenderer.cs                        #   DANFE PDF renderer
│
├── src/PdfDocument.CTe/                      # 🚛 CTe plugin (NuGet PdfDocument.CTe)
│   ├── PdfDocument.CTe.csproj                #   Target: net10.0
│   ├── CTeConstants.cs                       #   DACTE layout constants
│   ├── CTeData.cs                            #   Data model (record, implements IPdfData)
│   ├── CTeParser.cs                          #   XML CTe 3.00 parser (XXE-safe, XDocument)
│   ├── CTeRenderer.cs                        #   DACTE PDF renderer
│   └── Sample/                               #   Sample CTe XML and reference PDF
│
├── samples/Playground/                       # 🎮 Usage examples (IsPackable=false)
│   ├── Playground.csproj
│   └── Program.cs                            #   6 complete demos
│
├── tests/PdfDocument.Tests/                  # 🧪 Unit tests (150) (IsPackable=false)
│   ├── PdfDocument.Tests.csproj              #   xUnit + coverlet
│   ├── PdfCanvasTests.cs                     #   25 tests
│   ├── Code39Tests.cs                        #   9 tests
│   ├── EAN13Tests.cs                         #   12 tests
│   ├── Code128Tests.cs                       #   13 tests
│   ├── PdfDocumentTests.cs                   #   18 tests
│   ├── PdfConstantsTests.cs                  #   12 tests
│   ├── NFeParserTests.cs                     #   19 tests
│   ├── NFeRendererTests.cs                   #   5 tests
│   └── DanfeValidationTests.cs               #   37 tests
│
└── benchmarks/PdfDocument.Benchmarks/        # ⚡ Performance benchmarks (IsPackable=false)
    ├── PdfDocument.Benchmarks.csproj         #   BenchmarkDotNet 0.14.0
    ├── Program.cs                            #   Interactive CLI (1-6)
    ├── BenchConstants.cs
    ├── PdfCanvasBenchmarks.cs                #   13 drawing benchmarks
    ├── Code39Benchmarks.cs                   #   Params: 1 to 50 chars
    ├── EAN13Benchmarks.cs                    #   6 scenarios
    ├── NFeParserBenchmarks.cs                #   Full parse + missing fields
    └── PdfBuilderBenchmarks.cs               #   7 full document scenarios

🔄 Roadmap

• Basic drawing operations (lines, rectangles, text)
• Tables with header and data
• Code 39 and EAN-13 barcodes
• Code 128 barcodes
• JPEG image insertion
• Plugin architecture (IDataParser<T> + ILayoutRenderer<T> + PdfPluginFactory)
• NFe XML parser (4.00) + DANFE rendering
• CTe XML parser (3.00) + DACTE rendering
• Logging decorators for parser and renderer pipelines
• Unit tests (150)
• Performance benchmarks
• Official DANFE layout with logo
• NuGet packaging (v1.0.0)
• Security audit (CWE-125, CWE-611, CWE-79, CWE-117, CWE-770)
• CodePages encoding fix (eliminated exception on first DrawText call)
• Memory optimizations (ArrayPool, removed _objects leak, XDocument, HashSet)
• TrueType font (TTF) support
• Page rotation support
• PDF/A support
• Async API for large documents

⚖️ License

MIT License — Free to use, modify, distribute, and incorporate into any project (commercial or not).

MIT License

Copyright © 2026 Valdomiro Galo

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

<div align="center"> _{Made with 💜 by <a href="https://github.com/valdomirogalo">Valdomiro Galo</a>} </div>