گزارش‌ها را با ادغام پستی C# خودکار کنید | پلاگین ادغام پستی Aspose.Words | File Format Processing Plugins for C# .NET Core

Automating the creation of personalized documents—such as reports, letters, and invoices—can significantly enhance efficiency in your workflow. With C# Mail Merge powered by Aspose.Words for .NET, you can achieve this seamlessly. This guide will walk you through using the Aspose.Words Mail Merge Plugin to perform efficient and scalable document generation within your .NET applications—without the need for MS Word or Office Interop. By the end of this guide, you will be equipped to integrate C# mail merge for report automation and streamline your reporting workflow.

What is Mail Merge?

Mail Merge یک روش قدرتمند برای تولید دینامیک اسناد با پر کردن الگوها با داده‌های از منابع مختلف است. با Aspose.Words، می‌توانید کارهایی مانند:

تولید نامه‌ها و فاکتورها شخصی‌سازی شده.
ایجاد گزارش‌های انبوه با استفاده از فرمت‌های ساختاری مانند XML، JSON یا پایگاه‌داده‌ها، که امکان تولید دینامیک گزارش با C# و Aspose.Words را فراهم می‌کند.

Data Sources for Mail Merge

Aspose.Words از انواع مختلفی از منابع داده پشتیبانی می‌کند، از جمله:

Objects: پر کردن الگوها با استفاده از نمونه‌های کلاس.
XML: بارگذاری داده‌های ساختاری برای فیلدهای دینامیک.
JSON: یکپارچه‌سازی آسان با APIهای مدرن.
CSV: استفاده از داده‌های جدولی برای تولید اسناد انبوه.
DataTable/DataSet: استفاده از ADO.NET برای یکپارچه‌سازی پایگاه‌داده.

Preparing Template for Mail Merge

الگوی mail merge سندی است که شامل فیلدهای ادغامی است که در طول اجرا با داده‌های منبع داده مشخص شما پر می‌شود. الگو می‌تواند در فرمت DOC یا DOCX باشد و نیازی به سبک خاصی ندارد. برای ایجاد یک الگوی mail merge مراحل زیر را دنبال کنید:

سند خود را در MS Word باز کنید یا یک سند جدید ایجاد کنید.
مکان‌نما را در جایی که می‌خواهید یک فیلد ادغامی را وارد کنید قرار دهید.
از منوی Insert گزینه Field را انتخاب کنید.
از لیست Field names گزینه MergeField را انتخاب کنید.
یک نام برای فیلد ادغامی در کادر Field name مشخص کنید و روی OK کلیک کنید.
سند را ذخیره کنید.

تصویر زیر یک الگوی نمونه را نشان می‌دهد.

.NET Mail Merge API - Installation

شما می‌توانید Aspose.Words for .NET را از طریق روش‌های مختلف نصب کنید:

Perform Mail Merge in Word Document using C#

پس از آماده شدن الگو، می‌توانید mail merge را برای تولید اسناد اجرا کنید. مراحل زیر را برای انجام mail merge بر روی الگوی آماده‌شده خود دنبال کنید:

سند الگو را با استفاده از کلاس Document بارگذاری کنید.
گزینه‌های مورد نیاز mail merge را تنظیم کنید، مانند Document.MailMerge.TrimWhitespaces.
mail merge را با استفاده از متد Document.MailMerge.Execute() اجرا کنید و منبع داده را به عنوان پارامتر منتقل کنید.
سند تولیدشده را با استفاده از متد Document.Save(String) ذخیره کنید.

اینجا یک نمونه کد است که نشان می‌دهد چگونه تولید گزارش را در C# با استفاده از یک آرایه از مقادیر خودکار کنیم:

Word Document after Mail Merge

Perform Mail Merge using XML Data Source in C#

فایل‌های XML معمولاً برای ذخیره و انتقال داده‌ها استفاده می‌شوند. Aspose.Words for .NET از XML به عنوان منبع داده برای عملیات mail merge پشتیبانی می‌کند. به سادگی XML را به یک شیء DataSet بخوانید و mail merge را اجرا کنید. در زیر یک فایل XML نمونه برای مورد استفاده ما آورده شده است.

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

نمونه کد زیر داده‌ها را از یک منبع داده XML بازیابی کرده و mail merge را با استفاده از C# اجرا می‌کند.

در زیر الگوی mail merge template آورده شده است که با داده‌های فایل XML پر می‌شود.

