Mail Merge

Serienbrief

Dieser Leitfaden zeigt, wie man mit Mail-Merge-Feldcodes und Mail-Merge-Konfigurationsdaten in Aspose.Words FOSS für .NET arbeitet und wo die Grenze zur Merge-Ausführung liegt. Aspose.Words FOSS für .NET erkennt und aktualisiert die Word-Mail-Merge-Feldcodes — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF, und SKIPIF — als Teil seiner Feldauswertungs-Engine und kann die Mail-Merge-Konfigurationsdaten (MailMergeSettings) gespeichert in einem Dokument. Einen tatsächlichen Merge gegen eine externe Datenquelle ausführen, um ausgefüllte Ausgabedokumente zu erzeugen — das MailMerge.Execute() workflow bekannt aus dem kommerziellen Produkt — ist not in dieser Ausgabe implementiert; kein MailMerge Ausführungsklasse in der aktuellen API-Oberfläche existiert.

MERGEFIELD — Lesen und Ändern von Merge-Platzhaltern

FieldMergeField implementiert das MERGEFIELD-Feld. FieldName und FieldNameNoPrefix geben den zugrunde liegenden Spaltennamen der Datenquelle zurück, an den das Feld gebunden ist, TextBefore/TextAfter enthalten wörtlichen Text, der um den zusammengeführten Wert herumliegt, und IsMapped/IsVerticalFormatting geben das Merge-Feld-Mapping und Layout-Flags zurück. Wie jeder Feldtyp unterstützt es GetFieldCode(), Update(), Unlink() und Remove().

ADDRESSBLOCK und GREETINGLINE

FieldAddressBlock implementiert das ADDRESSBLOCK-Feld, wobei FormatAddressOnCountryOrRegion, IncludeCountryOrRegionName, ExcludedCountryOrRegionName, NameAndAddressFormat und LanguageId steuern, wie die Adresse des Empfängers formatiert wird. FieldGreetingLine implementiert GREETINGLINE, wobei AlternateText, NameFormat und LanguageId den Anrede-Text steuern.

DATABASE-Feld

FieldDatabase implementiert das DATABASE-Feld und stellt die in dem Feld gespeicherten Verbindungsdetails bereit: Connection, FileName, Query, TableFormat, InsertHeadings, InsertOnceOnMailMerge, FirstRecord und LastRecord. Um Abfrageergebnisse bereitzustellen, wenn dieses Feld aktualisiert wird, implementieren Sie IFieldDatabaseProvider und dessen GetQueryResult(fileName, connection, query, field)-Methode, und weisen Sie es Document.FieldOptions.FieldDatabaseProvider zu, bevor Sie Update() aufrufen. Die Eigenschaft Connection muss gesetzt werden – ohne sie hat Update() keine Datenquelle zum Abfragen.

Bedingte Seriendatenfelder — NEXTIF und SKIPIF

FieldNextIf und FieldSkipIf implementieren die Felder NEXTIF und SKIPIF, die jeweils LeftExpression, ComparisonOperator und RightExpression für den bedingten Test bereitstellen. Document.FieldOptions.ComparisonExpressionEvaluator (ein IComparisonExpressionEvaluator) kann überschreiben, wie diese bedingten Ausdrücke ausgewertet werden.

Größenbestimmung des Bild-Seriendatenfelds

MergeFieldImageDimension steht für eine Breite oder Höhe eines Bildes, das über ein Bild-Seriendatenfeld eingefügt wird, konstruiert als new MergeFieldImageDimension(value) (in Punkten) oder new MergeFieldImageDimension(value, unit) mit einem expliziten MergeFieldImageDimensionUnit (Point oder Percent). Seine Value- und Unit-Eigenschaften sind beide schreibbar.

Was im Geltungsbereich liegt und was nicht

Document.MailMergeSettings gibt ein MailMergeSettings Objekt, das die Mail-Merge-Konfiguration modelliert, OOXML bleibt innerhalb eines Dokuments erhalten — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, und die Office Data Source Object (ODSO)-Einstellungen über OdsoFieldMapData/OdsoRecipientData Sammlungen. Dies ist Konfiguration data die das Dokument trägt, keine Live-Verbindung: Lesen und Schreiben MailMergeSettings stellt keine Verbindung zu einer Datenbank, Tabelle oder Adressliste her, und diese Ausgabe hat keine MailMerge Ausführungsklasse, um einen Merge auszuführen und daraus ausgefüllte Ausgabedokumente zu erzeugen. Was diese Ausgabe jedoch unterstützt, ist die darüber liegende Feld-Ebene: das Erkennen, Lesen, Aktualisieren und Ändern der Merge-Feldcodes selbst innerhalb eines einzelnen Dokuments über die Feldauswertung-Engine.

Tipps und bewährte Vorgehensweisen

• Behandle MailMergeSettings als Dokumenten-Metadaten, die Sie lesen und round-trip verwenden können, nicht als ein API zum Anschließen an externe Daten — in dieser Ausgabe gibt es keine Ausführungs-Engine dahinter.
• Setzen Sie immer FieldDatabase.Connection, bevor Sie Update() auf einem DATABASE-Feld aufrufen, sonst hat das Update nichts zum Abfragen.
• Implementieren Sie IFieldDatabaseProvider einmal und weisen Sie es über Document.FieldOptions.FieldDatabaseProvider zu, um zu zentralisieren, wie alle DATABASE-Felder in einem Dokument ihre Daten auflösen.
• Verwenden Sie FieldMergeField.FieldName, um zu lesen, an welche Datenquellen-Spalte ein MERGEFIELD gebunden ist, bevor Sie entscheiden, wie Sie es programmatisch verarbeiten.

Häufige Probleme

FAQ

Kann ich in dieser Ausgabe einen Mail-Merge gegen eine CSV-Datei oder Datenbank ausführen?

Nein. Diese Ausgabe implementiert die Mail-Merge-Feldcodes und das MailMergeSettings-Konfigurationsdatenmodell, aber es gibt keine MailMerge-Ausführungsklasse, um eine Verbindung zu einer externen Datenquelle herzustellen und ausgefüllte Dokumente zu erzeugen.

Was kann ich dann tatsächlich mit MERGEFIELD-Feldern machen?

Sie können sie direkt lesen und ändern — FieldMergeField.FieldName für den gebundenen Spaltennamen, TextBefore/TextAfter für umgebenden Literaltext und Update()/Unlink()/Remove() wie jedes andere Feld — im aktuellen Dokument.

Ist MailMergeSettings ohne Merge-Ausführung nutzlos?

Nein — es ist weiterhin nützlich, um die im Dokument gespeicherte Mail-Merge-Konfiguration zu lesen oder zu round-tripping, beispielsweise DataSource, Query oder MainDocumentType, obwohl diese Ausgabe nicht auf dieser Konfiguration basiert, um einen Merge auszuführen.

Wie stelle ich Daten für ein DATABASE-Feld bereit?

Implementieren Sie IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) und weisen Sie Ihre Implementierung Document.FieldOptions.FieldDatabaseProvider zu, bevor Sie Update() aufrufen.

Wie kann ich die Größe eines Bildes steuern, das durch ein Bild-Merge-Feld eingefügt wird?

Verwenden Sie MergeFieldImageDimension, erstellt mit einem Punktwert oder einem Wert plus einem expliziten MergeFieldImageDimensionUnit (Point oder Percent).

API Reference Zusammenfassung

Siehe auch

• Aspose.Words for .NET — Enterprise Documentation