C# Serienbrief-API | MS Word Serienbrief-API for .NET

In diesem Artikel zeige ich Ihnen, wie Sie einen MS Word-Seriendruck mit C# oder VB.NET ohne MS Word oder Office Interop durchführen. Aspose.Words for .NET ist eine funktionsreiche und leistungsstarke Word-API, die alle grundlegenden sowie erweiterten Seriendruckfunktionen von MS Word bietet. Sie können damit Briefe, Umschläge, Berichte, Rechnungen und andere Arten von Dokumenten in Windows Forms, ASP.NET Webanwendungen oder jeder .NET/.NET Core Anwendung erstellen.

Dieser Artikel behandelt die herausragenden Funktionen unserer .NET Mail Merge API und besteht aus den folgenden Abschnitten:

Was ist Seriendruck?
Datenquellen für den Seriendruck
Vorlage für den Seriendruck vorbereiten
.NET-Seriendruck-API – Installation
Seriendruck in Word Dokument mit C# durchführen
Seriendruck mit XML Daten quelle
Benutzerdefinierte Formatierung von Briefvorlagenfeldern
Seriendruck mit Regionen
Verschachtelte Seriendruckbereiche

Was ist Seriendruck?

Seriendruck ist die Methode zur automatisierten Erstellung von Berichten, Briefen, Umschlägen, Rechnungen und anderen Arten von Dokumenten. Seriendruck in MS Word ermöglicht es Ihnen, ein Vorlagendokument mit Briefvorlagenfeldern zu erstellen und diese Felder dann mit Datensätzen in der Datenquelle auszufüllen. Um den Seriendruck zu verstehen, nehmen Sie an, Sie müssen einen Brief an zehn verschiedene Personen senden und nur der Name und die Adressfelder sollen aktualisiert werden. Erstellen Sie in einem solchen Fall einfach eine Vorlage für den Brief und generieren Sie die Briefe dann dynamisch, indem Sie die Briefvorlagenfelder für Name und Adresse mithilfe der Datenquelle ausfüllen.

Datenquellen für den Seriendruck

Die Daten für den Seriendruck können aus einer beliebigen Datenquelle wie XML, JSON oder einer Datenbank abgerufen werden. Was Aspose.Words for .NET betrifft, können Sie jede Datenquelle verwenden, die von ADO.NET unterstützt wird. Die Daten können in ein DataSet, eine DataTable, eine DataView oder ein Array von Werten geladen werden.

Vorlage für den Seriendruck vorbereiten

Die Seriendruckvorlage ist das Dokument, das die Seriendruckfelder enthält. Diese Felder werden dann mit den Daten in der Datenquelle gefüllt, wenn der Seriendruck ausgeführt wird. Das Vorlagendokument muss kein Vorlagenformat sein und kann ein DOC/DOCX-Dokument sein. So bereiten Sie eine Vorlage für den Seriendruck vor.

Öffnen Sie Ihr Dokument oder erstellen Sie ein neues in MS Word.
Platzieren Sie den Cursor an der Stelle, an der Sie ein Briefvorlagenfeld hinzufügen möchten.
Wählen Sie im Menü Einfügen die Option Feld aus.
Wählen Sie aus der Liste Feldnamen MergeField aus.
Geben Sie unter Feldname einen Namen für das Briefvorlagenfeld ein und drücken Sie OK.
Speichern Sie das Dokument.

Das Folgende ist der Screenshot des Dokuments Beispielvorlage.

.NET-Seriendruck-API – Installation

Aspose.Words for .NET kann auf folgende Weise heruntergeladen oder installiert werden:

Seriendruck in Word Dokument mit C# durchführen

Sobald Sie die Vorlage fertig haben, können Sie den Seriendruck ausführen, um die Dokumente zu generieren. Im Folgenden sind die Schritte zum Ausführen des Seriendrucks auf der oben genannten Vorlage aufgeführt.

Laden Sie das Vorlagendokument mit der Klasse Document.
Legen Sie die erforderlichen Seriendruckoptionen wie Document.MailMerge.TrimWhitespaces fest.
Führen Sie einen Seriendruck mit der methode Document.MailMerge.Execute() aus und übergeben Sie die Datenquelle als Parameter.
Speichern Sie das generierte Dokument mit der methode Document.Save(String).

Das folgende Codebeispiel zeigt, wie MS Word Mail Merge mithilfe eines Arrays von Werten in C# ausgeführt wird.

