Update Fields

What is this page about?

This page explains how to update fields in a Word document programmatically.

Typically, a field inserted into Microsoft Word already contains an up to date value. For example, if the field is a formula or a page number, it will contain the correct calculated value for the given version of the document. But if you have an application that generates or modifies a document with fields like merging two documents or populating it with data, then ideally all fields must be updated for the document to be useful.

How to Update Fields

When a document is loaded, Aspose.Words mimics the behavior of Microsoft Word with the option to automatically update fields is switched off. The behavior can be summarized as follows:

when you open/save a document the fields remain intact
you can explicitly update all fields in a document, for example, rebuild TOC, when you need to
when you print/render to PDF or XPS the fields related to page-numbering in headers/footers are updated
when you execute Mail Merge all fields are updated automatically

Update Fields Programmatically

To explicitly update fields in the whole document, simply call the UpdateFields method. To update fields contained in part of a document, obtain a Range object and call the UpdateFields method. In Aspose.Words, you can obtain a Range for any node in the document tree, such as Section, HeaderFooter , Paragraph, etc. using the Node.Range property. You can update the result of a single field by calling the Update method.

When you execute conversion of a document to a fixed-page format e.g. to PDF or XPS, then Aspose.Words will automatically update page layout-related fields PAGE, PAGEREF found in headers/footers of the document. This behavior mimics the behavior of Microsoft Word when printing a document.

If you want to update all other fields in the document, then you need to call UpdateFields before rendering the document.

The following code example shows how to update all fields before rendering a document:

You can download the sample file of this example from Aspose.Words GitHub.

Automatic Field Update During Mail Merge

When you execute a mail merge, all fields in the document will be automatically updated. This is because the Mail Merge is a case of a field update. The program encounters a Mail Merge field and needs to update its result, which involves grabbing the value from the data source and inserting it into the field. The logic is of course more complicated, for example, when the end of the document/mail merge region is reached but there is still further data to be merged, then the region needs to be duplicated and the new set of fields updated.

Update Fields Having Dirty Attribute

The w:dirty is a field-level attribute that will refresh only the field you specify when the document is opened. It tells MS Word to only refresh this field the next time the document is opened. You can use the UpdateDirtyFields property to specify whether to update the fields with the dirty attribute. When the value of UpdateDirtyFields is set to true, all fields having true value for Field.IsDirty or FieldChar.IsDirty property are updated on document load.

The following code example shows how to update fields having the dirty attribute:

Update LastSavedTime Property Before Saving

You can use the UpdateLastSavedTimeProperty property whether to update the corresponding built-in document property LastSavedTime when saving the document.

The following code example shows how to update this property:

FAQ

Q: How can I update all fields in a document using Aspose.Words for .NET?
A: Load the document, call Document.UpdateFields(), and then save or render it. This updates every field, including TOC, formulas, and references.
```
Document doc = new Document("input.docx");
doc.UpdateFields();               // Updates all fields in the document
doc.Save("output.docx");
```

Q: How do I update fields only in a specific part of a document, such as a header or a section?
A: Obtain the node that represents the part you want to update, get its Range, and call Range.UpdateFields(). This updates fields only within that range.

Document doc = new Document("input.docx");
HeaderFooter header = (HeaderFooter)doc.FirstSection.HeadersFooters[HeaderFooterType.HeaderPrimary];
header.Range.UpdateFields();      // Updates fields only in the header
doc.Save("output.docx");

Q: Will page‑number fields be updated automatically when converting a document to PDF or XPS?
A: Yes. During rendering to a fixed‑page format, Aspose.Words automatically updates page‑related fields (PAGE, PAGEREF, etc.) found in headers and footers. If you also need other fields updated, call Document.UpdateFields() before rendering.
```
Document doc = new Document("input.docx");
doc.UpdateFields();               // Optional: update non‑page fields
doc.Save("output.pdf");           // Page fields are refreshed automatically
```
Q: How can I update fields that have the dirty attribute when loading a document?
A: Set LoadOptions.UpdateDirtyFields to true when creating the Document. This forces Aspose.Words to refresh all fields marked as dirty on load.
```
LoadOptions loadOptions = new LoadOptions
{
    UpdateDirtyFields = true
};
Document doc = new Document("input.docx", loadOptions);
doc.Save("output.docx");
```
Q: How do I ensure the LastSavedTime property is updated when saving a document?
A: Use SaveOptions.UpdateLastSavedTimeProperty and set it to true before calling Save. This updates the built‑in LastSavedTime property to the current time.
```
Document doc = new Document("input.docx");
SaveOptions saveOptions = new SaveOptions
{
    UpdateLastSavedTimeProperty = true
};
doc.Save("output.docx", saveOptions);
```

Customize Field Properties in C# Remove Fields C#