این تصویر نمای اول سند Word حاصل پس از اجرای mail merge را نشان می‌دهد.

Custom Formatting of Merge Fields

Aspose.Words for .NET کنترل بهتری بر روی فرآیند mail merge فراهم می‌کند. خاصیت MailMerge.FieldMergingCallback به شما این امکان را می‌دهد که رفتار mail merge را هر بار که با یک فیلد ادغامی مواجه می‌شوید، پیکربندی کنید. پیاده‌سازی متدهای IFieldMergingCallback.FieldMerging و IFieldMergingCallback.ImageFieldMerging امکان شخصی‌سازی عملیات mail merge را فراهم می‌کند.

در زیر یک نمونه کد وجود دارد که نشان می‌دهد چگونه می‌توان فرمت‌بندی سفارشی را در حین mail merge از طریق الگوی نمونه ارائه‌شده اعمال کرد:

دنبال کننده این کلاس HandleMergeFieldAlternatingRows است.

Mail Merge with Regions using C#

در برخی موارد، ممکن است نیاز داشته باشید که یک ناحیه خاص را درون سند Word پر کرده و تکرار کنید. برای چنین سناریوهایی، از mail merge با نواحی استفاده کنید. برای ایجاد یک ناحیه، هم شروع و هم پایان ناحیه را مشخص کنید؛ mail merge سپس این ناحیه را برای هر رکورد در منبع داده تکرار خواهد کرد. مثال الگوی زیر شامل دو ناحیه—Orders و OrderDetails—است که از فیلدهای ادغامی «TableStart:Orders»، «TableEnd:Orders»، «TableStart:OrderDetails» و «TableEnd:OrderDetails» استفاده می‌کند.

اینجا یک نمونه کد وجود دارد که mail merge را بر اساس نواحی برای template ذکر شده قبلی اجرا می‌کند.

روش‌های زیر نشان می‌دهند که چگونه داده‌ها را از یک پایگاه‌داده بخوانید.

Nested Mail Merge

اغلب، داده‌های منبع به صورت فرمت‌های رابطه‌ای ساختار یافته‌اند. به عنوان مثال، “Orders” ممکن است یک رابطه یک به چند با “OrderDetails” داشته باشد که رکوردهای اقلام داخل یک سفارش را نگهداری می‌کند. در چنین سناریوهایی، از mail merge تو در تو استفاده کنید. در زیر یک الگوی فاکتور آورده شده است که برای این سناریو مناسب است.

منبع داده XML مربوط به مثال 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 مربوط به این XML به صورت زیر است:

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

نمونه کد زیر mail merge تو در تو را با استفاده از C# اجرا می‌کند.

Word Document after Mail Merge

در زیر نمای اول سند Word حاصل پس از اجرای mail merge تو در تو آورده شده است.

Conclusion

Aspose.Words for .NET یک API جامع mail merge است که ویژگی‌های استاندارد و پیشرفته‌ای را برای برنامه‌های .NET فراهم می‌کند. تنها با چند خط کد، می‌توانید گزارش‌های ساده یا پیچیده‌ای را از منابع داده متنوع به راحتی توسعه دهید. برای راهنمایی در مورد بهترین شیوه‌های تولید گزارش خودکار .NET، به مستندات مراجعه کنید. برای شروع با Aspose.Words for .NET، راهنماهای راهنمای توسعه‌دهنده و کدهای نمونه موجود در GitHub را بررسی کنید. Aspose Plugin همچنین امکانات پیشرفته‌ای برای تولید گزارش فراهم می‌کند.

Try Aspose.Words for .NET for Free

شما می‌توانید یک مجوز موقت رایگان برای آزمایش Aspose.Words for .NET بدون محدودیت دریافت کنید. مجوز موقت خود را هم‌اکنون دریافت کنید.

Contents#

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

Word Document after Mail Merge#

Perform Mail Merge using XML Data Source in C##

Custom Formatting of Merge Fields#

Mail Merge with Regions using C##

Nested Mail Merge#

Word Document after Mail Merge#

Conclusion#

Try Aspose.Words for .NET for Free#

Contents

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#

Word Document after Mail Merge

Perform Mail Merge using XML Data Source in C#

Custom Formatting of Merge Fields

Mail Merge with Regions using C#

Nested Mail Merge

Word Document after Mail Merge

Conclusion

Try Aspose.Words for .NET for Free