// Vollständige Beispiele und Datendateien finden Sie unter https://github.com/aspose-words/Aspose.Words-for-.NET
// Der Pfad zum Dokumentenverzeichnis.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
// Öffnen Sie ein vorhandenes Dokument.
Document doc = new Document(dataDir + "MailMerge.ExecuteArray.doc");

// Kürzen Sie nachgestellte und führende Leerzeichen für Seriendruckwerte
doc.MailMerge.TrimWhitespaces = false;

// Füllen Sie die Felder im Dokument mit Benutzerdaten.
doc.MailMerge.Execute(
    new string[] { "FullName", "Company", "Address", "Address2", "City" },
    new object[] { "James Bond", "MI5 Headquarters", "Milbank", "", "London" });

dataDir = dataDir + "MailMerge.ExecuteArray_out.doc";
// Senden Sie das Dokument im Word Format an den Client-Browser mit der Option, es auf der Festplatte zu speichern oder im aktuellen Browser zu öffnen.
doc.Save(dataDir);

Word Dokument nach dem Seriendruck

Seriendruck mit XML Daten quelle in C# durchführen

Die XML Dateien werden häufig zum Aufbewahren sowie zum Importieren/Exportieren von Daten verwendet. Aspose.Words for .NET unterstützt auch XML als Datenquelle für den Seriendruck. Lesen Sie einfach das XML in ein DataSet objekt ein und führen Sie den Seriendruck aus. Das Folgende ist die Beispiel-XML Datei, die wir verwenden werden.

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

Das folgende Codebeispiel ruft die Daten aus einer XML Daten quelle ab und führt den Seriendruck mit C# aus.

// Vollständige Beispiele und Datendateien finden Sie unter https://github.com/aspose-words/Aspose.Words-for-.NET
// Der Pfad zum Dokumentenverzeichnis.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 

// Erstellen Sie das Dataset und lesen Sie das XML.
DataSet customersDs = new DataSet();
customersDs.ReadXml(dataDir + "Customers.xml");

string fileName = "TestFile XML.doc";
// Öffnen Sie ein Vorlagendokument.
Document doc = new Document(dataDir + fileName);

// Führen Sie einen Seriendruck aus, um die Vorlage mithilfe von DataTable mit Daten aus XML zu füllen.
doc.MailMerge.Execute(customersDs.Tables["Customer"]);

dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Speichern Sie das Ausgabedokument.
doc.Save(dataDir);

Unten sehen Sie die Seriendruck-Vorlage, die mit XML Daten gefüllt wird.

Das Folgende ist Seite 1 des resultierenden Word Dokuments, das wir nach dem Ausführen des Seriendrucks erhalten.

Benutzerdefinierte Formatierung von Briefvorlagenfeldern

Aspose.Words for .NET gibt Ihnen mehr Kontrolle über den Seriendruck während der Ausführung. Mit der Eigenschaft MailMerge.FieldMergingCallback können Sie den Seriendruck anpassen, wenn ein Seriendruckfeld gefunden wird. MailMerge.FieldMergingCallback akzeptiert die Klasse, die die Methoden IFieldMergingCallback.FieldMerging und IFieldMergingCallback.ImageFieldMerging implementiert.

Das folgende Codebeispiel zeigt, wie Sie den Seriendruckvorgang anpassen und die Formatierung auf die Zellen in dieser Vorlage anwenden.

// Vollständige Beispiele und Datendateien finden Sie unter https://github.com/aspose-words/Aspose.Words-for-.NET
// Der Pfad zum Dokumentenverzeichnis.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

// Fügen Sie einen Handler für das MergeField-Ereignis hinzu.
doc.MailMerge.FieldMergingCallback = new HandleMergeFieldAlternatingRows();

// Seriendruck mit Regionen ausführen.
DataTable dataTable = GetSuppliersDataTable();
doc.MailMerge.ExecuteWithRegions(dataTable);
dataDir = dataDir + "MailMerge.AlternatingRows_out.doc";
doc.Save(dataDir);

Das Folgende ist die Implementierung der HandleMergeFieldAlternatingRows Klasse.

// Vollständige Beispiele und Datendateien finden Sie unter https://github.com/aspose-words/Aspose.Words-for-.NET
private class HandleMergeFieldAlternatingRows : IFieldMergingCallback
{
    ///<summary>
    /// Wird für jedes im Dokument gefundene Briefvorlagenfeld aufgerufen.
    /// Wir können entweder einige Daten an die Mail-Merge-Engine zurückgeben oder etwas tun
    /// Sonst mit dem Dokument. In diesem Fall ändern wir die Zellenformatierung.
    ///</summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs e)
    {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.Document);

