devexpress-office-file-api-pdf-new

name	devexpress-office-file-api-pdf-new
description	Create, load, modify, secure, and print PDF documents using the new DevExpress.Docs.Pdf API — a modern object-oriented DOM approach for .NET. Use when building .NET applications that need to programmatically generate or edit PDF files using the new DevExpress PDF Document API (CTP). Also use when someone mentions "DevExpress.Docs.Pdf", "new PDF API", "PdfDocument class", "pdf fragment", "pdf pages collection", "pdf form fields", "pdf redaction", "pdf structure tree", "tagged pdf", "pdf/ua", "pdf encryption", "pdf annotations new API", or asks to migrate from PdfDocumentProcessor to the new API. Covers both .NET and .NET Framework.
metadata	{"author":"DevExpress","version":"26.1","source-commit":"d4a70c0b5f39f3c991dd5ee8fa51f2d413ef26b6","status":"CTP"}

DevExpress New PDF Document API (CTP)

[!IMPORTANT] Community Technology Preview (CTP) The DevExpress.Docs.Pdf library is currently available as a CTP. Do not use it in mission-critical production applications. Try the library, share feedback, and await the official release. The legacy DevExpress.Pdf (PdfDocumentProcessor) API remains fully supported.

The new DevExpress PDF Document API (DevExpress.Docs.Pdf) is a cross-platform .NET library with a strongly-typed, object-oriented document model. It lets you create, load, modify, save, print, encrypt, and structurally tag PDF documents. The entry point is PdfDocument, which exposes pages, fragments, annotations, form fields, metadata, structure tree, and attachments as first-class typed collections. Works on Windows, Linux, and macOS.

When to Use This Skill

• Create new PDF documents with text, images, shapes, and reusable templates
• Load and modify existing PDF files (edit content, add/remove pages, manage annotations)
• Manage interactive forms: create, fill, flatten, import/export AcroForm data
• Find, format, redact, or permanently remove text from PDF documents
• Encrypt PDF documents and set granular permissions (print, modify, extract)
• Build tagged/accessible PDFs (PDF/UA) using the structure tree API
• Merge PDF documents or reorganize pages (clone, reorder, rotate, resize)
• Embed file attachments or ZUGFeRD/Factur-X electronic invoice XML
• Print PDFs cross-platform (Windows, Linux/macOS via CUPS)
• Migrate existing code from PdfDocumentProcessor to the new PdfDocument API

Prerequisites & Installation

CTP Warning: This package is a pre-release. Pin to the exact v26.1 version to avoid unexpected changes.

NuGet Packages

Package	Purpose
DevExpress.Docs.Pdf	New PDF Document API (CTP)

.NET (6/7/8+)

dotnet add package DevExpress.Docs.Pdf

.NET Framework (4.7.2+)

Install-Package DevExpress.Docs.Pdf

Or add DLL references: DevExpress.Docs.Pdf.v26.1.dll, DevExpress.Data.v26.1.dll, DevExpress.Drawing.v26.1.dll, DevExpress.Printing.v26.1.Core.dll, DevExpress.Office.v26.1.Core.dll, DevExpress.Docs.Core.v26.1.dll.

Important: All DevExpress packages in a project must share the same version. A valid DevExpress license is required.

Before You Start — Ask the Developer

Before generating code, confirm the following:

General

1. Target framework: .NET 8+, .NET 6/7, or .NET Framework 4.x?
2. New or existing project?: Creating fresh or adding to an existing codebase?
3. Hosting model: Console, ASP.NET Core, Blazor, WinForms, WPF, background service?
4. CTP acknowledgement: Has the developer confirmed they understand this is a pre-release library?

PDF-Specific

5. Operation: Create new document, load and modify existing, merge, extract text, fill forms, or secure?
6. Content types needed: Text, images, shapes, form fields, annotations, redaction, structure tree?
7. Security requirements: Encryption, permissions, password protection?
8. Output: Save to file, stream, or print?

Rule: If the developer's answer is ambiguous, ask before generating code. Do not guess.

Component Overview

The new PDF API provides:

• Document Model (PdfDocument): Central object — pages, fields, metadata, structure tree, attachments, encryption
• Page Content (Page, FragmentCollection): Add/inspect/modify text, images, shapes via typed fragment objects
• Annotations (Page.Annotations): Typed annotation classes — FreeTextAnnotation, RedactionAnnotation, TextAnnotation, LinkAnnotation, and more
• Interactive Forms (PdfDocument.Fields): Create and fill TextBoxField, CheckBoxField, RadioGroupField, ListBoxField, ComboBoxField, SignatureField
• Search & Redaction (PdfDocument.FindText, ApplyRedaction): Find text, format matches, permanently redact regions
• Structure Tree (PdfDocument.StructureTree): Build tagged PDFs for PDF/UA accessibility compliance
• Security (PdfDocument.Encrypt): AES-128/AES-256 encryption with granular permission flags

Core Entry Point

using DevExpress.Docs.Pdf;
using DevExpress.Drawing.Printing;

// Create new document
using var doc = new PdfDocument();
Page page = doc.Pages.Add(DXPaperKind.A4);
page.AddTextFragment(new TextFragment { Text = "Hello", Location = new PointF(50, 770) });
doc.Save(new FileStream("output.pdf", FileMode.Create));

// Load existing document
using var existing = new PdfDocument(File.OpenRead("input.pdf"));
// ... modify pages, annotations, fields ...
existing.Save(new FileStream("modified.pdf", FileMode.Create));

Documentation & Navigation Guide

Getting Started

📄 references/getting-started.md

When you need to:

• Install and configure the library for the first time
• Create your first PDF document with text and images
• Understand the coordinate system (bottom-left origin, points)
• See a complete multi-page working example

Add Content to Pages

📄 references/add-content.md

When you need to:

• Add text (single-line or multiline/wrapped) to a PDF page
• Add images in BMP, JPEG, PNG, EMF, TIFF, SVG formats
• Draw shapes and lines using PathFragment
• Create reusable page templates (FormTemplate / FormFragment)

Organize Pages

📄 references/organize-pages.md

When you need to:

• Add, insert, reorder, clone, or remove pages
• Copy pages from one document to another
• Rotate, resize, scale, or offset page content
• Merge PDF documents by appending pages

Interactive Form Fields

📄 references/form-fields.md

When you need to:

• Create text boxes, checkboxes, radio buttons, list boxes, combo boxes, or signature fields
• Fill, read, or flatten form fields
• Import/export AcroForm data (FDF, XFDF, XML, TXT)
• Group form fields or apply value formatting

Search, Edit & Redact Text

📄 references/search-replace-redact.md

When you need to:

• Find text in a PDF document
• Format search results (change font, color, bold)
• Permanently redact matched text regions
• Remove text or clear content from rectangular areas

Security & Encryption

📄 references/security.md

When you need to:

• Encrypt a PDF with user and owner passwords (AES-128/AES-256)
• Set granular permissions (print, modify, extract, interact)
• Open and inspect encrypted documents
• Remove encryption from a document

Structure Tree (Tagged PDF / PDF/UA)

📄 references/structure-tree.md

When you need to:

• Create accessible tagged PDFs with a logical structure tree
• Map custom tags to standard PDF roles
• Validate a structure tree for PDF/UA compliance
• Edit or remove elements from an existing document's structure

Metadata and Attachments

📄 references/metadata-attachments.md

When you need to:

• Read or write standard PDF document properties (Title, Author, Subject, Keywords)
• Work with XMP metadata schemas
• Embed file attachments in a PDF
• Attach a ZUGFeRD/Factur-X electronic invoice XML

Annotations

📄 references/annotations.md

When you need to:

• Add sticky notes, text highlights, underlines, or free text annotations
• Create watermark annotations or rubber stamps (static, dynamic, custom)
• Add link annotations (URL, page navigation, cross-document)
• Create drawing annotations (circle, square, line, ink)
• Search and edit existing annotations by type or author
• Remove annotations (and their threaded replies)
• Add comments (AddReply) or reviews (AddReview, ReviewStatus) to annotations
• Customize annotation appearance (border, color, cloudy effect)

Migration from Legacy API

