PdfForge.Core 2.0.0

PdfForge.Core — Enterprise PDF Generation Engine

Proprietary Closed-Source Software
30-day free trial + Perpetual licensing model.
See LICENSE.md and SUPPORT.md for licensing details.

A high-performance, multi-tenant PDF generation engine for enterprise SaaS platforms. Built with .NET 10.0+, designed for scale, security, and extensibility.

Table of Contents

• About
• Features
• Getting Started
• Configuration
• Security
• Release Notes
• What's Next
• Licensing
• License
• Support

About

PDF Forge solves the challenge of generating high-quality PDFs in enterprise SaaS environments where:

• Multi-tenancy is critical for data isolation and compliance
• Performance directly impacts user experience (sub-second PDF generation)
• Security is non-negotiable (decompression bombs, injection attacks, timing attacks)
• Reliability means 99.9%+ uptime with comprehensive testing

The engine converts multiple formats (HTML, Word, Excel, images, text) into production-grade PDFs while maintaining strict tenant boundaries and security standards.

Where it fits:

• SaaS platforms requiring PDF generation
• Enterprise document management systems
• Automated reporting pipelines
• Batch processing workflows with webhooks

Features

Core Capabilities

• HTML to PDF — Render complex web layouts (HtmlRenderer.RenderHtmlToPdf), with configurable page size, orientation, and margins via HtmlRenderOptions
• Per-page HTML headers/footers — AddHtmlHeader/AddHtmlFooter, targeting specific page indices, with {page}/{totalPages} substitution
• Word (DOCX) to PDF — Preserve formatting and styles
• Excel (XLSX) to PDF — Multi-sheet support with optional horizontal pagination
• Image to PDF — With bounds checking
• Image stamping — ImageStamper places a logo/signature image on specific pages of an existing PDF at a real-world position (points, inches, or millimeters via Length)
• Text to PDF — Simple text rendering
• Template Rendering — Reusable document templates
• Batch Processing — High-volume document generation
• Webhooks — Job completion notifications

Working with existing PDFs

• LoadedPdfDocument — one entry point for inspecting and extending a PDF you didn't generate with this library (page count/sizes/fonts via PdfInspector, plus form-fill/flatten, watermark, image-stamp, and append-generated-pages helpers). Note: this is a metadata + byte[]-transform wrapper, not a fully mutable re-parsed object graph — see the class doc comment for why.
• PDF merging/splitting — PdfMerger.Merge/Append/ExtractPages, PdfSplitter
• AcroForm fill/read/flatten — PdfFormFiller.Fill/ReadFields/Flatten for existing forms (text, check box, and radio fields); AcroFormBuilder for building a new form from scratch
• Watermarking — PdfWatermarker.Apply, with position/rotation/opacity/scale and per-watermark page scoping (all pages, first page only, all-except-first)

Enterprise Features

• Multi-Tenant Isolation — AsyncLocal ambient context, thread-safe
• High Performance — Object pooling, caching, async/await
• Zero third-party dependencies — no headless-browser process to launch/sandbox (unlike Chromium-based renderers); the only external package is Microsoft's own System.Security.Cryptography.Pkcs
• Security Hardening — JPEG bomb prevention, key rotation, constant-time validation
• Observability — Correlation IDs for distributed tracing
• Comprehensive Testing — 1750+ unit tests
• Scalability — Horizontal scaling ready

Architecture

High-Level Design

┌─────────────────────────────────────────────────────────────┐
│                    API Layer (REST/gRPC)                     │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│ │ TenantScope  │  │ CorrelationID│  │ ResourceLimits   │   │
│ │ (Context)    │  │ (Tracing)    │  │ (DoS Protection) │   │
│ └──────────────┘  └──────────────┘  └──────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│ ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│ │ HTML       │  │ Word       │  │ Excel      │  ...        │
│ │ Converter  │  │ Converter  │  │ Converter  │             │
│ └────────────┘  └────────────┘  └────────────┘             │
├─────────────────────────────────────────────────────────────┤
│ ┌────────────────┐  ┌────────────┐  ┌────────────┐         │
│ │ Font Manager   │  │ Layout     │  │ Graphics   │         │
│ │                │  │ Engine     │  │ Renderer   │         │
│ └────────────────┘  └────────────┘  └────────────┘         │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────────┐  ┌──────────────┐  ┌────────────┐     │
│ │ MemoryStreamPool │  │ CssCache     │  │ TextLayout │     │
│ │ (Performance)    │  │ (Performance)│  │ Cache      │     │
│ └──────────────────┘  └──────────────┘  └────────────┘     │
├─────────────────────────────────────────────────────────────┤
│           PDF Writer & Storage Layer                         │
└─────────────────────────────────────────────────────────────┘

