C# Mail Merge API | MS Word Mail Merge API för .NET

I den här artikeln kommer jag att visa dig hur du utför MS Word Mail Merge med C# eller VB.NET utan MS Word eller Office Interop. Aspose.Words for .NET är ett funktionsrikt och kraftfullt Word API som tillhandahåller alla grundläggande såväl som utökade MS Word Mail Merge-funktioner. Den låter dig generera brev, kuvert, rapporter, fakturor och andra typer av dokument i Windows Forms, ASP.NET webbapplikationer eller någon .NET/.NET Core-applikation.

Den här artikeln täcker de viktigaste funktionerna i vårt .NET Mail Merge API och består av följande avsnitt:

Vad är Mail Merge?
Datakällor för Mail Merge
Förbereder mall för brevkoppling
.NET Mail Merge API - Installation
Utför e-postkoppling i Word-dokument med C#
Mail Merge med XML-datakälla
Anpassad formatering av sammanfogningsfält
Mail Merge med regioner
Kapslade kopplingsregioner

Vad är Mail Merge?

Mail Merge är sättet för automatisk generering av rapporter, brev, kuvert, fakturor och andra typer av dokument. Mail Merge i MS Word låter dig skapa ett malldokument som innehåller sammanslagningsfält och sedan fylla i dessa fält med hjälp av poster i datakällan. För att förstå Mail Merge, anta att du måste skicka ett brev till tio olika personer och att endast namn och adressfält ska uppdateras. I ett sådant fall skapar du helt enkelt en mall för brevet och genererar sedan bokstäverna dynamiskt genom att fylla i namn- och adresssammanslagningsfälten med hjälp av datakällan.

Datakällor för Mail Merge

Data för Mail Merge kan hämtas från vilken datakälla som helst som XML, JSON eller en databas. När det gäller Aspose.Words för .NET kan du använda vilken datakälla som helst som stöds av ADO.NET. Data kan laddas in i en datauppsättning, datatabell, datavy eller en uppsättning värden.

Förbereder mall för brevkoppling

Mail Merge-mallen är dokumentet som innehåller sammanslagningsfälten. Dessa fält fylls sedan i med informationen i datakällan när brevkopplingen körs. Malldokumentet behöver inte vara ett mallformat och det kan vara ett DOC/DOCX-dokument. Så här kan du förbereda en mall för Mail Merge.

Öppna ditt dokument eller skapa ett nytt i MS Word.
Placera markören där du vill lägga till ett sammanfogningsfält.
Välj alternativet Fält på menyn Infoga.
Välj MergeField i listan Fältnamn.
Ange ett namn för sammanslagningsfältet i Fältnamn och tryck på OK.
Spara dokumentet.

Följande är skärmdumpen av dokumentet exempelmall.

.NET Mail Merge API - Installation

Aspose.Words för .NET kan laddas ner eller installeras på följande sätt:

Utför e-postkoppling i Word-dokument med C#

När du har mallen redo kan du köra brevkopplingen för att generera dokumenten. Följande är stegen för att utföra brevkopplingen på den ovan nämnda mallen.

Ladda malldokumentet med klassen Document.
Ställ in önskade alternativ för sammankoppling av brev som Document.MailMerge.TrimWhitespaces.
Kör en sammankoppling av brev med metoden Document.MailMerge.Execute() och skicka datakällan som parameter.
Spara det genererade dokumentet med metoden Document.Save(String).

Följande kodexempel visar hur man kör MS Word Mail Merge med en uppsättning värden i C#.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
// Sökvägen till dokumentkatalogen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
// Öppna ett befintligt dokument.
Document doc = new Document(dataDir + "MailMerge.ExecuteArray.doc");

// Trimma efterföljande och ledande blankstegs kopplingsvärden
doc.MailMerge.TrimWhitespaces = false;

// Fyll i fälten i dokumentet med användardata.
doc.MailMerge.Execute(
    new string[] { "FullName", "Company", "Address", "Address2", "City" },
    new object[] { "James Bond", "MI5 Headquarters", "Milbank", "", "London" });

dataDir = dataDir + "MailMerge.ExecuteArray_out.doc";
// Skicka dokumentet i Word-format till klientens webbläsare med möjlighet att spara på disk eller öppna i den aktuella webbläsaren.
doc.Save(dataDir);

Word-dokument efter brevkoppling

Utför Mail Merge med XML-datakälla i C#

XML-filerna används i stor utsträckning för att lagra samt importera/exportera data. Aspose.Words för .NET stöder också XML som datakälla för Mail Merge. Läs bara in XML i ett DataSet-objekt och kör Mail Merge. Följande är exempel på XML-filen som vi kommer att använda.

<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>

Följande kodexempel hämtar data från en XML-datakälla och kör brevkopplingen med C#.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
// Sökvägen till dokumentkatalogen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 

// Skapa datamängden och läs XML.
DataSet customersDs = new DataSet();
customersDs.ReadXml(dataDir + "Customers.xml");

