Cracking the Code: Working with PDF Forms in .NET
PDF forms come in two major formats and managing them programmatically requires understanding the difference between them, the workflows that connect them, and the tools that make those workflows reliable. This tutorial walks through three of the most important forms operations you can perform with the Adobe PDF Library Forms Extension: converting XFA forms to AcroForms, importing and exporting form data, and flattening forms for broad compatibility. All examples are in C# using the .NET SDK.
The complete sample code for each section is available in the Datalogics GitHub repository: apdfl-csharp-dotnet-samples/Forms.
Who Is This For?
This tutorial is written for developers building or maintaining systems that process PDF forms at scale. That includes document management platforms, government or healthcare intake workflows, insurance claim processing pipelines, and any application that receives completed forms from end users and needs to extract, normalize, or archive that data.
XFA and AcroForms: Why Both Exist and Why It Matters
AcroForms is the original PDF forms standard and remains the current standard under PDF 2.0. XFA (XML Forms Architecture) was developed by Adobe as a more powerful alternative, capable of dynamic layouts and complex validation logic. However, XFA was deprecated in PDF 2.0 and is not supported in ISO compliance formats such as PDF/A. Google Chrome, Firefox, and most mobile PDF viewers do not render XFA documents at all.
If your application receives documents from the field, there is a reasonable chance some of them are XFA forms. Leaving them as XFA means they may be invisible to the majority of your users' software. Converting them to AcroForms is the correct long-term approach.
Converting XFA Forms to AcroForms
When to Use This
Use XFA-to-AcroForm conversion when you receive XFA documents from external sources and need to process them with standard PDF tools, render them in browsers, display them on mobile devices, or archive them in PDF/A format. It is also the right step before any downstream form data extraction.
What the Code Does
The ConvertXFAToAcroForms sample opens an XFA document, calls a single conversion method, and saves the result. The key setup is initializing the library with Forms Extension support and allowing XFA documents to open:
using (Library lib = new
Library(LibraryFlags.InitFormsExtension))
{
if (!lib.IsFormsExtensionAvailable())
{
Console.Out.WriteLine("Forms
Plugins were not properly loaded!");
return;
}
lib.AllowOpeningXFA = true;
using (Document doc = new Document(sInput))
{
UInt32 pagesOutput =
doc.ConvertXFAFieldsToAcroFormFields();
Console.WriteLine("XFA document
was converted into an AcroForms document with {0} pages.", pagesOutput);
doc.Save(SaveFlags.Full |
SaveFlags.Linearized, sOutput);
}
}
The Library must be initialized with LibraryFlags.InitFormsExtension, or the Forms Extension methods will not be available. Setting AllowOpeningXFA = true is also required, as APDFL defaults to legacy behavior that blocks XFA files from opening. Once the document is open, ConvertXFAFieldsToAcroFormFields does the work and returns the number of pages output, which is useful for validation logging.
Expected Output
The output is a standard AcroForms PDF that renders correctly in Chrome, Adobe Reader, mobile viewers, and any other PDF-compliant software. The visual appearance of the form is preserved. Form fields become interactive AcroForm fields that can be filled, extracted, or further processed.
Sample: ConvertXFAToAcroForms.cs on GitHub
Importing and Exporting Form Data
When to Use This
Form data import and export is useful when the data needs to travel separately from the visual document. A completed form submitted as an XML or XFDF data file can be imported back into the original PDF to view the data in context. Conversely, you can export the data from a filled form into a smaller file for database ingestion, archival, or transmission to another system without sending the entire PDF.
Exported files are significantly smaller than the full PDF, which matters when distributing completed forms across systems or storing large volumes of submissions.
Importing Data into XFA Documents
The ImportFormsData sample handles both XFA and AcroForms documents. For XFA documents, the data file is typically in XDP format. The import call specifies the data file path and the library handles mapping the data to the correct fields:
using (Document doc = new
Document(sInput))
{
bool result =
doc.ImportXFAFormsData(sInputData);
if (result)
doc.Save(SaveFlags.Full |
SaveFlags.Linearized, sOutput);
}
Importing Data into AcroForms Documents
For AcroForms documents, data is typically in XFDF format. The import call includes an explicit type parameter so the library knows how to parse the incoming file:
bool result =
doc.ImportAcroFormsData(sInputData, AcroFormImportType.XFDF);
The type parameter accepts XFDF, FDF, and XML. Choosing the wrong type will cause the import to fail silently, so matching the type to the actual file format is important.
Exporting Form Data
The ExportFormsData sample mirrors the import workflow. For XFA documents, the export format is XDP. For AcroForms, it is XFDF:
// XFA export
bool result =
doc.ExportXFAFormsData(sOutput, XFAFormExportType.XDP);
// AcroForms export
bool result =
doc.ExportAcroFormsData(sOutput, AcroFormExportType.XFDF);
Expected Output
Import produces a filled PDF where each form field contains the imported data value. Export produces a compact data file (XDP or XFDF) containing only the field names and their submitted values. These output files are human-readable XML and can be parsed by any standard XML library.
Samples: ImportFormsData.cs and ExportFormsData.cs on GitHub
Flattening PDF Forms
When to Use This
Form flattening converts interactive form fields into static page content. The resulting document looks identical to the filled form but contains no editable fields. Use flattening when archiving completed forms, preparing documents for printing, delivering finalized documents to recipients who should not modify them, or when downstream systems cannot handle interactive form fields.
Flattening is also the correct approach when XFA documents need to be processed by software that does not support XFA. Unlike conversion to AcroForms, flattening produces a document with no form fields at all, which guarantees compatibility with any PDF viewer.
What the Code Does
The FlattenForms sample handles both XFA and AcroForms in the same program. For XFA documents, FlattenXFAFormFields expands the dynamic XFA content into static PDF pages. For AcroForms, FlattenAcroFormFields converts each field's current value into fixed page text:
// Flatten XFA
using (Document doc = new
Document(sInput))
{
UInt32 pagesOutput =
doc.FlattenXFAFormFields();
Console.WriteLine("XFA document was
expanded into {0} Flattened pages.", pagesOutput);
doc.Save(SaveFlags.Full |
SaveFlags.Linearized, sOutput);
}
// Flatten AcroForms
using (Document doc = new
Document(sInput))
{
doc.FlattenAcroFormFields();
Console.WriteLine("AcroForms document
was Flattened.");
doc.Save(SaveFlags.Full |
SaveFlags.Linearized, sOutput);
}
Note that AllowOpeningXFA = true must be set before opening XFA documents, just as with the conversion sample. Forgetting this step results in an error when the document is opened.
Expected Output
The output is a standard PDF with no interactive elements. All form field values appear as static text on the page. The document renders identically in all PDF viewers and can be printed, archived, or embedded in other documents without compatibility concerns.
Sample: FlattenForms.cs on GitHub
Additional Forms Capabilities
The Forms Extension includes additional capabilities beyond what is covered in this tutorial. These include reading individual field values and properties, programmatically setting field values before flattening, working with digital signatures on forms, and handling forms within PDF portfolios. The Datalogics GitHub repository contains additional samples covering these use cases.
Prefer a Command-Line Tool?
If your workflow calls for batch flattening without writing application code, the Datalogics PDF Forms Flattener command-line tool handles XFA and AcroForms flattening without requiring SDK integration.
Get Started
The Forms Extension is an add-on to the Adobe PDF Library. Start a free trial today.