Change Request: Improve Form Field Handling When Merging PDFs

[cbra-nbb]

Background

When merging multiple PDFs that contain form fields (AcroForms) using PDFsharp, field names are not automatically deduplicated. As noted by @ThomasHoevel in #264, this is because all form fields in a single PDF must have unique names, and currently, PDFsharp leaves it up to consumer code to ensure uniqueness.

However, in many real‑world scenarios (such as combining externally provided contracts or forms), developers may not have prior knowledge of the field names used in the source documents and cannot reliably enforce uniqueness themselves, especially since PDFsharp does not expose public setters for altering form field names.

Problem Statement

• When combining PDFs with overlapping form field names, the resulting document in Adobe Reader will only show form fields from the first input file.

• This behavior makes merged forms unusable in common PDF viewers like Adobe Reader, even though some viewers (e.g., Microsoft Edge’s PDF viewer) still display all form fields.

• Because PDFsharp currently offers no API for renaming or deduplicating conflicting field names, developers cannot easily work around this limitation.

Proposed Change / Feature Request

Introduce built‑in support in PDFsharp for handling non‑unique form field names when merging PDFs. Possible approaches:

1. Automatic renaming: Provide an option during merging that ensures all field names from different documents are made unique (e.g., by prefixing with the source file name or page number).

2. API for renaming fields: Expose setters or utility methods that make it possible for client code to rename fields during or after merging.

3. Merge behavior options: Allow developers to specify merge strategies (keep first occurrence, rename duplicates, fail with explicit exception, etc.).

Expected Outcome

Developers can merge any two PDFs with form fields, whether or not there are name collisions, and end up with a valid PDF where all fields are visible and editable in Adobe Reader, Edge, and other major PDF viewers.

Benefits

• Makes PDFsharp more robust for document automation scenarios.

• Reduces the need for complex pre‑processing of PDFs outside PDFsharp.

• Provides consistency across different PDF viewers.