Xref table expose by vafle228 · Pull Request #1292 · UglyToad/PdfPig

vafle228 · 2026-05-12T08:31:47Z

Description

This PR addresses a long-standing limitation for developers needing to implement incremental PDF updates (e.g., for digital signatures, form filling, or appending objects without full re‑saving). Currently, the PdfDocument.Structure exposes limited low‑level access, because the CrossReferenceTable (old property) is missing, and the core token writer lacks support for writing a custom xref table with /Prev trailer.

The changes in this PR restore and extend the low-level API to fully support reading and writing both normal xref tables and xref streams, as well as working with trailer dictionaries. This makes it possible to:

Access the raw CrossReferenceTablePart entries (object number, offset, generation, type).
Read/write the trailer dictionary (including /Prev, /Size, /Root, /Info).
Append new objects while keeping the original xref section intact.
Implement full incremental PDF update workflows.

Changes Made

CrossReferenceTable is now fully exposed via PdfDocument.Structure.CrossReferenceTable
(previously it was removed). It provides:
- ObjectOffsets – mapping from IndirectReference to XrefLocation.
- Parts - single instance of xref table
TrailerDictionary now exposes /Prev, /Size, /Root, /Info (and all raw dictionary entries).

TokenWriter has been extended with a new method:

public void WriteCrossReferenceTable(
    IReadOnlyDictionary<IndirectReference, long> objectOffsets,
    IndirectReference catalogToken,
    Stream outputStream,
    IndirectReference? documentInformationReference,
    long? prevTableLocation);   // 👈 new parameter for incremental save

Added AdvancedMerge.cs example of low level tools usage

- Also uncommented old tests

BobLd

you can also un-comment the asserts in PdfMergerTests

BobLd · 2026-05-13T17:25:13Z

-        public IReadOnlyDictionary<IndirectReference, long> ObjectOffsets { get; }
+        public IReadOnlyDictionary<IndirectReference, XrefLocation> ObjectOffsets { get; }

        public long Offset { get; private set; }


no need for private set;, read only

BobLd · 2026-05-13T17:30:36Z

    public class CrossReferenceTable
    {
-        private readonly Dictionary<IndirectReference, long> objectOffsets;
+        private readonly List<CrossReferenceTablePart> parts;


Change to CrossReferenceTablePart[], no need for a list from what I see

BobLd · 2026-05-13T17:31:40Z

-            foreach (var objectOffset in objectOffsets)
+            this.objectOffsets = objectOffsets.ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
+            
+            var result = new List<CrossReferenceOffset>();


Use a CrossReferenceOffset[] instead

BobLd · 2026-05-13T17:33:42Z

+            for (var i = 1; i < parts.Count; i++)
            {
-                result[objectOffset.Key] = objectOffset.Value;
+                result.Add(new CrossReferenceOffset(parts[i].Offset, parts[i - 1].Previous));


can you double check that it should not be the below instead:

foreach (var part in parts) { result.Add(new CrossReferenceOffset(part.Offset, part.Previous)); }

Thank for that

BobLd · 2026-05-13T17:42:49Z

I have review your PR, let me know if any question, great job!

BobLd · 2026-05-13T17:48:04Z

Also, review AdvancedMerge and make sure it's referenced into Program.cs

vafle228 · 2026-05-14T08:04:31Z

@BobLd Thank you for the review! I’ve applied all the suggested changes:

Replaced Empty() method with static readonly Empty field.
Removed unnecessary private set; from read‑only properties.
Changed List<CrossReferenceTablePart> to array.
Simplified CrossReferenceOffset creation logic using foreach.
Verified AdvancedMerge is now referenced in Program.cs for the samples.

Could you please take another look when you have time? Thanks again!

BobLd

Can you also review the AdvanceMerge example? It produces a blank page. Can you also add this example as an integration test, if possible?

BobLd · 2026-05-16T14:22:22Z

+                        using var output = new FileStream(Path.Combine(filesDirectory, "AdvancedMergeResult.pdf"), FileMode.Create);
+                        using var input = File.Open(Path.Combine(filesDirectory, "Single Page Simple - from google drive.pdf"), FileMode.Open);
+
+                        input2.CopyToAsync(output);


input2.CopyToAsync(output); is not awaited, input2.CopyTo(output); should be enough

BobLd · 2026-05-16T14:26:28Z

        /// <param name="catalogToken">The object representing the catalog dictionary which is referenced from the trailer dictionary.</param>
        /// <param name="outputStream">The output stream to write to.</param>
        /// <param name="documentInformationReference">The object reference for the document information dictionary if present.</param>
+        /// /// <param name="prevTableLocation">The offset to the previous xref table if present</param>


duplicate ///

BobLd · 2026-05-16T14:34:40Z

+                    () =>
+                    {
+                        using var input2 = File.Open(Path.Combine(filesDirectory, "EmptyPdf.pdf"), FileMode.Open);
+                        using var output = new FileStream(Path.Combine(filesDirectory, "AdvancedMergeResult.pdf"), FileMode.Create);


let's not write the output document to the integration tests folder. new FileStream("AdvancedMergeResult.pdf") should be enough

BobLd · 2026-05-16T14:58:45Z

@vafle228 I've added some more comments, let me know if any question. Can you also add an integration test based on AdvanceMerge? Thanks again

- Also added nice property for calculating Prev

vafle228 · 2026-05-18T07:55:42Z

@BobLd Thank you for the new comments! My bad with the AdvancedMerge.cs example. I forgot to link resources, so readers couldn't render the content properly. I fixed this in the last two commits. Also I added the integration test, as you asked for. Let me know if there are any issues left.

BobLd · 2026-05-18T17:43:35Z

note to self:

Trailer-merging semantics changed silently. The deleted builder special-cased /Size so a linearized PDF's first trailer wins. The new FirstPassParser walks all parts and prefers the dictionary that has /Root. This is reasonable but is a behavior change, worth a targeted test on a linearized file to confirm /Size hasn't regressed.

vafle228 added 5 commits May 10, 2026 15:35

Added prev to trailer dictionary

fc4ec96

Trailer dictionary expose

378426b

CrossReferenceTable final expose

c72d8d4

- Also uncommented old tests

Added AdvancedMerge example

7775d69

Added content logic here too

446deba

vafle228 mentioned this pull request May 12, 2026

Reintroduce CrossReferenceTable / expose low-level xref and trailer access for incremental updates #1289

Closed

BobLd requested changes May 13, 2026

View reviewed changes

vafle228 added 2 commits May 14, 2026 11:08

Review fix

70eb343

Extend example (also add into Program.cs)

b881402

vafle228 requested a review from BobLd May 14, 2026 08:02

BobLd requested changes May 16, 2026

View reviewed changes

vafle228 added 2 commits May 18, 2026 10:41

Fixed example

67e0fa5

Integration test

3aca79a

- Also added nice property for calculating Prev

vafle228 requested a review from BobLd May 18, 2026 07:40

Summary

9976249

BobLd approved these changes May 18, 2026

View reviewed changes

BobLd merged commit b2e2337 into UglyToad:master May 18, 2026
2 checks passed

Uh oh!

Conversation

vafle228 commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes Made

Uh oh!

BobLd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BobLd commented May 13, 2026

Uh oh!

BobLd commented May 13, 2026

Uh oh!

vafle228 commented May 14, 2026

Uh oh!

BobLd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BobLd commented May 16, 2026

Uh oh!

vafle228 commented May 18, 2026

Uh oh!

BobLd commented May 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vafle228 commented May 12, 2026 •

edited

Loading