MailMergeSettings Class

Specifies all of the mail merge information for a document.

Inheritance Hierarchy

SystemObject
  Aspose.Words.SettingsMailMergeSettings

Namespace:  Aspose.Words.Settings
Assembly:  Aspose.Words (in Aspose.Words.dll) Version: 20.9.0

Syntax

public class MailMergeSettings

The MailMergeSettings type exposes the following members.

Constructors

  NameDescription
Public methodMailMergeSettings
Initializes a new instance of the MailMergeSettings class

Properties

  NameDescription
Public propertyCode exampleActiveRecord
Specifies the one-based index of the record from the data source which shall be displayed in Microsoft Word. The default value is 1.
Public propertyCode exampleAddressFieldName
Specifies the column within the data source that contains e-mail addresses. The default value is an empty string.
Public propertyCode exampleCheckErrors
Specifies the type of error reporting which shall be conducted by Microsoft Word when performing a mail merge. The default value is Default.
Public propertyCode exampleConnectString
Specifies the connection string used to connect to an external data source. The default value is an empty string.
Public propertyCode exampleDataSource
Specifies the path to the mail-merge data source. The default value is an empty string.
Public propertyCode exampleDataType
Specifies the type of the mail-merge data source and the method of data access. The default value is Default.
Public propertyCode exampleDestination
Specifies how Microsoft Word will output the results of a mail merge. The default value is Default.
Public propertyCode exampleDoNotSupressBlankLines
Specifies how an application performing the mail merge shall handle blank lines in the merged documents resulting from the mail merge. The default value is false.
Public propertyCode exampleHeaderSource
Specifies the path to the mail-merge header source. The default value is an empty string.
Public propertyCode exampleLinkToQuery
Not sure about this one. The Microsoft Word Automation Reference suggests that this specifies that the query is executed every time the document is opened in Microsoft Word. But the OOXML specification suggests that this specifies that the query contains a reference to an external query file which contains the actual query. The default value is false.
Public propertyCode exampleMailAsAttachment
Specifies that the documents produced during a mail merge operation should be emailed as an attachment rather than the body of the actual e-mail. The default value is false.
Public propertyCode exampleMailSubject
Specifies the text which shall appear in the subject line of the e-mails or faxes produced during mail merge. The default value is an empty string.
Public propertyCode exampleMainDocumentType
Specifies the mail-merge main document type. The default value is Default.
Public propertyCode exampleOdso
Gets or sets the object that specifies the Office Data Source Object (ODSO) settings.
Public propertyCode exampleQuery
Contains the Structured Query Language string that shall be run against the specified external data source to return the set of records which shall be imported into the document when the mail merge operation is performed. The default value is an empty string.
Public propertyCode exampleViewMergedData
Specifies that Microsoft Word shall display the data from the specified external data source where merge fields have been inserted (e.g. preview merged data). The default value is false.

Methods

  NameDescription
Public methodCode exampleClear
Clears the mail merge settings in such a way that when the document is saved, no mail merge settings will be saved and it will become a normal document.
Public methodCode exampleClone
Returns a deep clone of this object.
Public methodEquals (Inherited from Object.)
Public methodGetHashCode (Inherited from Object.)
Public methodGetType (Inherited from Object.)
Public methodToString (Inherited from Object.)

Remarks

You can use this object to specify a mail merge data source for a document and this information (along with the available data fields) will appear in Microsoft Word when the user opens this document. Or you can use this object to query mail merge settings that the user has specified in Microsoft Word for this document.

You do not normally need to create objects of this class directly because Mail merge settings of a document are always available via the MailMergeSettings property.

To detect whether this document is a mail merge main document, check the value of the MainDocumentType property.

To remove mail merge settings and data source information from a document you can use the Clear method. Aspose.Words will not write mail merge settings to a document if the MainDocumentType property is set to NotAMergeDocument or the DataType property is set to None.

The best way to learn how to use the properties of this object is to create a document with a desired data source manually in Microsoft Word and then open that document using Aspose.Words and examine the properties of the MailMergeSettings and Odso objects. This is a good approach to take if you want to learn how to programmatically configure a data source, for example.

Aspose.Words preserves mail merge information when loading, saving and converting documents between different formats, but does not use this information when performing its own mail merge using the MailMerge object.

Examples

Shows how to execute an Office Data Source Object mail merge with MailMergeSettings.
// We'll create a simple document that will act as a destination for mail merge data
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.Write("Dear ");
builder.InsertField("MERGEFIELD FirstName", "<FirstName>");
builder.Write(" ");
builder.InsertField("MERGEFIELD LastName", "<LastName>");
builder.Writeln(": ");
builder.InsertField("MERGEFIELD Message", "<Message>");

// We will use an ASCII file as a data source
// We can use any character we want as a delimiter, in this case we'll choose '|'
// The delimiter character is selected in the ODSO settings of mail merge settings
string[] lines = { "FirstName|LastName|Message",
    "John|Doe|Hello! This message was created with Aspose Words mail merge." };
string dataSrcFilename = ArtifactsDir + "MailMerge.MailMergeSettings.DataSource.txt";

File.WriteAllLines(dataSrcFilename, lines);

// Set the data source, query and other things
MailMergeSettings settings = doc.MailMergeSettings;
settings.MainDocumentType = MailMergeMainDocumentType.MailingLabels;
settings.CheckErrors = MailMergeCheckErrors.Simulate;
settings.DataType = MailMergeDataType.Native;
settings.DataSource = dataSrcFilename;
settings.Query = "SELECT * FROM " + doc.MailMergeSettings.DataSource;
settings.LinkToQuery = true;
settings.ViewMergedData = true;

Assert.AreEqual(MailMergeDestination.Default, settings.Destination);
Assert.False(settings.DoNotSupressBlankLines);

// Office Data Source Object settings
Odso odso = settings.Odso;
odso.DataSource = dataSrcFilename;
odso.DataSourceType = OdsoDataSourceType.Text;
odso.ColumnDelimiter = '|';
odso.FirstRowContainsColumnNames = true;

// ODSO/MailMergeSettings objects can also be cloned
Assert.AreNotSame(odso, odso.Clone());
Assert.AreNotSame(settings, settings.Clone());

// The mail merge will be performed when this document is opened 
doc.Save(ArtifactsDir + "MailMerge.MailMergeSettings.docx");

See Also