MailMerge Class

Description

The MailMerge class is a .NET component that can be used to effortlessly merge template documents with database content in .NET projects, such as ASP.NET web applications, web services or Windows services. The MailMerge class can be found in the TXTextControl.DocumentServer namespace. It is inherited from the System.ComponentModel.Component class. The following describes only the properties and methods defined through the MailMerge class. For a list of properties, methods and events inherited from the System.ComponentModel.Component class see the .NET Framework reference.

Syntax

public class MailMerge : Component

Public Class MailMerge
    Inherits Component

Examples

The following example creates a Mail Merge instance and configures its remove empty blocks setting for a document workflow.

using TXTextControl.DocumentServer.MailMerge mailMerge = new();
mailMerge.RemoveEmptyBlocks = true;

Dim mailMerge As New TXTextControl.DocumentServer.MailMerge()
mailMerge.RemoveEmptyBlocks = True

Members

Constructors

Constructor	Description
MailMerge	Initializes a new instance of the MailMerge class.

Properties

Property	Description
DataSourceCulture	Specifies the culture with which numerical and date / time values coming from the data source are parsed. The default value for this property is the current thread culture.
DateFieldUtcOffset	Specifies the UTC offset in minutes to apply to date fields. If this property is null, the local date and time is used. The default value of this property is null.
FormFieldMergeType	Specifies in which manner form fields are treated during the merge process. Form fields can either be ignored, preselected or replaced with a value from the data source. The default value is FormFieldMergeType.None which means that form fields are completely unaffected by the merge process.
MergeBlockNamePrefix	A static property returning the internal merge block name prefix “txmb_”. The name of a SubTextPart has to start with this prefix if it should be recognized as a repeating mail merge block by the merge methods of class MailMerge.
MergeCulture	Specifies the culture with which numerical and date / time values are formatted when merged into the target document. The default value for this property is the current thread culture.
RemoveEmptyBlocks	Specifies whether the content of empty merge blocks should be removed from the template or not. The default value is true.
RemoveEmptyFields	Specifies whether empty fields should be removed from the template or not. The default value is true.
RemoveEmptyImages	Specifies whether images which don't have merge data should be removed from the template or not. The default value is false.
RemoveEmptyLines	Specifies whether text lines which are empty after merging should be removed from the template or not. The default value is false.
RemoveTrailingWhitespace	Specifies whether trailing whitespace should be removed before saving a document. The default value is true.
ReportDataSourceConfig	Specifies the Report Data Source Configuration as an XML string. Must be in the same form as the content of a Report Data Source Configuration file created by TX Text Control Words.
ReportDataSourceConfigFile	Gets or sets the file path of a Report Data Source Configuration file (*.rdsc) which has been created with TX Text Control Words.
SearchPath	Specifies a directory name where sub-templates and images (for image merging) should be searched. If SearchPath is empty, the root directory is used.
TemplateFile	Specifies the template file path. Can be used instead of the LoadTemplate method. The document format is deduced from the file extension automatically.
TextComponent	Gets or sets the TextComponent object which is associated with the MailMerge component. It must be of the type ServerTextControl, TextControl or WPF.TextControl. The PageSize, PageMargins and Landscape properties will be used, if UseTemplateFormat has been set to false. The ServerTextControl.FormattingPrinter property will be used internally to format the text. It returns null when not specified.
UseTemplateFormat	Specifies whether the template page size and margins should be used or not. The default value is false.

Methods

Method	Description
GetBlockFieldNames	Returns the names of all merge fields inside the merge block with the specified name.
GetBlockNames	Lists the names of all merge blocks contained in the currently loaded template.
LoadTemplate	Loads a template from a file that is used for the merge process.
LoadTemplateFromMemory	Loads a template from memory that is used for the merge process.
Merge	Merges given data into the loaded document template. The supported format of the merge fields can be found in the ASP.NET User's Guide.
MergeBlocks	Merges all repeating blocks that are contained in the loaded template with the System.Data.DataTable instances contained in the given System.Data.DataSet. The name of the System.Data.DataTable must match the name of the block in the template. The supported format of the repeating blocks can be found in the ASP.NET User's Guide.
MergeJsonData	Merges data given as a JSON string into a document template. The JSON string has to contain either a single object or an array of equally structured objects. Analyzes and uses the given object(s) as merge data in the same way as the method MergeObjects.
MergeObject	Merges a single instance of an arbitrary type into the loaded document template. For more information about .NET reflection based object merging read the documentation of the MergeObjects method.
MergeObjects	Merges a collection of type System.Collections.IEnumerable containing objects of any type or instances of type System.Collections.Generic.Dictionary with string keys into the loaded document template.
Print	Prints the merged document.
SaveDocument	Saves the merged document to a file.
SaveDocumentToMemory	Saves the merged document.

Events

Event	Description
BarcodeMerged	Occurs when a barcode has been merged successfully. The event handler receives an argument of type BarcodeMergedEventArgs containing data related to this event.
BlockMerging	Occurs when a merge block is about to be merged. The event handler receives an argument of type BlockMergingEventArgs containing data related to this event.
BlockRowMerged	Occurs when a merge block row has been merged successfully. The event handler receives an argument of type BlockRowMergedEventArgs containing data related to this event. This event can be used to change the content or formatting of a merged row in the repeating block.
ChartMerged	Occurs when a chart has been merged successfully. The event handler receives an argument of type ChartMergedEventArgs containing data related to this event.
DataRowMerged	Occurs when a data row has been merged successfully. The event handler receives an argument of type DataRowMergedEventArgs containing data related to this event.
FieldMerged	Occurs when a field has been merged. The event handler receives an argument of type FieldMergedEventArgs containing data related to this event. This event can be used to change the field text and to determine whether the field has been merged successfully.
FormFieldMerged	Occurs when a form field has been merged. The event handler receives an argument of type FormFieldMergedEventArgs containing data related to this event. This event can be used to change the field text and to determine whether the field has been merged successfully.
ImageFieldMerged	Occurs when an image field, i.e., a merge field whose name is prefixed with "image:" has been merged. The event handler receives an argument of type ImageFieldMergedEventArgs containing data related to this event. This event can be used to change the image and to determine whether the field has been merged successfully.
ImageMerged	Occurs when an image has been merged successfully. The event handler receives an argument of type ImageMergedEventArgs containing data related to this event.
IncludeTextMerging	Occurs when an IncludeText field has been merged. The event handler receives an argument of type IncludeTextMergingEventArgs containing data related to this event.