In this article, I’ll show you how to perform MS Word Mail Merge using C# or VB.NET without MS Word or Office Interop. Aspose.Words for .NET is a feature-rich and powerful Word API that provides all the basic as well as extended MS Word Mail Merge features. It lets you generate letters, envelopes, reports, invoices, and other types of documents within Windows Forms, ASP.NET web applications, or any .NET/.NET Core application.
Covering the salient features of our .NET Mail Merge API, this article is composed of the following sections:
- What is Mail Merge?
- Data Sources for Mail Merge
- Preparing Template for Mail Merge
- .NET Mail Merge API – Installation
- Perform Mail Merge in Word Document using C#
- Mail Merge using XML Data Source
- Custom Formatting of Merge Fields
- Mail Merge with Regions
- Nested Mail Merge Regions
What is Mail Merge?
Mail Merge is the way of automated generation of reports, letters, envelopes, invoices, and other types of documents. Mail Merge in MS Word allows you to create a template document containing merge fields and then populate those fields using records in the data source. To understand Mail Merge, suppose you have to send a letter to ten different people and only name and the address fields are to be updated. In such a case, simply create a template of the letter and then dynamically generate the letters by populating the name and address merge fields using the data source.
Data Sources for Mail Merge
The data for the Mail Merge could be fetched from any data source such as XML, JSON, or a database. As far as Aspose.Words for .NET is concerned, you can use any data source which is supported by ADO.NET. The data can be loaded into a DataSet, DataTable, DataView, or an array of values.
Preparing Template for Mail Merge
The Mail Merge template is the document that contains the merge fields. These fields are then populated with the data in the data source when the Mail Merge is executed. The template document doesn’t need to be a template format and it can be a DOC/DOCX document. This is how you can prepare a template for Mail Merge.
- Open your document or create a new one in MS Word.
- Place the cursor where you want to add a merge field.
- From the Insert menu select Field option.
- From the Field names list, select MergeField.
- Enter a name for the merge field in Field name and press OK.
- Save the document.
The following is the screenshot of the sample template document.
.NET Mail Merge API – Installation
Aspose.Words for .NET can be downloaded or installed using the following ways:
Perform Mail Merge in Word Document using C#
Once you have the template ready, you can execute the Mail Merge to generate the documents. The following are the steps to execute the Mail Merge on the above-mentioned template.
- Load the template document using Document class.
- Set required Mail Merge options such as Document.MailMerge.TrimWhitespaces.
- Execute a Mail Merge using Document.MailMerge.Execute() method and pass the data source as the parameter.
- Save the generated document using Document.Save(String) method.
The following code sample shows how to execute MS Word Mail Merge using an array of values in C#.
Word Document after Mail Merge
Perform Mail Merge using XML Data Source in C#
The XML files are widely used to keep as well as import/export data. Aspose.Words for .NET also support XML as a data source for the Mail Merge. Just read the XML into a DataSet object and execute the Mail Merge. The following is the sample XML file that we are going to use.
<customers> <customer Name="John Ben Jan" ID="1" Domain="History" City="Boston"/> <customer Name="Lisa Lane" ID="2" Domain="Chemistry" City="LA"/> <customer Name="Dagomir Zits" ID="3" Domain="Heraldry" City="Milwaukee"/> <customer Name="Sara Careira Santy" ID="4" Domain="IT" City="Miami"/> </customers>
The following code sample fetches the data from an XML data source and executes the Mail Merge using C#.
Below is the Mail Merge template that will be populated with XML data.
The following is page 1 of the resultant Word document we get after executing the Mail Merge.
Custom Formatting of Merge Fields
Aspose.Words for .NET gives you more control over the Mail Merge during the execution. The MailMerge.FieldMergingCallback property allows you to customize the Mail Merge when any merge field is encountered. MailMerge.FieldMergingCallback accepts the class implementing the IFieldMergingCallback.FieldMerging and IFieldMergingCallback.ImageFieldMerging methods.
The following code sample shows how to customize the Mail Merge operation and apply formatting to the cells within this template.
The following is the implementation of the HandleMergeFieldAlternatingRows class.
Mail Merge with Regions using C#
There might be the case when you need to populate and repeat a particular region in the Word document. For such a case, you can use the Mail Merge with regions. To create a region you need to specify the start and the end of the region and then Mail Megre will repeat that region for each record in the data source. For example, The following template contains two regions, Orders and OrderDetails with the merge fields «TableStart:Orders», «TableEnd:Orders» and «TableStart:OrderDetails», «TableEnd:OrderDetails» respectively.
The following is the code sample that performs Mail Megre on regions for the above-mentioned template.
The following are the methods to read data from the database.
Nested Mail Merge Regions
Most often, the data we have in the data source comes in the form of relationships. For example, the table “Order” will have a one-to-many relationship with the “OrderDetails” that will keep records of the items in an order. To deal with such parent-child relationships, nested Mail Merge is used. The following is a sample invoice template that well-suits this scenario.
The following is the sample XML data source that we’ll use for the nested Mail Merge.
<?xml version="1.0" encoding="utf-8"?> <Orders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="OrdersSchema.xsd"> <Order> <Number>23</Number> <Address>Nelson Street</Address> <Suburb>Howick</Suburb> <City>Auckland</City> <Phonenumber>543 1234</Phonenumber> <Date>03/01/2010</Date> <Total>14.00</Total> <Item> <Name>BBQ Chicken Pizza</Name> <Price>6.00</Price> <Quantity>1</Quantity> <ItemTotal>6.00</ItemTotal> </Item> <Item> <Name>1.5 Litre Coke</Name> <Price>4.00</Price> <Quantity>2</Quantity> <ItemTotal>8.00</ItemTotal> </Item> </Order> <Order> <Number>10</Number> <Address>Parkville Avenue</Address> <Suburb>Pakuranga</Suburb> <City>Auckland</City> <Phonenumber>548 7342</Phonenumber> <Date>05/03/2010</Date> <Total>6.00</Total> <Item> <Name>Hawaiian Pizza</Name> <Price>4.00</Price> <Quantity>1</Quantity> <ItemTotal>4.00</ItemTotal> </Item> <Item> <Name>Fries</Name> <Price>1.00</Price> <Quantity>2</Quantity> <ItemTotal>2.00</ItemTotal> </Item> </Order> </Orders>
Whereas, the OrderSchema.xsd for this XML is:
<?xml version="1.0" encoding ="utf-8"?> <xs:schema id="OrdersSchema" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="Orders"> <xs:complexType> <xs:sequence> <xs:element name="Order"> <xs:complexType> <xs:sequence> <xs:element name="Number"/> <xs:element name="Address"/> <xs:element name="Suburb"/> <xs:element name="City"/> <xs:element name="Phonenumber"> <xs:element name="Date"/> <xs:element name="Total"/> <xs:element name="Item"> <xs:complexType> <xs:sequence> <xs:element name="Name"/> <xs:element name="Price"/> <xs:element name="Quantity"/> <xs:element name="ItemTotal"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
The following code sample is used to execute the nested Mail Merge using C#.
Word Document after Mail Merge
Below is the first page of the resultant Word document after executing the Mail Merge.
Aspose.Words for .NET is a feature-rich Mail Merge API that provides all the standard as well as extended Mail Merge features for .NET applications. Within a few lines of code, you can create simple or complex reports from various types of data sources seamlessly. You can read more about the .NET Mail Merge API from the documentation. To learn about Aspose.Words for .NET, get started with the developer’s guides, and GitHub code samples.
Try Aspose.Words for .NET for Free
You can get a free temporary license to try Aspose.Words for .NET without any limitations. Get your temporary license now.