Mail Merge Examples
MailMerge creates documents from a template and data, and its events let your code change each field, row and block while it merges. Most of the samples below are Windows Forms projects that do exactly that: they color table cells, merge cells, include Excel sheets or HTML, and preview the results record by record.
Official Samples
The setup installs these samples, and the folder Howto\MailMerge of TXSamples_WinForms_CSharp contains them for version 32.0:
| Example | What it shows | Where |
|---|---|---|
| Simple merge | Merge fields filled with data | Howto\MailMerge\MailMerge_Simple |
| Merge blocks | A section of the template repeated for each record | Howto\MailMerge\MailMerge_Blocks |
| Nested merge blocks | Merge blocks inside merge blocks, filled from related tables | Howto\MailMerge\MailMerge_Nested_Blocks |
The TX Words Reporting sample designs templates with a sample database and merges them; see TX Words Sample Application.
Sample Projects
All projects are Windows Forms applications in C# for the .NET Framework. The version is the one the project references today; the code dates from the year of the article.
| Example | What it shows | Where |
|---|---|---|
| Conditional cell colors | Background colors of table cells set in FieldMerged according to rules in the field names, as described in MailMerge: Conditional Table Cell Colors using Filter Instructions. .NET Framework 4.5, version 34.0 | TextControl.WindowsForms.MailMerge.ConditionalColor |
| Merged cells | Cells of a merge block with the same content merged vertically after BlockRowMerged, as described in Merging Merge Block Cells Vertically with Matching Content. .NET Framework 4.8, version 33.0 | TextControl.Windows.Forms.MailMerge.MergeCells |
| Preview with a BindingNavigator | Each record of a BindingSource merged into the template for a preview, as described in Windows Forms: Preview Mail Merge Results with the BindingNavigator and a BindingSource. .NET Framework 4.5, version 33.0 | TextControl.WindowsForms.MailMerge.BindingNavigator |
| Excel in templates | Excel sheets included through INCLUDETEXT fields in IncludeTextMerging, as described in Merge Excel Documents into MailMerge Templates using IncludeText Fields. .NET Framework 4.8, version 34.0 | TextControl.WindowsForms.MailMergeExcel |
| Formatted HTML | HTML from the data merged into merge fields with its formatting, as described in Reporting: Merge Formatted HTML into Merge Fields. .NET Framework 4.0, version 34.0 | TextControl.MailMerge.MergeFormattedHTML |
| DOCVARIABLE fields | DOCVARIABLE fields of MS Word documents converted into merge fields before the merge, as described in Reporting: Merging MS Word Documents with DocVariables. .NET Framework 4.8, version 34.0 | TextControl.MailMerge.DocVariables |
| Sums in merge blocks | Custom SUM fields totaled for each merge block, as described in MailMerge: Dynamic, Custom SUM Fields in Merge Blocks. .NET Framework 4.0, version 34.0 | TextControl.MailMerge.CustomSUMFields |
| Conditional sub-templates | INCLUDETEXT fields included or skipped for each record, as described in MailMerge: Conditional INCLUDETEXT Fields. .NET Framework 4.8, version 33.0 | TextControl.MailMerge.ConditionalIncludeFields |
| Events for custom processing | Fields, rows and block rows processed in the merge events, as described in Reporting: Custom Processing Using MailMerge Events. .NET Framework 4.0, version 33.0 | TextControl.MailMerge.CustomProcessingWithEvents |
| Empty lines | Lines of an address removed when all their fields are empty, as described in Mail Merge: Suppress Lines with Empty Merge Fields. .NET Framework 4.5, version 33.0 | TextControl.MailMerge.Suppress-Lines-With-Empty-Merge-Fields |
| Line breaks in the data | Line breaks in field values turned into line breaks of the document, as described in MailMerge: MergeFields with CRLFs. .NET Framework 4.0, version 33.0 | TextControl.MailMerge.CRLF |
| Remapping merge fields | A dialog that maps the field names of a template to the columns of new data, as described in Dialog Project: Remapping Merge Fields. .NET Framework 4.0, version 33.0 | TextControl.MailMerge.FieldRemapping |
| Conditional text blocks | Formatted text, tables and images between two marker fields of the template kept or removed for each record in DataRowMerged, as described in Reporting: Conditional Formatted Text Blocks. .NET Framework 4.8, version 33.0 | TextControl.MailMerge.ConditionalTextBlock |
| Check boxes from data | MS Word check box form fields checked from Boolean values of the data with the FormCheckBox field adapter, as described in MailMerge: Merge CheckBoxes During the Merge Process. .NET Framework 4.5, version 33.0 | TextControl.MailMerge.CheckBoxes |
| Empty table rows | Alternating row colors from NEXT fields, and empty rows at the end of a merge block removed in BlockRowMerged, as described in Reporting: Removing Empty Table Rows. .NET Framework 4.5, version 33.0 | TextControl.MailMerge.RemoveEmptyTableRows |
| Business objects | Collections of business objects merged into merge blocks and nested merge blocks, with totals calculated in the objects instead of the template, as described in Advantages of Using Business Objects with Text Control Reporting. .NET Framework 4.8, version 33.0 | TextControl.MailMerge.BusinessObjectsUsage |
| Progress bar | A progress bar advanced in DataRowMerged for each merged record, as described in Reporting: Updating a Progress Bar During Merge Processes. .NET Framework 4.8, version 33.0 | TextControl.MailMerge.ProgressBar |
| Images from files | Image placeholders merged from file names in the data, with the folder of the images set in SearchPath, as described in Reporting: Merging Images from Files Using SearchPath. .NET Framework 4.0, version 33.0 | TextControl.MailMerge.MergeImagesFromFiles |
| Shipping labels | A label template with two page columns filled with one label per record, as described in MailMerge: Creating Shipping Labels Using TX Text Control. .NET Framework 4.8, version 33.0 | TextControl.MailMerge.ShippingLabels |
Blog Articles With Code
These articles use MailMerge with a ServerTextControl; the class is the same in TX Text Control .NET for Windows Forms, where the TextControl of a form can also be its template:
| Example | What it shows | Where |
|---|---|---|
| Overview | Templates, data sources, merge blocks and the events of MailMerge | An Ultimate Guide to Mail Merge with MS Word Documents in C# |
| Sorting and filtering | The rows of merge blocks sorted and filtered | Filtering and Sorting Repeating Blocks in MailMerge using C# |
| Calculating business objects | Business objects that calculate their own totals, merged into a template | Merging Self-Calculating Business Objects with TX Text Control MailMerge in C# |
| Table cells | Table cells changed while the merge runs | Manipulating Table Cells During the MailMerge Process in .NET C# |
| Merge blocks in code | Merge blocks inserted with the DataSourceManager | Mail Merge: Inserting Merge Blocks using the DataSourceManager in C# |
| Hyperlinks | Hyperlinks created from the data in FieldMerged | MailMerge: Merging Hyperlinks using the FieldMerged Event |
Next Steps
- Mail Merge and Reporting: templates, data sources and merge blocks, explained.
- Mail Merge in Getting Started: merge a first template step by step.
- PDF Examples: merged documents saved as PDF and electronic invoices.