هنگام ایجاد ایمیل‌ها به‌صورت برنامه‌نویسی در C#، افزودن گیرندگان یا پیوست‌ها اغلب تنها گام اول است. ممکن است نیاز داشته باشید ویژگی‌های اضافی را بر روی مورد تازه اضافه‌شده پیکربندی کنید، که به‌صورت سنتی مستلزم افزودن آن به مجموعه و سپس یافتن مجدد آن قبل از اعمال تغییرات بیشتر بود. این جستجوی اضافی می‌تواند کد ایجاد ایمیل را پرحجم‌تر و نگهداری آن را کمتر راحت کند. در این پست وبلاگ، خواهید آموخت که چگونه ایجاد ایمیل در C# را با Aspose.Email for .NET ساده کنید.

Aspose.Email for .NET این جریان کاری را با به‌روزرسانی متدهای Add در MapiAttachmentCollection و MapiRecipientCollection برای برگرداندن نمونهٔ پیوست یا گیرندهٔ تازه ایجاد شده ساده می‌کند. اکنون می‌توانید بلافاصله پس از افزودن، به شیء بازگردانده‌شده دسترسی پیدا کنید و آن را پیکربندی کنید، که کد C# شما را تمیزتر، مستقیم‌تر و نگهداری آن را آسان‌تر می‌سازد. در بخش‌های بعدی، نحوه استفاده از این متدهای پیشرفته را با مثال‌های عملی بررسی خواهیم کرد.

چرا ساده‌سازی ایجاد ایمیل در C#

هنگامی که راه‌حل‌های ایمیل برنامه‌نویسی—مانند اعلان‌های خودکار، فاکتورها یا اسناد تجاری—را می‌سازید، توسعه‌دهندگان اغلب نیاز دارند گیرندگان و پیوست‌ها را اضافه کرده و سپس ویژگی‌های آن‌ها را پیکربندی کنند. با روش سنتی، افزودن یک مورد و پیکربندی آن عملیات جداگانه‌ای بود: ابتدا مورد را به مجموعه اضافه می‌کردید و سپس برای تغییر آن دوباره بازیابی می‌کردید.

به عنوان مثال:

var message = new MapiMessage();

message.Recipients.Add(
    "bob@example.com",
    "SMTP",
    "Bob",
    MapiRecipientType.MAPI_TO);

// Retrieve the recipient from the collection before configuring it.
var recipient = message.Recipients[0];
recipient.DisplayName = "Bob Smith";

این رویکرد زمانی که یک پیام شامل چندین گیرنده یا پیوست باشد، کمتر راحت می‌شود زیرا شما باید موقعیت‌های مجموعه را پیگیری کنید یا یک جستجوی اضافی انجام دهید.

با روش‌های Add بهبود یافته، شیء تازه ایجاد شده مستقیماً بازگردانده می‌شود:

var recipient = message.Recipients.Add(
    "bob@example.com",
    "SMTP",
    "Bob",
    MapiRecipientType.MAPI_TO);

recipient.DisplayName = "Bob Smith";

این باعث می‌شود که کد ساده‌تر باشد و ایجاد شیء و پیکربندی را با هم نگه دارد. مزایای اصلی عبارتند از:

  • کد کمتر – no additional collection lookup is required.
  • قابلیت خوانایی بهتر – the returned object can be configured immediately.
  • مدیریت ساده‌تر شیء – there is no need to depend on a collection index to access the newly added item.
  • کد قابل نگهداری‌تر – creation and customization remain logically connected.

شروع کار با Aspose.Email for .NET

Aspose.Email for .NET یک مدل شیء غنی برای کار با پیام‌های ایمیل و فرمت‌های Microsoft Outlook فراهم می‌کند. کلاس MapiMessage نمایانگر یک پیام MAPI است، در حالی که ویژگی‌های Recipients و Attachments دسترسی به MapiRecipientCollection و MapiAttachmentCollection را به ترتیب فراهم می‌آورند. روش‌های Add پیشرفته در این مجموعه‌ها اشیائی را که ایجاد می‌کنند برمی‌گردانند، به شما امکان می‌دهند که بلافاصله آن‌ها را پیکربندی کنید.

برای شروع، کتابخانه را از طریق NuGet نصب کنید:

Install-Package Aspose.Email

پس از نصب، می‌توانید برای جزئیات ویژگی‌ها به صفحه محصول مراجعه کنید. همچنین مستندات و مرجع API در دسترس هستند:

افزودن گیرندگان و پیوست‌ها با استفاده از نمونه‌های بازگشتی

به‌روزرسانی‌های انجام‌شده در متدهای Add پیکربندی گیرندگان و پیوست‌ها را بلافاصله پس از افزودن آن‌ها به یک MapiMessage آسان‌تر می‌کند. به‌جای افزودن یک مورد و سپس بازیابی آن از مجموعه، می‌توانید نمونهٔ بازگشتی را دریافت کنید و ویژگی‌های آن را مستقیماً تنظیم کنید.

مثال زیر یک MapiMessage ایجاد می‌کند، با استفاده از نمونه‌های بازگردانده‌شده یک گیرنده و پیوست اضافه می‌نماید، ویژگی‌های آن‌ها را پیکربندی می‌کند و پیام را به‌عنوان یک فایل MSG ذخیره می‌نماید.

گام به گام

1. ایجاد شی پیام

با ایجاد یک شیء MapiMessage شروع کنید، که به عنوان مخزن پیام، دریافت‌کنندگان، پیوست‌ها و سایر ویژگی‌های ایمیل عمل می‌کند.

۲. افزودن و پیکربندی گیرنده

از متد Add برای ایجاد یک گیرنده استفاده کنید و شیء MapiRecipient بازگردانده‌شده را به یک متغیر اختصاص دهید. سپس می‌توانید ویژگی‌های آن را بلافاصله بدون جستجو در مجموعه گیرندگان پیکربندی کنید.

3. افزودن و پیکربندی یک پیوست

به‌طور مشابه، از متد Add برای ایجاد یک پیوست استفاده کنید و نمونهٔ بازگشتی MapiAttachment را دریافت کنید. این به شما امکان می‌دهد تا ویژگی‌هایی مانند DisplayName را بلافاصله پس از افزودن پیوست تنظیم کنید.

4. تنظیم ویژگی‌های پیام

ویژگی‌های دیگر پیام، مانند موضوع و بدنه، را در صورت نیاز پیکربندی کنید.

5. ذخیره پیام

در نهایت، پیام MapiMessage تکمیل‌شده را به‌عنوان یک فایل MSG ذخیره کنید. این به شما امکان می‌دهد پیام تولید شده را در یک برنامه ایمیل باز کنید و گیرنده، پیوست و سایر ویژگی‌های پیکربندی‌شده را تأیید کنید.

کد زیر دقیقاً این مراحل را دنبال می‌کند.

مثال زیر نشان می‌دهد که چگونه یک گیرنده و یک پیوست را اضافه کنید و همزمان خصوصیات آن‌ها را با استفاده از C# پیکربندی کنید.

using System;
using System.IO;
using Aspose.Email.Mapi;

class Program
{
    static void Main()
    {
        // Step 1: Create a fresh MapiMessage instance.
        var message = new MapiMessage();

// Step 2: Add a recipient and capture the returned object.
        var recipient = message.Recipients.Add(
            "alice.johnson@example.com", // Email address
            "SMTP",                      // Address type
            "Alice Johnson",             // Display name (initial)
            MapiRecipientType.MAPI_TO);  // Recipient type
        // Immediately update the display name to a more user‑friendly version.
        recipient.DisplayName = "Alice Johnson (Accounts)"; // Overwrites the initial value.

// Step 3: Add an attachment and capture the returned object.
        // The file is read into a byte array; replace the path with a real file.
        var attachment = message.Attachments.Add(
            "invoice.pdf",
            File.ReadAllBytes("invoice.pdf"));
        // Set a friendly display name for the attachment.
        attachment.DisplayName = "Invoice #2026-001.pdf";

// Step 4: Set additional message properties.
        message.Subject = "Your Invoice for August 2026";
        message.Body = "Dear Alice,\n\nPlease find attached your invoice for August 2026.\n\nBest regards,\nFinance Team";

// Step 5: Save the message to an MSG file for verification.
        string outputPath = Path.Combine(Environment.CurrentDirectory, "InvoiceEmail.msg");
        message.Save(outputPath);
        Console.WriteLine($"Message saved to {outputPath}");
    }
}