Design Patterns

• Multi-Tenant: AsyncLocal<T> for ambient context isolation
• Performance: Object pooling + LRU caching at hot paths
• Security: Layered validation (input sanitization, bounds checking, rate limiting)
• Observability: Correlation IDs flowing through async call chains
• Extensibility: Plugin architecture with interfaces

Getting Started

Installation

dotnet add package PdfForge.Core

Requirements: .NET 10.0+ SDK

Quick Start

using PdfForge;
using PdfForge.Logging;

// 1. Setup DI
var services = new ServiceCollection();
services.AddPdfForge(new PdfForgeOptions 
{ 
    StorageRootPath = "/tmp/pdfs" 
});
var provider = services.BuildServiceProvider();

// 2. Create document
var doc = provider.GetRequiredService<PdfDocument>();
var page = new PdfPage(PdfRectangle.Letter);
doc.AddPage(page);

// 3. Write PDF
await doc.WriteToFileAsync("output.pdf", CancellationToken.None);

HTML to PDF

using PdfForge.Html;
using PdfForge.Fonts;
using PdfForge.Layout;
using PdfForge.Pdf;

var fontManager  = new FontManager();
var layoutEngine = new LayoutEngine(fontManager.GetFont("Helvetica", 12));
var renderer     = new HtmlRenderer(fontManager, layoutEngine);

var doc = new PdfDocument();
renderer.RenderHtmlToPdf(doc,
    "<html><body><h1>Invoice #1042</h1><p>Thank you for your business.</p></body></html>",
    new HtmlRenderOptions { PaperSize = PdfRectangle.A4, MarginTop = 20 });

// Optional: recurring header/footer, e.g. letterhead + page numbers
renderer.AddHtmlHeader(doc, "<p>Acme Corp — Confidential</p>");
renderer.AddHtmlFooter(doc, "<p>Page {page} of {totalPages}</p>");

await doc.WriteToFileAsync("invoice.pdf", CancellationToken.None);

Working with an existing PDF

using PdfForge.Pdf;
using PdfForge.Watermark;

var loaded = LoadedPdfDocument.Load(File.ReadAllBytes("contract.pdf"));

byte[] filled      = loaded.FillForm(new Dictionary<string, string> { ["ClientName"] = "Jane Doe" });
byte[] watermarked = loaded.ApplyWatermark([new WatermarkDescriptor { Text = "DRAFT", Opacity = 0.3 }]);

Samples

Runnable sample projects are in the samples/ directory:

• HtmlBarcodeBatchSample — 4-page HTML template rendering, barcode overlay, batch generation (55 records), merged PDF output
• NuGetPackageValidationSample — Validates consuming PdfForge.Core as a NuGet package

# HTML + barcode batch sample (default)
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj

# All options & fixes demo
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj -- --all-options

# Word document sample
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj -- --word-test

# Excel sample
dotnet run --project samples/HtmlBarcodeBatchSample/HtmlBarcodeBatchSample.csproj -- --excel-test

# NuGet package consumption validation
dotnet run --project samples/NuGetPackageValidationSample/NuGetPackageValidationSample.csproj

Configuration

Environment Variables

# Storage configuration
PDFFORGE_STORAGE_PATH=/data/pdfs
PDFFORGE_CACHE_SIZE=1000

# Logging
PDFFORGE_LOG_LEVEL=Information
PDFFORGE_ENABLE_TRACING=true