        // Auf diese Weise fangen wir den Anfang einer neuen Reihe.
        if (e.FieldName.Equals("CompanyName"))
        {
            // Wählen Sie die Farbe abhängig davon, ob die Zeilennummer gerade oder ungerade ist.
            Color rowColor;
            if (IsOdd(mRowIdx))
                rowColor = Color.FromArgb(213, 227, 235);
            else
                rowColor = Color.FromArgb(242, 242, 242);

            // Momentan gibt es keine Möglichkeit, Zelleigenschaften für die gesamte Zeile festzulegen.
            // Wir müssen also über alle Zellen in der Zeile iterieren.
            for (int colIdx = 0; colIdx < 4; colIdx++)
            {
                mBuilder.MoveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.CellFormat.Shading.BackgroundPatternColor = rowColor;
            }

            mRowIdx++;
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        // Nichts tun.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}     
///<summary>
/// Gibt wahr zurück, wenn der Wert ungerade ist; false, wenn der Wert gerade ist.
///</summary>
private static bool IsOdd(int value)
{
    // Der Code ist etwas komplex, aber ansonsten funktioniert die automatische Konvertierung nach VB nicht.
    return ((value / 2) * 2).Equals(value);
}      
///<summary>
/// DataTable erstellen und mit Daten füllen.
/// Im wirklichen Leben sollte diese DataTable aus einer Datenbank gefüllt werden.
///</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;
}

Seriendruck mit Regionen mit C#

Es kann vorkommen, dass Sie einen bestimmten Bereich im Word Dokument ausfüllen und wiederholen müssen. Für einen solchen Fall können Sie den Seriendruck mit Regionen verwenden. Um eine Region zu erstellen, müssen Sie den Anfang und das Ende der Region angeben, und dann wiederholt Mail Megre diese Region für jeden Datensatz in der Datenquelle. Beispiel: Die folgende Vorlage enthält zwei Regionen, Orders und OrderDetails mit den Briefvorlagenfeldern «TableStart:Orders», «TableEnd:Orders» bzw. «TableStart:OrderDetails», «TableEnd:OrderDetails».

Das Folgende ist das Codebeispiel, das Mail Megre in Regionen für die oben genannte Vorlage ausführt.

// Vollständige Beispiele und Datendateien finden Sie unter https://github.com/aspose-words/Aspose.Words-for-.NET
// Der Pfad zum Dokumentenverzeichnis.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting();
string fileName = "MailMerge.ExecuteWithRegions.doc";
Document doc = new Document(dataDir + fileName);
 
// Verwenden Sie DataTable als Datenquelle.
int orderId = 10444;
DataTable orderTable = GetTestOrder(orderId);
doc.MailMerge.ExecuteWithRegions(orderTable);
 
// Anstatt DataTable zu verwenden, können Sie eine DataView für benutzerdefiniertes Sortieren oder Filtern und dann für den Seriendruck erstellen.
DataView orderDetailsView = new DataView(GetTestOrderDetails(orderId));
orderDetailsView.Sort = "ExtendedPrice DESC";
 
// Führen Sie den Seriendruckvorgang aus.
doc.MailMerge.ExecuteWithRegions(orderDetailsView);
 
// Speichern Sie das zusammengeführte Dokument.
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
doc.Save(dataDir);

Im Folgenden sind die Methoden zum Lesen von Daten aus der Datenbank aufgeführt.

// Vollständige Beispiele und Datendateien finden Sie unter 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>
/// Hilfsfunktion, die eine Verbindung herstellt, Befehl, 
/// Führt den Befehl aus und gibt das Ergebnis in einer DataTable zurück.
///</summary>
private static DataTable ExecuteDataTable(string commandText)
{
    // Öffnen Sie die Datenbankverbindung.
    string connString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" +
        RunExamples.GetDataDir_Database() + "Northwind.mdb";
    OleDbConnection conn = new OleDbConnection(connString);
    conn.Open();

    // Befehl erstellen und ausführen.
    OleDbCommand cmd = new OleDbCommand(commandText, conn);
    OleDbDataAdapter da = new OleDbDataAdapter(cmd);
    DataTable table = new DataTable();
    da.Fill(table);

    // Schließen Sie die Datenbank.
    conn.Close();

    return table;
}

Verschachtelte Seriendruckbereiche

Meistens liegen die Daten in der Datenquelle in Form von Beziehungen vor. Beispielsweise hat die Tabelle „Order“ eine Eins zu Viele-Beziehung mit den „OrderDetails“, die Aufzeichnungen über die Artikel in einer Bestellung führen. Um mit solchen Eltern-Kind-Beziehungen fertig zu werden, wird verschachtelter Seriendruck verwendet. Das Folgende ist ein Beispiel für eine Rechnungsvorlage, das sich gut für dieses Szenario eignet.

Das Folgende ist die Beispiel-XML Daten quelle, die wir für den verschachtelten Seriendruck verwenden.

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

Wohingegen die OrderSchema.xsd für dieses XML ist:

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

Das folgende Codebeispiel wird verwendet, um den verschachtelten Seriendruck mit C# auszuführen.

// Vollständige Beispiele und Datendateien finden Sie unter https://github.com/aspose-words/Aspose.Words-for-.NET
// Der Pfad zum Dokumentenverzeichnis.
string dataDir = RunExamples.GetDataDir_MailMergeAndReporting(); 
	 
// Erstellen Sie das Dataset und lesen Sie das XML.
DataSet pizzaDs = new DataSet();
	 
// Die Datatable.TableNames und die DataSet.Relations werden implizit von .NET über ReadXml definiert.
pizzaDs.ReadXml(dataDir + "CustomerData.xml");
string fileName = "Invoice Template.doc";

// Öffnen Sie das Vorlagendokument.
Document doc = new Document(dataDir + fileName);
	 
// Kürzen Sie nachgestellte und führende Leerzeichen für Seriendruckwerte.
doc.MailMerge.TrimWhitespaces = false;
	 
// Führen Sie den verschachtelten Seriendruck mit Regionen aus.
doc.MailMerge.ExecuteWithRegions(pizzaDs);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);