توضیح کد

  • new MapiMessage() – یک پیام MAPI جدید ایجاد می‌کند که شامل گیرندگان، پیوست‌ها، موضوع، بدنه و سایر ویژگی‌های پیام خواهد بود.
  • message.Recipients.Add(...) – یک گیرنده اضافه می‌کند و نمونه‌ی تازه ایجاد شده‌ی MapiRecipient را برمی‌گرداند که در متغیر recipient ذخیره می‌شود.
  • recipient.DisplayName = "Alice Johnson (Accounts)"; – گیرنده‌ی بازگردانده‌شده را بلافاصله پیکربندی می‌کند، بدون این‌که از مجموعه استخراج شود.
  • message.Attachments.Add(...) – فایل invoice.pdf را اضافه می‌کند و نمونه‌ی تازه ایجاد شده‌ی MapiAttachment را برمی‌گرداند.
  • attachment.DisplayName = "Invoice #2026-001.pdf"; – نام نمایشی پیوست تازه اضافه‌شده را سفارشی می‌کند.
  • message.Subject and message.Body – موضوع و محتوای متنی ساده ایمیل را تنظیم می‌کند.
  • message.Save(outputPath) – پیام تکمیل‌شده را به‌صورت یک فایل MSG ذخیره می‌کند.

چون متدهای Add اکنون اشیاء ایجاد شده را برمی‌گردانند، می‌توانید بلافاصله آن‌ها را پیکربندی کنید یا مراجع را برای استفادهٔ بعدی ذخیره کنید.

دریافت لایسنس رایگان

Aspose موقت‌اً مجوزهایی ارائه می‌دهد که به شما امکان ارزیابی کامل مجموعه ویژگی‌ها را بدون محدودیت می‌دهد. یک مجوز آزمایشی رایگان را از اینجا دریافت کنید: https://purchase.aspose.com/temporary-license/

نتیجه‌گیری

روش‌های پیشرفته Add در Aspose.Email for .NET ایجاد برنامه‌ای ایمیل را راحت‌تر می‌کند، زیرا به‌صورت مستقیم شیء‌های تازه‌ساخته MapiRecipient و MapiAttachment را برمی‌گرداند. این کار نیاز به جستجوی اضافی در مجموعه را زمانی که می‌خواهید مورد تازه اضافه‌شده را پیکربندی کنید، حذف می‌کند.

در این پست وبلاگ، ما یک MapiMessage ایجاد کردیم، یک گیرنده و یک پیوست اضافه کردیم، ویژگی‌های آن‌ها را بلافاصله پیکربندی کردیم و پیام را به عنوان یک فایل MSG ذخیره کردیم. با استفاده از نمونه‌های بازگردانده‌شده، می‌توانید کد تولید ایمیل C# را بنویسید که مستقیم‌تر، قابل خواندن‌تر و قابل نگهداری‌تر باشد.

سؤالات متداول

  1. آیا متدهای جدید Add جایگزین متدهای موجود می‌شوند؟ خیر. پارامترهای متدهای موجود همانند قبلی باقی می‌مانند، در حالی که متدها اکنون شیء دریافت‌کننده یا پیوست تازه ایجاد شده را برمی‌گردانند. می‌توانید شیء بازگردانده‌شده را زمانی که نیاز به پیکربندی فوری آن دارید، دریافت کنید.

  2. آیا برای استفاده از نمونه‌های بازگردانده‌شده کد اضافی‌ای لازم است؟ خیر. به سادگی MapiRecipient یا MapiAttachment بازگردانده‌شده را به یک متغیر اختصاص دهید و ویژگی‌های آن را بر حسب نیاز پیکربندی کنید.

  3. آیا هنوز می‌توانم از مجموعه برای دسترسی به گیرندگان و پیوست‌ها استفاده کنم؟ بله. مجموعه‌ها همچنان دسترسی به آیتم‌های خود را فراهم می‌کنند. نمونه‌های بازگردانده شده به سادگی راهی مستقیم‌تر برای کار با یک آیتم بلافاصله پس از اضافه شدن آن فراهم می‌آورند.

  4. آیا این تغییرات بر نحوه ذخیره یا سریال‌سازی یک MapiMessage تأثیر می‌گذارند؟ خیر. پیام می‌تواند با استفاده از همان APIها ذخیره و سریال‌سازی شود. این بهبود فقط باعث می‌شود که اشیاء گیرنده و پیوست تازه‌ساخته شده بلافاصله پس از عملیات Add در دسترس باشند.

  5. آیا برای استفاده از این ویژگی‌ها به مجوز خاصی نیاز دارم؟ این ویژگی‌ها به عنوان بخشی از Aspose.Email for .NET در دسترس هستند و تحت شرایط مجوز استاندارد Aspose.Email قرار دارند.

بیشتر بخوانید