What's New in Document Solutions for Word v9

Document Solutions for Word (DsWord) v9.1 expands support for Word field updates and improves accessible PDF export. This release adds the ability to update LISTNUM, AUTONUM, AUTONUMLGL, and AUTONUMOUT fields, while also enhancing PDF export with structure tags for better accessibility and standards compliance.

Together, these updates help developers generate more accurate numbered documents and produce tagged PDFs that more closely match Microsoft Word’s own export behavior. Whether the goal is to maintain complex numbering schemes in contracts and technical documents or create PDF/A- and PDF/UA-ready output, DsWord v9.1 makes those workflows easier to automate.

Update LISTNUM Field

DsWord v9.1 adds support for updating LISTNUM fields, which are used to continue or retrieve numbering from a specific level of a numbering definition. This is especially useful in documents such as contracts, legal files, and structured technical content where numbering must continue correctly across paragraphs, tables, and other layout elements.

The main API addition is the new ListNumFieldOptions class, which lets developers work with LISTNUM field settings such as the list name, level, and starting value. LISTNUM fields are now included in the normal field update process, so calling UpdateFields() calculates and refreshes their displayed values automatically.

// LISTNUM-fields can be used to increment the numbers of your “main” numbering scheme.
// For example, let’s assume you have a typical contract structure with a title 1., a sublevel 1.1, etc.
GcWordDocument doc = new GcWordDocument();

// create a new list template
string listName = "MyList";
ListTemplate listTemplate = doc.ListTemplates.Add(BuiltInListTemplateId.OutlineLegal, listName);
// and use it to number paragraphs in the contract
Paragraph p = doc.Body.AddParagraph("SCOPE");
p.ListFormat.Template = listTemplate;
p.ListFormat.LevelNumber = (int)OutlineLevel.Level1;
p = doc.Body.AddParagraph("The Licensor grants to the Licensee an exclusive, transferable, sublicensable, remunerated, worldwide License to exploit the Software for the Term and the specific purpose set forth in this License Agreement.");
p.ListFormat.Template = listTemplate;
p.ListFormat.LevelNumber = (int)OutlineLevel.Level2;
p = doc.Body.AddParagraph("The Licensor hereby grants to the Licensee this License to use the Licensed Products. It is understood and agreed that the License shall pertain only to the Licensed Products.");
p.ListFormat.Template = listTemplate;
p.ListFormat.LevelNumber = (int)OutlineLevel.Level2;
// For some business reason you now want to insert paragraphs inside of a table that continues the “main numbering”.
// You can do so by including LISTNUM fields in the left column of the table.
p = doc.Body.AddParagraph("If the contract is signed by the customer before January 1st, 2025, then also the following will apply:");
// create options for LISTNUM fields
ListNumFieldOptions options = new ListNumFieldOptions(doc);
options.Name = listName;
options.Level = 2;
// create a table 
Table table = doc.Body.AddTable(new string[][]
{
    new string[] { "Optional clause nr." , "Optional clause content" },
    new string[] { null, "The Licensee may grant sublicenses free of charges to customers in France." },
    new string[] { null, "If at least 500 orders are submitted, the Licensee may also grant sublicenses to customers in Denmark." },
}, doc.Styles[BuiltInStyleId.GridTable1Light]);
// format header with style
table.Format.StyleOptions |= TableStyleOptions.FirstRow;
// including LISTNUM fields in the left column
table[1, 0].GetRange().Paragraphs.First.GetRange().ComplexFields.Add(options);
table[2, 0].GetRange().Paragraphs.First.GetRange().ComplexFields.Add(options);
// continue numbering in a general way
p = doc.Body.AddParagraph("The Licensee may grant any sublicenses to any third party without the prior express written consent of the Licensor which may be withheld for any reason.");
p.ListFormat.Template = listTemplate;
p.ListFormat.LevelNumber = (int)OutlineLevel.Level2;
// calculate LISTNUM fields values
doc.UpdateFields();
doc.Save(@"listnum.docx");

Help | Demo

Update AUTONUM, AUTONUMLGL, and AUTONUMOUT Fields

DsWord v9.1 also adds support for updating the legacy AUTONUM, AUTONUMLGL, and AUTONUMOUT fields. These fields are older Word numbering features used for sequential numbering, legal-style numbering, and outline-style numbering, and are still important for compatibility with existing Word documents.

