Doc Properties update TOC page numbering changes

Aspose.Words Product Family
1

Hi Team,

We are using the Doc properties update extensively and it works really well.

but for few cases we see some challenges which causes some issue.

the document table of content is getting changed after the doc properties are performed.

2

@Sai_Prasad

Why the TOC becomes wrong

A Table of Contents in a Word document is built from field codes (TOC, PAGE, NUMPAGES, …).
When you change a document property (Title, Author, a custom property, etc.) the text that is inserted can change the length of a paragraph, which in turn changes pagination.

Aspose.Words does not automatically:

  1. Re‑layout the document – i.e., recalculate page breaks.
  2. Refresh the fields – i.e., re‑evaluate the TOC and any page‑number fields.

If you skip either step the TOC will show stale page numbers.

Solution (Java & .NET)

  1. Update the document properties.
  2. Force a layout pass – updatePageLayout().
  3. Update the fields – updateFields() (or update only the TOC fields).
  4. Save the document in the required format.

Both updatePageLayout() and updateFields() are required for a correct TOC.

Java (Aspose.Words)

import com.aspose.words.*;

public class UpdatePropertiesAndToc {
    public static void main(String[] args) throws Exception {
        // 1. Load the document
        Document doc = new Document("Input.docx");

        // 2. Change built‑in and custom properties
        doc.getBuiltInDocumentProperties().setTitle(
                "A very long title that changes pagination");
        doc.getCustomDocumentProperties().add("ProjectId", 12345);

        // 3. Re‑layout the document (re‑calculate page breaks)
        doc.updatePageLayout();          // needed for PAGE / NUMPAGES fields

        // 4. Refresh all fields (TOC, PAGE, NUMPAGES, cross‑references, …)
        doc.updateFields();

        // 5. Save the result (any format you need)
        doc.save("Output.docx");                     // Word
        // doc.save("Output.pdf");                  // PDF
        // doc.save("Output.html",
        //          SaveOptions.createSaveOptions(SaveFormat.HTML)); // HTML
    }
}

If you only want to update the TOC fields:

for (Field field : doc.getRange().getFields()) {
    if (field.getType() == FieldType.FIELD_TOC) {
        field.update();
    }
}

C# (.NET, Aspose.Words)

using Aspose.Words;

class UpdatePropertiesAndToc
{
    static void Main()
    {
        // 1. Load the document
        Document doc = new Document("Input.docx");

        // 2. Change properties
        doc.BuiltInDocumentProperties.Title = 
            "A new title that changes layout";
        doc.CustomDocumentProperties.Add("ProjectId", 12345);

        // 3. Re‑layout pages
        doc.UpdatePageLayout();

        // 4. Refresh fields (TOC, PAGE, NUMPAGES, …)
        doc.UpdateFields();

        // 5. Save
        doc.Save("Output.docx");   // Word
        // doc.Save("Output.pdf"); // PDF
        // doc.Save("Output.html"); // HTML
    }
}

Update only the TOC:

foreach (Field field in doc.Range.Fields)
{
    if (field.Type == FieldType.FieldTOC)
        field.Update();
}

Frequently asked questions

Question Answer
Do I need both UpdatePageLayout and UpdateFields? Yes. UpdatePageLayout recomputes pagination; UpdateFields refreshes the TOC and any page‑number fields that depend on that pagination.
I only need the TOC, not other fields. Iterate through doc.Range.Fields (Java) or doc.Range.Fields (C#) and call field.Update() only for FieldType.FIELD_TOC.
What about converting to PDF/HTML? Perform the two steps before calling doc.Save(..., SaveFormat.Pdf) or SaveFormat.Html. The generated file will contain the correct page numbers.
Will this hurt performance on large files? Both methods are O(N). If performance is a concern, limit the scope to the TOC field only.
Is there an automatic “always update fields” switch? No. Aspose.Words requires an explicit call so you can decide when layout and field evaluation happen.

TL;DR

1. Change the document property.
2. doc.updatePageLayout();   // Java / doc.UpdatePageLayout();   // C#
3. doc.updateFields();       // Java / doc.UpdateFields();       // C#
4. Save the document.

Executing these steps guarantees that the Table of Contents reflects the correct page numbers after any modification to document properties.

3

@Sai_Prasad Could you please attach your problematic input and output documents along with a simple code that will allow us to reproduce the problem on our side? We will check the issue and provide you more information.

4

Hi Alexy,

will provide the file soon as it is confidential. trying to get a dummy file for this issue.

5

@Sai_Prasad Thank you for additional information. We will wait from your inputs. Please note, it is safe to attach documents in the forum. Only you as a topic starter and Aspose staff can access the attachments.