string fileName = "TestFile XML.doc";
// Öppna ett malldokument.
Document doc = new Document(dataDir + fileName);

// Kör sammanslagningen för att fylla mallen med data från XML med DataTable.
doc.MailMerge.Execute(customersDs.Tables["Customer"]);

dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Spara utdatadokumentet.
doc.Save(dataDir);

Nedan är Mail Merge mall som kommer att fyllas med XML-data.

Följande är sida 1 i det resulterande Word-dokumentet som vi får efter att ha kört Mail Merge.

Anpassad formatering av sammanfogningsfält

Aspose.Words för .NET ger dig mer kontroll över Mail Merge under körningen. Egenskapen MailMerge.FieldMergingCallback låter dig anpassa Mail Merge när något sammanslagningsfält påträffas. MailMerge.FieldMergingCallback accepterar klassen som implementerar metoderna IFieldMergingCallback.FieldMerging och IFieldMergingCallback.ImageFieldMerging.

Följande kodexempel visar hur man anpassar funktionen Mail Merge och tillämpar formatering på cellerna i denna mall.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
// Sökvägen till dokumentkatalogen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

// Lägg till en hanterare för MergeField-händelsen.
doc.MailMerge.FieldMergingCallback = new HandleMergeFieldAlternatingRows();

// Utför e-postsammanslagning med regioner.
DataTable dataTable = GetSuppliersDataTable();
doc.MailMerge.ExecuteWithRegions(dataTable);
dataDir = dataDir + "MailMerge.AlternatingRows_out.doc";
doc.Save(dataDir);

Följande är implementeringen av klassen HandleMergeFieldAlternatingRows.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
private class HandleMergeFieldAlternatingRows : IFieldMergingCallback
{
    ///<summary>
    /// Anropas för varje sammanslagningsfält som påträffas i dokumentet.
    /// Vi kan antingen returnera vissa data till kopplingsmotorn eller göra något
    /// Annat med dokumentet. I det här fallet ändrar vi cellformateringen.
    ///</summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs e)
    {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.Document);