To support these scenarios, DsWord introduces the new AutoNumFieldOptions, AutoNumLglFieldOptions, and AutoNumOutFieldOptions classes. These fields are now included in the field update pipeline, so developers can insert them, call UpdateFields(), and have the numbering results calculated correctly in the document. Although these field types are considered obsolete by Word, supporting them helps preserve compatibility with older document workflows.

// AUTONUM, AUTONUMLGL, and AUTONUMOUT field examples combined into one sample.
void AddHeadingWithField(GcWordDocument doc, string text, BuiltInStyleId styleId, FieldOptionsBase options)
{
    Paragraph p = doc.Body.AddParagraph(text, doc.Styles[styleId]);
    p.GetRange().ComplexFields.Insert(options, InsertLocation.Start);
}
// AUTONUM
{
    GcWordDocument doc = new GcWordDocument();
    // Create options to insert AUTONUM fields in the document.
    AutoNumFieldOptions options = new AutoNumFieldOptions(doc);
    // Create a structure of paragraphs with different outline levels
    // and insert AUTONUM fields at the beginning of each paragraph
    // to automatically number them.
    AddHeadingWithField(doc, "Heading 1", BuiltInStyleId.Heading1, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    AddHeadingWithField(doc, "Heading 3", BuiltInStyleId.Heading3, options);
    AddHeadingWithField(doc, "Heading 3", BuiltInStyleId.Heading3, options);
    AddHeadingWithField(doc, "Heading 1", BuiltInStyleId.Heading1, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    // Calculate AUTONUM field values.
    doc.UpdateFields();
    doc.Save(@"autonum.docx");
}
// AUTONUMLGL
{
    GcWordDocument doc = new GcWordDocument();

    // Create options to insert AUTONUMLGL fields in the document.
    AutoNumLglFieldOptions options = new AutoNumLglFieldOptions(doc);

    // Create a structure of paragraphs with different outline levels
    // and insert AUTONUMLGL fields at the beginning of each paragraph
    // to automatically number them.
    AddHeadingWithField(doc, "Heading 1", BuiltInStyleId.Heading1, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    AddHeadingWithField(doc, "Heading 3", BuiltInStyleId.Heading3, options);
    AddHeadingWithField(doc, "Heading 3", BuiltInStyleId.Heading3, options);
    AddHeadingWithField(doc, "Heading 1", BuiltInStyleId.Heading1, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    // Calculate AUTONUMLGL field values.
    doc.UpdateFields();
    doc.Save(@"autonumlgl.docx");
}
// AUTONUMOUT
{
    GcWordDocument doc = new GcWordDocument();
    // Create options to insert AUTONUMOUT fields in the document.
    AutoNumOutFieldOptions options = new AutoNumOutFieldOptions(doc);
    // Create a structure of paragraphs with different outline levels
    // and insert AUTONUMOUT fields at the beginning of each paragraph
    // to automatically number them.
    AddHeadingWithField(doc, "Heading 1", BuiltInStyleId.Heading1, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    AddHeadingWithField(doc, "Heading 3", BuiltInStyleId.Heading3, options);
    AddHeadingWithField(doc, "Heading 3", BuiltInStyleId.Heading3, options);
    AddHeadingWithField(doc, "Heading 1", BuiltInStyleId.Heading1, options);
    AddHeadingWithField(doc, "Heading 2", BuiltInStyleId.Heading2, options);
    // Calculate AUTONUMOUT field values.
    doc.UpdateFields();
    doc.Save(@"autonumout.docx");
}

Help | Demo

Structure Tags for PDF Export

DsWord v9.1 improves PDF export by adding support for structure tags, making it easier to generate tagged PDFs with better accessibility and navigation support. Previous versions wrapped paragraphs with only basic paragraph tagging, while this update adds richer structural information similar to Word’s own PDF export, including heading recognition, image alternative text, and hyperlink screen tips.

This behavior is controlled through PdfOutputSettings, primarily with ExportStructureTags and MarkAsPdfUa. Developers can also provide placeholder values such as MissingDocumentTitle, MissingShapeAlternativeText, and MissingHyperlinkScreenTip when validating incomplete documents during development. With this enhancement, DsWord can more easily participate in workflows targeting PDF/A or PDF/UA compliance, provided the source document is prepared correctly.

using GrapeCity.Documents.Word;
using GrapeCity.Documents.Word.Layout;

DocToPdfUa("SimpleDocument");
DocToPdfA("SimpleDocument");
// mark the exported document as PDF/UA compliant
static void DocToPdfUa(string name)
{
    var doc = new GcWordDocument();
    doc.Load($"{name}.docx");
    using var wl = new GcWordLayout(doc);
    var settings = new PdfOutputSettings
    {
        ExportStructureTags = true,
        MarkAsPdfUa = true,
        MissingDocumentTitle = "(no title)",
        MissingShapeAlternativeText = "(no alternative text)",
        MissingHyperlinkScreenTip = "(no content)"
    };
    wl.SaveAsPdf($"{name}PdfUa.pdf", null, settings);
}
// mark the exported document as PDF/A compliant
static void DocToPdfA(string name)
{
    var doc = new GcWordDocument();
    doc.Load($"{name}.docx");
    using var wl = new GcWordLayout(doc);
    var settings = new PdfOutputSettings
    {
        ExportStructureTags = true,
        MissingDocumentTitle = "(no title)"
    };
    wl.SaveAsPdf($"{name}PdfA.pdf", null, settings);
}

With support for LISTNUM and legacy automatic numbering fields, plus richer structure tags in PDF export, DsWord v9.1 improves both document automation and accessible publishing workflows.

Help | Demo

Support for RD Fields in Document Field Updating

The v9.0 release expands DsWord’s field-processing engine with full support for the RD (Referenced Document) field, an important feature for customers working with large, multi-file Word projects such as legal filings, reports, academic materials, and publishing workflows.

The RD field allows a Word document to reference other DOCX files when building a Table of Contents (TOC), Table of Authorities (TOA), or Index, enabling authors to generate unified references across multiple documents. With v9.0, DsWord now automatically recognizes RD fields during field updates, retrieves referenced entries, and correctly merges headings, citations, and index entries into the parent document.

Why RD Field Support Matters

Many enterprise and legal Word documents are built using a master document with multiple sub-documents, each containing its own headings, citations, and index entries. The RD field makes it possible to:

• Maintain long documents as smaller, manageable files
• Generate a single consolidated TOC, TOA, or Index
• Reference headings and entries across multiple files
• Create dynamic documents that update automatically

With v9.0, DsWord brings this capability to automated workflows and server-side document generation.

New RD Field API: RdFieldOptions

To support this workflow, DsWord adds the new RdFieldOptions class, which provides full access to RD field definitions:

public class RdFieldOptions : BaseFieldOptions, IFieldOptions
{
    public string FilePath { get; set; }
    public bool Relative { get; set; }
}

Developers can create, read, modify, or save RD fields from both SimpleField and ComplexField structures, allowing DsWord to integrate seamlessly into document assembly pipelines.

Document Path Awareness for Relative RD Fields

The v9.0 update also adds a new property to GcWordDocument:

public string Path { get; set; }

This property enables DsWord to resolve relative RD file paths when updating fields. It is automatically populated when loading or saving a document with a file path, but must be set manually when loading from a stream.

This enhancement ensures that headings, citations, and index terms can be gathered correctly across referenced documents.

Example: Consolidating TOC, TOA, and Index Entries Across Multiple Files

// Create referenced sub-documents...
// (each containing headings, authorities, and index entries)
// Create the main document
var doc = new GcWordDocument();
doc.Path = Path.Combine(Directory.GetCurrentDirectory(), @"rd-new.docx");
// Add TOC, TOA, and Index fields
var toc = new TocFieldOptions(doc);
doc.Body.AddParagraph("Table of Content", doc.Styles[BuiltInStyleId.Title])
        .AddComplexField(toc);
var toa = new ToaFieldOptions(doc);
doc.Body.AddParagraph("Table of Authorities", doc.Styles[BuiltInStyleId.Title])
        .AddComplexField(toa);
var index = new IndexFieldOptions(doc);
index.PageNumbers.Separator = "\t";
doc.Body.AddParagraph("Index", doc.Styles[BuiltInStyleId.Title])
        .AddComplexField(index);
// Reference the sub-documents using RD fields
for (int i = 1; i <= 2; i++)
{
    var rd = new RdFieldOptions(doc)
    {
        FilePath = $"sub{i}.docx",
        Relative = true
    };
    doc.Body.AddParagraph().AddComplexField(rd);
}
// Update all fields (TOC, TOA, Index + RD)
doc.UpdateFields();
doc.Save(doc.Path);

When UpdateFields() is called, DsWord now:

• Loads each referenced sub-document
• Extracts headings, citation entries, and index markers
• Merges them into the parent document’s TOC, TOA, and Index
• Produces a fully consolidated reference structure

With RD field support, DsWord v9.0 gives developers deeper control over complex Word document structures, making it easier to generate consolidated output and automate professional-grade document assembly workflows.

Help | Demo

Update DATE and TIME Fields with Word-Compatible Formatting

In v9.0, DsWord adds full support for updating DATE and TIME fields programmatically, including rich formatting options that closely follow Microsoft Word’s behavior. This enhancement makes it easy to insert “current date/time” fields into server-generated documents and keep them synchronized just by calling UpdateFields(), no manual edits required.

Whether you’re generating contracts, reports, letters, or timestamped exports, you can now control how dates and times are displayed across a wide range of languages and calendar systems.

Rich Date/Time Formatting via Options Classes

To support flexible, Word-like formatting, DsWord introduces two new base classes:

• TimeFormatOptions – Common options for formatting date/time strings
• DateFormatOptions – Extends TimeFormatOptions with calendar-specific settings

These classes expose a DateTimeFormat string, which supports a broad set of format tokens similar to those used by Word (e.g., d, dd, MMM, MMMM, yyyy, hh:mm, AM/PM, localized era and calendar tokens, and more). This allows you to mimic the same formatting users see when inserting DATE/TIME fields in Word.

DateFormatOptions also lets you target specific calendar systems:

• UseHijriLunarCalendar
• UseSakaEraCalendar
• UseUmAlQuoraCalendar

Together, these options give you fine-grained control over how dates and times are rendered across different regions and locales.

Note: Supported languages currently include:

"ar-SA", "bn-BD", "cs-CZ", "de-DE", "el-GR", "en-US", "es-ES", "fa-IR", "fr-FR", "he-IL", "hi-IN", "id-ID", "it-IT", "ja-JP", "ko-KR", "nl-NL", "pl-PL", "pt-PT", "ro-RO", "ru-RU", "sv-SE", "th-TH", "tr-TR", "uk-UA", "vi-VN", "zh-CN", "zh-HK", "zh-MO", "zh-SG", "zh-TW".

The numbered-item format is not supported in this release.

New Field Option Classes: TimeFieldOptions and DateFieldOptions

Building on the formatting base classes, DsWord v9.0 adds two field-specific types:

• TimeFieldOptions – For TIME fields
  • A TIME field defines the current date and time, with emphasis on time formatting.
• DateFieldOptions – For DATE fields
  • A DATE field also defines the current date and time, typically used for document headers, signatures, and print dates.
  • Includes UseLastCreatedFormat to honor the last date-time format used by the hosting application when inserting new DATE fields.

These classes are designed to integrate cleanly with existing DsWord field APIs, and they can be created from a GcWordDocument, SimpleField, or ComplexField, making them useful both for new documents and for updating existing ones.

Example: Insert and Update DATE and TIME Fields

The following example shows how to create default and custom-formatted fields and then update them to the current date and time:

GcWordDocument doc = new GcWordDocument();

// TIME field with default settings
var time = new TimeFieldOptions(doc);
doc.Body.AddParagraph("Time: ").AddComplexField(time);

// DATE field with default settings
var date = new DateFieldOptions(doc);
doc.Body.AddParagraph("Date: ").AddComplexField(date);

// DATE field with custom date-time format
date.DateTimeFormat = "'Today is ' d MMMM yyyy HH:mm:ss";
doc.Body.AddParagraph("Custom date-time format: ").AddComplexField(date);

// Update all fields to show the current date and time
doc.UpdateFields();
doc.Save("date-time.docx");

With this API, you can:

• Insert DATE/TIME fields in templates and update them server-side
• Localize date and time output based on document language
• Match existing Word-based formatting conventions in automated workflows

DsWord v9.0 makes it significantly easier to keep dates and times accurate, consistent, and region-aware across all your generated Word documents.

Help | Demo