// Speichern Sie die Ausgabe in einer Datei.
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 nach dem Seriendruck

Unten sehen Sie die erste Seite des resultierenden Word Dokuments nach dem Ausführen des Seriendrucks.

Fazit

Aspose.Words for .NET ist eine funktionsreiche Serienbrief-API, die alle Standard und erweiterten Serienbrieffunktionen für .NET Anwendungen bereitstellt. Innerhalb weniger Codezeilen können Sie nahtlos einfache oder komplexe Berichte aus verschiedenen Arten von Datenquellen erstellen. Weitere Informationen zur .NET-Seriendruck-API finden Sie in der Dokumentation. Um mehr über Aspose.Words for .NET zu erfahren, beginnen Sie mit den Codebeispielen Entwicklerhandbücher und GitHub.

Probieren Sie Aspose.Words for .NET kostenlos aus

Sie können eine kostenlose temporäre Lizenz erhalten, um Aspose.Words for .NET ohne Einschränkungen zu testen. Holen Sie sich jetzt Ihre temporäre Lizenz.

Siehe auch

Generieren Sie Word Dokumente aus Vorlagen in C# .NET

Was ist Seriendruck?#

Datenquellen für den Seriendruck#

Vorlage für den Seriendruck vorbereiten#

.NET-Seriendruck-API – Installation#

Seriendruck in Word Dokument mit C# durchführen#

Word Dokument nach dem Seriendruck#

Seriendruck mit XML Daten quelle in C# durchführen#

Benutzerdefinierte Formatierung von Briefvorlagenfeldern#

Seriendruck mit Regionen mit C##

Verschachtelte Seriendruckbereiche#

Word Dokument nach dem Seriendruck#

Fazit#

Probieren Sie Aspose.Words for .NET kostenlos aus#

Siehe auch#

Was ist Seriendruck?

Datenquellen für den Seriendruck

Vorlage für den Seriendruck vorbereiten

.NET-Seriendruck-API – Installation

Seriendruck in Word Dokument mit C# durchführen

Word Dokument nach dem Seriendruck

Seriendruck mit XML Daten quelle in C# durchführen

Benutzerdefinierte Formatierung von Briefvorlagenfeldern

Seriendruck mit Regionen mit C#

Verschachtelte Seriendruckbereiche

Word Dokument nach dem Seriendruck

Fazit

Probieren Sie Aspose.Words for .NET kostenlos aus

Siehe auch