Class
WordMailMerge
OfficeIMO.Word
Provides basic mail merge capabilities by replacing MERGEFIELD fields with supplied values.
Inheritance
- object
- WordMailMerge
Methods
public static void Execute(WordDocument document, IDictionary<string, string> values, bool removeFields = true) #Replaces all MERGEFIELD fields in the given document with provided values.
Parameters
- document OfficeIMO.Word.WordDocument
- Document to update.
- values System.Collections.Generic.IDictionary<string, string>
- Dictionary with field names and values.
- removeFields bool = true
- Determines whether the field codes are removed after replacement.
public static IReadOnlyList<string> ExecuteBatch(string templatePath, IEnumerable<IDictionary<string, string>> records, Func<int, IDictionary<string, string>, string> outputPathFactory, bool removeFields = true) #Creates one merged document per value set from a template file.
Parameters
- templatePath string
- Path to the source template document.
- records System.Collections.Generic.IEnumerable<System.Collections.Generic.IDictionary<string, string>>
- Value sets used to generate output documents.
- outputPathFactory System.Func<int, System.Collections.Generic.IDictionary<string, string>, string>
- Function that returns an output path for each zero-based record index and value set.
- removeFields bool = true
- Determines whether field codes are removed after replacement.
Returns
IReadOnlyList<string> Output document paths in generation order.public static WordMailMergeBatchResult ExecuteBatchWithReport(string templatePath, IEnumerable<IDictionary<string, string>> records, Func<int, IDictionary<string, string>, string> outputPathFactory, bool removeFields = true) #Creates one merged document per record and returns each output with its per-field execution report.
Parameters
- templatePath string
- records System.Collections.Generic.IEnumerable<System.Collections.Generic.IDictionary<string, string>>
- outputPathFactory System.Func<int, System.Collections.Generic.IDictionary<string, string>, string>
- removeFields bool = true
Returns
WordMailMergeBatchResultpublic static int ExecuteConditionalBlocks(WordDocument document, IDictionary<string, bool> conditions, bool removeMarkers = true) #Includes or removes conditional template blocks delimited by marker paragraphs such as {{#ShowDiscount}} and {{/ShowDiscount}}.
Parameters
- document OfficeIMO.Word.WordDocument
- Document containing conditional marker paragraphs.
- conditions System.Collections.Generic.IDictionary<string, bool>
- Condition values keyed by marker name.
- removeMarkers bool = true
- When true, matched marker paragraphs are removed from included blocks.
Returns
int The number of conditional blocks processed.public static WordContentControlDataBindingResult ExecuteContentControlDataBindings(WordDocument document, IDictionary<string, string> values, bool updateCustomXml = true) #Fills bound content controls from supplied values and, when possible, updates the backing Custom XML node.
Parameters
- document OfficeIMO.Word.WordDocument
- Document containing bound content controls.
- values System.Collections.Generic.IDictionary<string, string>
- Values keyed by content-control alias, tag, XPath, or storeItemId|XPath.
- updateCustomXml bool = true
- When true, matching backing Custom XML nodes are updated with supplied values.
public static int ExecuteRepeatingBlockRegions(WordDocument document, IDictionary<string, IEnumerable<WordMailMergeBlockData>> regions, bool removeFields = true) #Repeats block-level template regions with nested data, using marker paragraphs such as {{#each Items}} and {{/each Items}}.
Parameters
- document OfficeIMO.Word.WordDocument
- Document containing repeated block marker paragraphs.
- regions System.Collections.Generic.IDictionary<string, System.Collections.Generic.IEnumerable<OfficeIMO.Word.WordMailMergeBlockData>>
- Repeated region rows keyed by marker name.
- removeFields bool = true
- Determines whether field codes are removed after replacement.
Returns
int The number of generated region instances, including nested instances.public static int ExecuteRepeatingBlocks(WordDocument document, IDictionary<string, IEnumerable<IDictionary<string, string>>> regions, bool removeFields = true) #Repeats block-level template regions delimited by marker paragraphs such as {{#each Items}} and {{/each Items}}.
Parameters
- document OfficeIMO.Word.WordDocument
- Document containing repeated block marker paragraphs.
- regions System.Collections.Generic.IDictionary<string, System.Collections.Generic.IEnumerable<System.Collections.Generic.IDictionary<string, string>>>
- Repeated region rows keyed by marker name.
- removeFields bool = true
- Determines whether field codes are removed after replacement.
Returns
int The number of generated region instances.public static WordMailMergeTableRowGroupResult ExecuteTableRowGroups(WordTable table, int groupTemplateRowIndex, int detailTemplateRowIndex, IEnumerable<WordMailMergeTableRowGroup> groups, bool removeFields = true) #Repeats a group template row and its detail row template for each supplied grouped data set.
Parameters
- table OfficeIMO.Word.WordTable
- Table containing the group and detail template rows.
- groupTemplateRowIndex int
- Zero-based row index of the group/header row template.
- detailTemplateRowIndex int
- Zero-based row index of the detail row template.
- groups System.Collections.Generic.IEnumerable<OfficeIMO.Word.WordMailMergeTableRowGroup>
- Grouped value sets used to generate group and detail rows.
- removeFields bool = true
- Determines whether the field codes are removed after replacement.
public static int ExecuteTableRows(WordTable table, int templateRowIndex, IEnumerable<IDictionary<string, string>> rows, bool removeFields = true) #Repeats a table row template once for every supplied value set and applies MERGEFIELD replacements in each generated row.
Parameters
- table OfficeIMO.Word.WordTable
- Table containing the row template.
- templateRowIndex int
- Zero-based row index to clone and bind.
- rows System.Collections.Generic.IEnumerable<System.Collections.Generic.IDictionary<string, string>>
- Value sets used to generate rows.
- removeFields bool = true
- Determines whether field codes are removed after replacement.
Returns
int The number of generated rows.public static WordMailMergeExecutionReport ExecuteWithReport(WordDocument document, IDictionary<string, string> values, bool removeFields = true) #Replaces MERGEFIELD values and returns per-occurrence missing-value and formatting diagnostics.
Parameters
- document OfficeIMO.Word.WordDocument
- values System.Collections.Generic.IDictionary<string, string>
- removeFields bool = true
Returns
WordMailMergeExecutionReportpublic static WordMailMergeTemplateInspection InspectTemplate(WordDocument document, IEnumerable<string>? mergeFieldNames = null, IEnumerable<string>? conditionNames = null, IEnumerable<string>? repeatingBlockNames = null) #Inspects a Word mail-merge template and optionally validates that merge fields and conditional blocks have supplied values.
Parameters
- document OfficeIMO.Word.WordDocument
- Document to inspect.
- mergeFieldNames System.Collections.Generic.IEnumerable<string>? = null
- Optional supplied MERGEFIELD names. When provided, missing fields are reported as issues.
- conditionNames System.Collections.Generic.IEnumerable<string>? = null
- Optional supplied conditional block names. When provided, missing conditions are reported as issues.
- repeatingBlockNames System.Collections.Generic.IEnumerable<string>? = null
- Optional supplied repeated block names. When provided, missing repeated block rows are reported as issues.
public static WordTemplatePreflightReport PreflightTemplate(WordDocument document, IEnumerable<string>? mergeFieldNames = null, IEnumerable<string>? conditionNames = null, IEnumerable<string>? repeatingBlockNames = null) #Inspects a Word mail-merge template and returns a CI-friendly preflight report with capability checks and diagnostics.
Parameters
- document OfficeIMO.Word.WordDocument
- Document to inspect.
- mergeFieldNames System.Collections.Generic.IEnumerable<string>? = null
- Optional supplied MERGEFIELD names. When provided, missing fields are reported as issues.
- conditionNames System.Collections.Generic.IEnumerable<string>? = null
- Optional supplied conditional block names. When provided, missing conditions are reported as issues.
- repeatingBlockNames System.Collections.Generic.IEnumerable<string>? = null
- Optional supplied repeated block names. When provided, missing repeated block rows are reported as issues.
Returns
WordTemplatePreflightReportpublic static WordContentControlDataBindingResult RefreshContentControlDataBindings(WordDocument document) #Updates visible text in bound content controls from their backing Custom XML values.
Parameters
- document OfficeIMO.Word.WordDocument
- Document containing bound content controls.
ValidateTemplate 2 overloads
public static WordMailMergeTemplateInspection ValidateTemplate(WordDocument document, IEnumerable<string> mergeFieldNames, IEnumerable<string> conditionNames) #Validates a Word mail-merge template against supplied merge-field and conditional-block names.
Parameters
- document OfficeIMO.Word.WordDocument
- Document to validate.
- mergeFieldNames System.Collections.Generic.IEnumerable<string>
- Supplied MERGEFIELD names.
- conditionNames System.Collections.Generic.IEnumerable<string>
- Supplied conditional block names.
public static WordMailMergeTemplateInspection ValidateTemplate(WordDocument document, IEnumerable<string> mergeFieldNames, IEnumerable<string> conditionNames, IEnumerable<string> repeatingBlockNames) #Validates a Word mail-merge template against supplied merge-field, conditional-block, and repeated-block names.
Parameters
- document OfficeIMO.Word.WordDocument
- Document to validate.
- mergeFieldNames System.Collections.Generic.IEnumerable<string>
- Supplied MERGEFIELD names.
- conditionNames System.Collections.Generic.IEnumerable<string>
- Supplied conditional block names.
- repeatingBlockNames System.Collections.Generic.IEnumerable<string>
- Supplied repeated block names.