DocumentUpdateFields Method

Updates the values of fields in the whole document.

Namespace:  Aspose.Words
Assembly:  Aspose.Words (in Aspose.Words.dll) Version: 20.7.0

Syntax

public void UpdateFields()

Remarks

When you open, modify and then save a document, Aspose.Words does not update fields automatically, it keeps them intact. Therefore, you would usually want to call this method before saving if you have modified the document programmatically and want to make sure the proper (calculated) field values appear in the saved document.

There is no need to update fields after executing a mail merge because mail merge is a kind of field update and automatically updates all fields in the document.

This method does not update all field types. For the detailed list of supported field types, see the Programmers Guide.

This method does not update fields that are related to the page layout algorithms (e.g. PAGE, PAGES, PAGEREF). The page layout-related fields are updated when you render a document or call UpdatePageLayout.

Use the NormalizeFieldTypes method before fields updating if there were document changes that affected field types.

To update fields in a specific part of the document use UpdateFields.

Examples

Shows to use the QUOTE field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a QUOTE field, which will display content from the Text attribute
FieldQuote field = (FieldQuote)builder.InsertField(FieldType.FieldQuote, true);
field.Text = "\"Quoted text\"";

Assert.AreEqual(" QUOTE  \"\\\"Quoted text\\\"\"", field.GetFieldCode());

// Insert a QUOTE field with a nested DATE field
// DATE fields normally update their value to the current date every time the document is opened
// Nesting the DATE field inside the QUOTE field like this will freeze its value to the date when we created the document
builder.Write("\nDocument creation date: ");
field = (FieldQuote)builder.InsertField(FieldType.FieldQuote, true);
builder.MoveTo(field.Separator);
builder.InsertField(FieldType.FieldDate, true);

Assert.AreEqual(" QUOTE \u0013 DATE \u0014" + DateTime.Now.Date.ToShortDateString() + "\u0015", field.GetFieldCode());

// Some field types don't display the correct result until they are manually updated
Assert.AreEqual(string.Empty, doc.Range.Fields[0].Result); 

doc.UpdateFields();

Assert.AreEqual("\"Quoted text\"", doc.Range.Fields[0].Result);

doc.Save(ArtifactsDir + "Field.QUOTE.docx");
Shows how to set user details and display them with fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Set user information
UserInformation userInformation = new UserInformation();
userInformation.Name = "John Doe";
userInformation.Initials = "J. D.";
userInformation.Address = "123 Main Street";
doc.FieldOptions.CurrentUser = userInformation;

// Insert fields that reference our user information
Assert.AreEqual(userInformation.Name, builder.InsertField(" USERNAME ").Result);
Assert.AreEqual(userInformation.Initials, builder.InsertField(" USERINITIALS ").Result);
Assert.AreEqual(userInformation.Address, builder.InsertField(" USERADDRESS ").Result);

// The field options object also has a static default user value that fields from many documents can refer to
UserInformation.DefaultUser.Name = "Default User";
UserInformation.DefaultUser.Initials = "D. U.";
UserInformation.DefaultUser.Address = "One Microsoft Way";
doc.FieldOptions.CurrentUser = UserInformation.DefaultUser;

Assert.AreEqual("Default User", builder.InsertField(" USERNAME ").Result);
Assert.AreEqual("D. U.", builder.InsertField(" USERINITIALS ").Result);
Assert.AreEqual("One Microsoft Way", builder.InsertField(" USERADDRESS ").Result);

doc.UpdateFields();
doc.Save(ArtifactsDir + "FieldOptions.FieldOptionsCurrentUser.docx");
Shows how to insert a Table of contents (TOC) into a document using heading styles as entries.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table of contents at the beginning of the document,
// and set it to pick up paragraphs with headings of levels 1 to 3 and entries to act like hyperlinks
builder.InsertTableOfContents("\\o \"1-3\" \\h \\z \\u");

// Start the actual document content on the second page
builder.InsertBreak(BreakType.PageBreak);

// Build a document with complex structure by applying different heading styles thus creating TOC entries
// The heading levels we use below will affect the list levels in which these items will appear in the TOC,
// and only levels 1-3 will be picked up by our TOC due to its settings
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading1;
builder.Writeln("Heading 1");

builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading2;
builder.Writeln("Heading 1.1");
builder.Writeln("Heading 1.2");

builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading1;
builder.Writeln("Heading 2");
builder.Writeln("Heading 3");

builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading2;
builder.Writeln("Heading 3.1");

builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading3;
builder.Writeln("Heading 3.1.1");
builder.Writeln("Heading 3.1.2");
builder.Writeln("Heading 3.1.3");

builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading2;
builder.Writeln("Heading 3.2");
builder.Writeln("Heading 3.3");

// Call the method below to update the TOC and save
doc.UpdateFields();
doc.Save(ArtifactsDir + "DocumentBuilder.InsertToc.docx");

See Also