# Performance
PDFFORGE_POOL_MIN_SIZE=4
PDFFORGE_POOL_MAX_SIZE=64
PDFFORGE_CACHE_ENTRIES=1000

Startup Configuration

var options = new PdfForgeOptions
{
    StorageRootPath = Environment.GetEnvironmentVariable("PDFFORGE_STORAGE_PATH"),
    MaxCacheSize = int.Parse(
        Environment.GetEnvironmentVariable("PDFFORGE_CACHE_SIZE") ?? "1000"
    )
};

services.AddPdfForge(options);

Resource Limits

// Per-tenant configuration
var limits = JobResourceLimits.CreateForProfessionalTier(
    maxOutputPages: 1000,
    maxJobDuration: TimeSpan.FromMinutes(5),
    maxMemory: 512 * 1024 * 1024  // 512 MB
);

services.AddSingleton(limits);

Security

Built-In Protections

Security Best Practices

1. Secrets Management

   // Use secure configuration, not hardcoded keys
   var apiKey = configuration["Security:ApiKey"];  // From env/vault
   

2. Input Validation

   var sanitized = InputSanitizer.SanitizeHtml(userInput);
   

3. Tenant Isolation

   using (new TenantScope(tenantContext))
   {
       // All operations automatically isolated
   }
   

4. Audit Logging

   logger.LogInformation(
       "PDF generated for tenant {TenantId}: {DocumentId}",
       tenantId, documentId
   );
   

Compliance

• OWASP Top 10 considerations implemented
• Audit logging for all operations
• Data isolation for multi-tenant compliance
• Full security details: docs/SECURITY-IMPLEMENTATION.md

Release Notes

See CHANGELOG.md for the full release history.

What's Next

Upcoming (Q3 2026)

• Advanced font subsetting
• Enhanced image optimization
• Plugin framework v2
• GraphQL API support

Roadmap

See ROADMAP.md for detailed product roadmap and timelines.

Known Limitations

• Maximum document size: 10GB (design constraint)
• Concurrent jobs per tenant: 100 (configurable)
• LoadedPdfDocument reads metadata and applies transforms (merge/form-fill/watermark/image-stamp) to an existing PDF's bytes, but does not re-parse it into a fully mutable object graph — PdfDocument remains a write-oriented model for building new PDFs. This covers the common cases (fill an existing form, watermark, stamp a logo, append newly generated pages) without the cost/risk of a full PDF parser.
• PdfMerger refuses (with a clear error, not corrupted output) to merge a source PDF that uses PDF 1.5+ cross-reference streams or object streams unless MergeOptions.AllowBestEffortOnModernPdf is explicitly set, since that path can't yet losslessly re-link every reference.
• The merge/form-fill/flatten/watermark/image-stamp utilities patch existing PDF bytes directly (locating objects and dictionary keys textually) rather than through a full parsed object model — this is intentionally lightweight, but PDFs with heavily obfuscated or unusually structured object dictionaries are more likely to be left unmodified than to be corrupted.

Licensing

PdfForge is proprietary closed-source software with a commercial licensing model:

30-Day Free Trial

• All features enabled
• No watermark
• No credit card required
• Watermark appears after day 30 (unless licensed)

Perpetual License

• Valid forever (no renewal)
• One-time payment
• All features included
• Commercial use allowed

Purchase: Email rdaforge@gmail.com
Questions: See SUPPORT.md

License

Proprietary Commercial License — See LICENSE for full legal terms.

This software is NOT open source. Source code is proprietary and not publicly available.

Key terms:

• Use PdfForge.Core NuGet package in your projects (with valid license)
• Distribute applications that use PdfForge
• Cannot modify, reverse-engineer, or access source code
• Cannot redistribute NuGet binaries without a valid license

For licensing inquiries: LICENSE.md | SUPPORT.md

Support

PDF Forge

• Email: rdaforge@gmail.com
• Documentation: GitHub Repository
• Security Concerns: Report privately to rdaforge@gmail.com
• Issue Reporting: Contact rdaforge@gmail.com

Last Updated: June 29, 2026
Status: Production Ready