        // På så sätt fångar vi början på en ny rad.
        if (e.FieldName.Equals("CompanyName"))
        {
            // Välj färg beroende på om radnumret är jämnt eller udda.
            Color rowColor;
            if (IsOdd(mRowIdx))
                rowColor = Color.FromArgb(213, 227, 235);
            else
                rowColor = Color.FromArgb(242, 242, 242);

            // Det finns inget sätt att ställa in cellegenskaper för hela raden för tillfället,
            // Så vi måste iterera över alla celler i raden.
           for (int colIdx = 0; colIdx < 4; colIdx++)
            {
                mBuilder.MoveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor;
            }

            mRowIdx++;
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        // Göra ingenting.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}     
///<summary>
/// Returnerar sant om värdet är udda; falskt om värdet är jämnt.
///</summary>
private static bool IsOdd(int value)
{
    // Koden är lite komplex, men annars fungerar inte automatisk konvertering till VB.
    return ((value / 2) * 2).Equals(value);
}      
///<summary>
/// Skapa DataTable och fyll den med data.
/// I verkligheten bör denna datatabell fyllas i från en databas.
///</summary>
private static DataTable GetSuppliersDataTable()
{
    DataTable dataTable = new DataTable("Suppliers");
    dataTable.Columns.Add("CompanyName");
    dataTable.Columns.Add("ContactName");
   for (int i = 0; i < 10; i++)
    {
        DataRow datarow = dataTable.NewRow();
        dataTable.Rows.Add(datarow);
        datarow[0] = "Company " + i.ToString();
        datarow[1] = "Contact " + i.ToString();
    }
    return dataTable;
}

Mail Merge med regioner med C#

Det kan vara fallet när du behöver fylla i och upprepa en viss region i Word-dokumentet. I ett sådant fall kan du använda Mail Merge med regioner. För att skapa en region måste du ange början och slutet av regionen och sedan kommer Mail Megre att upprepa den regionen för varje post i datakällan. Till exempel innehåller följande mall två regioner, Orders och OrderDetails med sammanslagningsfälten «TableStart:Orders», «TableEnd:Orders» och «TableStart:OrderDetails», «TableEnd:OrderDetails» respektive.

Följande är kodexemplet som utför Mail Megre på regioner för ovan nämnda mall.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
// Sökvägen till dokumentkatalogen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
string fileName = "MailMerge.ExecuteWithRegions.doc";
Document doc = new Document(dataDir + fileName);
 
// Använd DataTable som datakälla.
int orderId = 10444;
DataTable orderTable = GetTestOrder(orderId);
doc.MailMerge.ExecuteWithRegions(orderTable);
 
// Istället för att använda DataTable kan du skapa en DataView för anpassad sortering eller filter och sedan sammanfoga e-post.
DataView orderDetailsView = new DataView(GetTestOrderDetails(orderId));
orderDetailsView.Sort = "ExtendedPrice DESC";
 
// Kör sammankopplingsåtgärden.
doc.MailMerge.ExecuteWithRegions(orderDetailsView);
 
// Spara det sammanslagna dokumentet.
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
doc.Save(dataDir);

Följande är metoderna för att läsa data från databasen.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
private static DataTable GetTestOrder(int orderId)
{
    DataTable table = ExecuteDataTable(string.Format(
        "SELECT * FROM AsposeWordOrders WHERE OrderId = {0}", orderId));
    table.TableName = "Orders";
    return table;
}
private static DataTable GetTestOrderDetails(int orderId)
{
    DataTable table = ExecuteDataTable(string.Format(
        "SELECT * FROM AsposeWordOrderDetails WHERE OrderId = {0} ORDER BY ProductID", orderId));
    table.TableName = "OrderDetails";
    return table;
}
///<summary>
/// Verktygsfunktion som skapar en anslutning, kommando, 
/// Utför kommandot och returnerar resultatet i en datatabell.
///</summary>
private static DataTable ExecuteDataTable(string commandText)
{
    // Öppna databasanslutningen.
    string connString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" +
        RunExamples.GetDataDir_Database() + "Northwind.mdb";
    OleDbConnection conn = new OleDbConnection(connString);
    conn.Open();

    // Skapa och kör ett kommando.
    OleDbCommand cmd = new OleDbCommand(commandText, conn);
    OleDbDataAdapter da = new OleDbDataAdapter(cmd);
    DataTable table = new DataTable();
    da.Fill(table);

    // Stäng databasen.
    conn.Close();

    return table;
}

Kapslade kopplingsregioner

Oftast kommer den data vi har i datakällan i form av relationer. Till exempel kommer tabellen “Order” att ha en en-till-många-relation med “OrderDetails” som kommer att hålla register över artiklarna i en beställning. För att hantera sådana förälder-barn-relationer används kapslad Mail Merge. Följande är ett exempel på fakturamall som passar detta scenario.

Följande är exempel på XML-datakällan som vi kommer att använda för den kapslade 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>

OrderSchema.xsd för denna XML är:

<?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>

Följande kodexempel används för att köra den kapslade Mail Merge med C#.

// För fullständiga exempel och datafiler, gå till https://github.com/aspose-words/Aspose.Words-for-.NET
// Sökvägen till dokumentkatalogen.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
	 
// Skapa datamängden och läs XML.
DataSet pizzaDs = new DataSet();
	 
// Datatable.TableNames och DataSet.Relations definieras implicit av .NET genom ReadXml.
pizzaDs.ReadXml(dataDir + "CustomerData.xml");
string fileName = "Invoice Template.doc";

// Öppna malldokumentet.
Document doc = new Document(dataDir + fileName);
	 
// Trimma efterföljande och ledande blankstegs kopplingsvärden.
doc.MailMerge.TrimWhitespaces = false;
	 
// Kör den kapslade e-postsammanfogningen med regioner.
doc.MailMerge.ExecuteWithRegions(pizzaDs);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);

// Spara utdata till fil.
doc.Save(dataDir);

Debug.Assert(doc.MailMerge.GetFieldNames().Length == 0, "There was a problem with mail merge");
Console.WriteLine("\nMail merge performed with nested data successfully.\nFile saved at " + dataDir);

Word-dokument efter brevkoppling

Nedan är den första sidan av det resulterande Word-dokumentet efter att ha kört sammankopplingen.

Slutsats

Aspose.Words för .NET är ett funktionsrikt Mail Merge API som tillhandahåller alla standard- och utökade Mail Merge-funktioner för .NET-applikationer. Inom några få rader kod kan du skapa enkla eller komplexa rapporter från olika typer av datakällor sömlöst. Du kan läsa mer om .NET Mail Merge API från dokumentationen. För att lära dig mer om Aspose.Words för .NET, kom igång med kodexemplen utvecklarguider och GitHub.

Prova Aspose.Words för .NET gratis

Du kan få en gratis tillfällig licens för att prova Aspose.Words för .NET utan några begränsningar. Hämta din tillfälliga licens nu.

Se även

Generera Word-dokument från mallar i C# .NET

Vad är Mail Merge?#

Datakällor för Mail Merge#

Förbereder mall för brevkoppling#

.NET Mail Merge API - Installation#

Utför e-postkoppling i Word-dokument med C##

Word-dokument efter brevkoppling#

Utför Mail Merge med XML-datakälla i C##

Anpassad formatering av sammanfogningsfält#

Mail Merge med regioner med C##

Kapslade kopplingsregioner#

Word-dokument efter brevkoppling#

Slutsats#

Prova Aspose.Words för .NET gratis#

Se även#

Vad är Mail Merge?

Datakällor för Mail Merge

Förbereder mall för brevkoppling

.NET Mail Merge API - Installation

Utför e-postkoppling i Word-dokument med C#

Word-dokument efter brevkoppling

Utför Mail Merge med XML-datakälla i C#

Anpassad formatering av sammanfogningsfält

Mail Merge med regioner med C#

Kapslade kopplingsregioner

Word-dokument efter brevkoppling

Slutsats

Prova Aspose.Words för .NET gratis

Se även