📄 references/migration.md

When you need to:

• Migrate from PdfDocumentProcessor / DevExpress.Pdf to PdfDocument / DevExpress.Docs.Pdf
• Map old annotation/field/encryption types to new equivalents
• Understand side-by-side namespace coexistence

Quick Start Example

using DevExpress.Docs.Pdf;
using DevExpress.Drawing;
using DevExpress.Drawing.Printing;
using System.Drawing;

// Create a multi-page PDF report
using (PdfDocument pdfDocument = new PdfDocument()) {
    // Page 1: Title and text
    Page page1 = pdfDocument.Pages.Add(DXPaperKind.A4);

    page1.AddTextFragment(new TextFragment {
        Text = "Quarterly Sales Report",
        Location = new PointF(50, 770),
        Font = new TextFont("Arial", TextFontStyle.Bold),
        FontSize = 24
    });

    page1.AddTextFragment(new TextFragment {
        Text = "This report summarizes Q1 2026 sales data.",
        Location = new PointF(50, 730),
        Font = new TextFont("Arial"),
        FontSize = 12
    });

    // Add a logo image
    DXImage logo = DXImage.FromFile("logo.png");
    page1.AddImageFragment(new ImageFragment(logo) {
        Location = new PointF(50, 600),
        Size = new SizeF(200, 100)
    });

    // Page 2: Data
    Page page2 = pdfDocument.Pages.Add(DXPaperKind.A4);
    page2.AddTextFragment(new TextFragment {
        Text = "North America: $1,250,000",
        Location = new PointF(50, 730),
        Font = new TextFont("Arial"),
        FontSize = 12
    });

    // Save
    using (FileStream fs = File.Create("SalesReport.pdf"))
        pdfDocument.Save(fs);
}

Key Properties & API Surface

PdfDocument

Member	Type	Description
Pages	PageCollection	Mutable page collection — add, insert, remove, clone
Fields	FormFieldCollection	All AcroForm fields
StructureTree	StructureTree	Logical structure for tagged PDFs
Metadata	DocumentMetadata	DocumentInfo + XmpMetadata
Attachments	collection	Embedded file attachments
AccessMode	enum	Access level of currently opened document
FindText(string, TextSearchOptions, int, int)	IEnumerable<TextSearchInfo>	Find text across page range
RemoveText(IEnumerable<TextSearchInfo>)	void	Remove found text permanently
ApplyRedaction(int, RedactionAnnotation[])	void	Permanently apply redaction annotations
ClearContent(int, List<OrientedRectangle>, ...)	void	Clear content in rectangular regions
Encrypt(EncryptionOptions)	void	Encrypt with AES-128/256 and permissions
RemoveEncryption()	void	Remove document encryption
AppendDocument(PdfDocument)	void	Append another PDF's pages
Print(PrintOptions)	void	Print cross-platform
Save(Stream)	void	Save to stream

Page

Member	Type	Description
Fragments	FragmentCollection	All content fragments (text, images, shapes)
Annotations	PageAnnotationCollection	All page annotations
Width, Height	double	Page dimensions in points
Rotation	PageRotationAngle	Page rotation (Clockwise90, etc.)
AddTextFragment(TextFragment)	void	Add text content
AddImageFragment(ImageFragment)	void	Add image content
AddPathFragment(PathFragment)	void	Add shape/line content
AddFormFragment(FormFragment)	void	Add reusable template
Clone()	Page	Deep-copy this page
Resize(RectangleF, H, V)	void	Resize page with alignment
RotateContent(double, double, double)	void	Rotate content around a point
ScaleContent(double, double)	void	Scale content X/Y
OffsetContent(double, double)	void	Translate content X/Y

Common Patterns

Pattern 1: Load, Modify, and Save

using DevExpress.Docs.Pdf;

using (PdfDocument doc = new PdfDocument(File.OpenRead("input.pdf"))) {
    // Add a watermark to every page
    for (int i = 0; i < doc.Pages.Count; i++) {
        doc.Pages[i].AddTextFragment(new TextFragment {
            Text = "DRAFT",
            Location = new PointF(150, 400),
            FontSize = 72,
            RotationAngle = 45,
            ForegroundFill = new SolidFill(PdfColor.Red, 0.2f)
        });
    }
    doc.Save(new FileStream("output.pdf", FileMode.Create));
}

