MappedDataFieldCollection Class
Allows to automatically map between names of fields in your data source and names of mail merge fields in the document.
Inheritance Hierarchy
SystemObject
  Aspose.Words.MailMergingMappedDataFieldCollection

Namespace: Aspose.Words.MailMerging
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 19.9
Syntax
public class MappedDataFieldCollection : IEnumerable<KeyValuePair<string, string>>, 
	IEnumerable

The MappedDataFieldCollection type exposes the following members.

Properties
  NameDescription
Public propertyCode exampleCount
Gets the number of elements contained in the collection.
Public propertyCode exampleItem
Gets or sets the name of the field in the data source associated with the specified mail merge field.
Methods
  NameDescription
Public methodCode exampleAdd
Adds a new field mapping.
Public methodCode exampleClear
Removes all elements from the collection.
Public methodCode exampleContainsKey
Determines whether a mapping from the specified field in the document exists in the collection.
Public methodCode exampleContainsValue
Determines whether a mapping from the specified field in the data source exists in the collection.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodCode exampleGetEnumerator
Returns a dictionary enumerator object that can be used to iterate over all items in the collection.
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetType
Gets the type of the current instance.
(Inherited from Object.)
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodCode exampleRemove
Removes a field mapping.
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Remarks

This is implemented as a collection of string keys into string values. The keys are the names of mail merge fields in the document and the values are the names of fields in your data source.

Examples
Shows how to map data columns and MERGEFIELDs with different names so the data is transferred between them during a mail merge.
[C#]

public void MappedDataFieldCollection()
{
    // Create a document and table that we will merge
    Document doc = CreateSourceDocMappedDataFields();
    DataTable dataTable = CreateSourceTableMappedDataFields();

    // We have a column "Column2" in the data table that doesn't have a respective MERGEFIELD in the document
    // Also, we have a MERGEFIELD named "Column3" that does not exist as a column in the data source
    // If data from "Column2" is suitable for the "Column3" MERGEFIELD,
    // we can map that column name to the MERGEFIELD in the "MappedDataFields" key/value pair
    MappedDataFieldCollection mappedDataFields = doc.MailMerge.MappedDataFields;

    // A data source column name is linked to a MERGEFIELD name by adding an element like this
    mappedDataFields.Add("MergeFieldName", "DataSourceColumnName");

    // So, values from "Column2" will now go into MERGEFIELDs named "Column3" as well as "Column2", if there are any
    mappedDataFields.Add("Column3", "Column2");

    // The MERGEFIELD name is the "key" to the respective data source column name "value"
    Assert.AreEqual("DataSourceColumnName", mappedDataFields["MergeFieldName"]);
    Assert.True(mappedDataFields.ContainsKey("MergeFieldName"));
    Assert.True(mappedDataFields.ContainsValue("DataSourceColumnName"));

    // Now if we run this mail merge, the "Column3" MERGEFIELDs will take data from "Column2" of the table
    doc.MailMerge.Execute(dataTable);

    // We can count and iterate over the mapped columns/fields
    Assert.AreEqual(2, mappedDataFields.Count);

    using (IEnumerator<KeyValuePair<string, string>> enumerator = mappedDataFields.GetEnumerator())
    {
        while (enumerator.MoveNext())
        {
            Console.WriteLine($"Column named {enumerator.Current.Value} is mapped to MERGEFIELDs named {enumerator.Current.Key}");
        }
    }

    // We can also remove some or all of the elements
    mappedDataFields.Remove("MergeFieldName");
    Assert.False(mappedDataFields.ContainsKey("MergeFieldName"));
    Assert.False(mappedDataFields.ContainsValue("DataSourceColumnName"));

    mappedDataFields.Clear();
    Assert.AreEqual(0, mappedDataFields.Count);

    // Removing the mapped key/value pairs has no effect on the document because the merge was already done with them in place
    doc.Save(ArtifactsDir + "MailMerge.MappedDataFieldCollection.docx");
}

/// <summary>
/// Create a document with 2 MERGEFIELDs, one of which does not have a corresponding column in the data table
/// </summary>
private Document CreateSourceDocMappedDataFields()
{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    // Insert two MERGEFIELDs that will accept data from that table
    builder.InsertField(" MERGEFIELD Column1");
    builder.Write(", ");
    builder.InsertField(" MERGEFIELD Column3");

    return doc;
}

/// <summary>
/// Create a data table with 2 columns, one of which does not have a corresponding MERGEFIELD in our source document
/// </summary>
private DataTable CreateSourceTableMappedDataFields()
{
    // Create a data table that will be used in a mail merge
    DataTable dataTable = new DataTable("MyTable");
    dataTable.Columns.Add("Column1");
    dataTable.Columns.Add("Column2");
    dataTable.Rows.Add(new object[] { "Value1", "Value2" });

    return dataTable;
}
See Also