Pattern 2: Encrypt with Permissions

using DevExpress.Docs.Pdf;

using (PdfDocument doc = new PdfDocument(File.OpenRead("report.pdf"))) {
    var opts = new EncryptionOptions("ownerPass", "userPass") {
        Algorithm = EncryptionAlgorithm.AES256,
        PrintPermissions = DocumentPrintPermissions.LowQuality,
        ModificationPermissions = DocumentModificationPermissions.NotAllowed
    };
    doc.Encrypt(opts);
    doc.Save(new FileStream("report_secured.pdf", FileMode.Create));
}

Pattern 3: Find and Redact Sensitive Text

using DevExpress.Docs.Pdf;
using System.Linq;

using (PdfDocument doc = new PdfDocument(
    new FileStream("document.pdf", FileMode.Open, FileAccess.ReadWrite))) {
    var results = doc.FindText("CONFIDENTIAL",
        new TextSearchOptions(true, false), 0, doc.Pages.Count - 1);
    foreach (var result in results) {
        var annotations = result.Matches
            .Select(m => new RedactionAnnotation(RectangleF.Empty) {
                Geometry = new RedactionGeometry(
                    m.MatchFragments.Select(f => f.Rectangle).ToArray()),
                FillColor = PdfColor.Black,
                OverlayText = "REDACTED"
            }).ToArray();
        doc.ApplyRedaction(result.PageIndex, annotations);
    }
    doc.Save(new FileStream("document_redacted.pdf", FileMode.Create));
}

Troubleshooting

Symptom	Cause	Solution
InvalidOperationException on save after encrypt	Saving to same stream used for load	Save to a new FileStream with FileMode.Create
Text not visible at expected coordinates	Coordinate origin is bottom-left, Y increases upward	Invert Y: for A4 (841.89 pts high), Y=770 is near top
PdfDocument ctor throws on encrypted file	No password provided	Use new PdfDocument(stream, new LoadOptions { Password = "..." })
Redaction doesn't remove underlying content	ApplyRedaction not called after creating annotation	Call doc.ApplyRedaction(pageIndex, annotations) to commit
Missing type TextFont	Namespace not imported	Add using DevExpress.Docs.Office;
Build error: missing assembly	Wrong NuGet package	Install DevExpress.Docs.Pdf, not DevExpress.Document.Processor
Form fields not visible in reader	Widget annotation not bound to page	Add the widget to page.Annotations after creating it
License error at runtime	Missing DevExpress license	Register license key per DevExpress installation guide

Constraints & Rules

CRITICAL — follow these rules in every interaction:

1. CTP status: Always inform the developer this library is a CTP. Do not recommend it for production mission-critical use.
2. Build verification: After changes, verify with dotnet build before reporting success.
3. Coordinate system: PDF origin is bottom-left. Y increases upward. A4 is 595.28 × 841.89 pts (72 pts = 1 inch).
4. Stream ownership: Open streams with appropriate FileAccess. Save to a separate output stream, not the input stream.
5. Redaction is permanent: ApplyRedaction cannot be undone. Warn developers before applying.
6. Version consistency: All DevExpress packages must share the same version.
7. Namespace clarity: New API is DevExpress.Docs.Pdf. Legacy is DevExpress.Pdf. Do not mix in the same file without aliases.
8. Framework detection: Check .csproj target framework before writing code.

Using DevExpress Documentation MCP

If the DxDocs MCP server is available, use it to supplement this skill:

• Search: devexpress_docs_search with technology "PDF Document API" or "New PDF Document API".
• Fetch: devexpress_docs_get_content with a documentation URL to retrieve full article content.

Use MCP for: advanced annotation types not listed here, XMP metadata schemas, ZUGFeRD invoice setup, ParagraphFragment multiline text, exact enum values, or any API not covered in these references.

---

Next Steps

Start with Getting Started to install and create your first PDF. Then explore features through the navigation guide above.