پیاده‌سازی خروجی اکسل در پروژه‌ Web API با استفاده از پکیج EPPlus

خروجی اکسل، EPPlus، Export Excel، تولید فایل Excel، سرویس خروجی اکسل 1404/8/25
نویسنده: مدرس بهمن آبادی

پیاده‌سازی خروجی اکسل در پروژه‌ Web API با استفاده از پکیج EPPlus

خروجی اکسل در نرم افزار

مقدمه

در بسیاری از پروژه‌های سازمانی، نیاز است که داده‌ها به‌صورت فایل اکسل (Excel) در اختیار کاربران قرار گیرد. این قابلیت معمولاً در سیستم‌های گزارش‌گیری، داشبوردهای مدیریتی و سامانه‌های مالی مورد استفاده قرار می‌گیرد. در معماری‌های مبتنی بر Web API، تولید خروجی اکسل باید به شکلی انجام شود که:

  • سریع باشد

  • نیاز به نصب Office نداشته باشد

  • حجم فایل کم باشد

  • فرمت استاندارد و قابل استفاده ارائه شود

یکی از بهترین کتابخانه‌ها برای این منظور، EPPlus است که به‌طور کامل با فرمت Office Open XML (فایل‌های ‎.xlsx‎) کار می‌کند و وابستگی به آفیس ندارد.

آشنایی با EPPlus

پکیج EPPlus یک کتابخانه‌ی قدرتمند برای ساخت، ویرایش و خواندن فایل‌های اکسل در بستر دات‌نت است. این پکیج با نسخه‌های مختلف دات نت کاملاً سازگار بوده و امکاناتی نظیر:

  • ساخت شیت‌های جدید

  • استایل‌دهی

  • ایجاد جدول (Table)

  • فرمول‌ها

  • تنظیمات Page Layout

  • و خروجی مستقیم فایل

را فراهم می‌کند.

نصب پکیج

برای نصب EPPlus کافی است دستور زیر را در کنسول NuGet اجرا کنید:

Install-Package EPPlus

یا در فایل ‎.csproj‎:

<PackageReference Include="EPPlus" Version="6.2.0" />

پیاده‌سازی سرویس خروجی اکسل در Web API

‏۱) ایجاد یک اکشن برای خروجی گرفتن فایل

در این مثال داده‌های فرضی را دریافت کرده و در قالب اکسل خروجی می‌دهیم.

[HttpGet("export-excel")]
public IActionResult ExportExcel()
{
    // نمونه داده
    var data = new List<Person>()
    {
        new Person { Id = 1, Name = "Ali", Age = 30 },
        new Person { Id = 2, Name = "Sara", Age = 25 }
    };

    using (var package = new OfficeOpenXml.ExcelPackage())
    {
        ExcelWorksheet sheet = package.Workbook.Worksheets.Add("Report");

        // عنوان ستون‌ها
        sheet.Cells[1, 1].Value = "ID";
        sheet.Cells[1, 2].Value = "Name";
        sheet.Cells[1, 3].Value = "Age";

        int row = 2;
        foreach (var item in data)
        {
            sheet.Cells[row, 1].Value = item.Id;
            sheet.Cells[row, 2].Value = item.Name;
            sheet.Cells[row, 3].Value = item.Age;

            row++;
        }

        // ایجاد جدول خودکار
        var range = sheet.Cells[1, 1, row - 1, 3];
        var table = sheet.Tables.Add(range, "ReportTable");
        table.TableStyle = OfficeOpenXml.Table.TableStyles.Medium6;

        // تولید فایل
        var fileBytes = package.GetAsByteArray();
        return File(fileBytes, 
            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "report.xlsx");
    }
}

نکات مهم در استفاده از EPPlus

‏۱) لایسنس EPPlus

از نسخه ۵ به بعد، EPPlus دارای لایسنس Polyform Noncommercial است.
برای پروژه‌های تجاری باید:

استفاده شود یا لایسنس مناسب تهیه گردد.

۲) تنظیم خودکار اندازه ستون‌ها

برای خوانایی بهتر خروجی:

sheet.Cells[sheet.Dimension.Address].AutoFitColumns();

۳) ایجاد استایل

نمونه‌ای از استایل‌دهی به عنوان ستون‌ها:

using (var range = sheet.Cells[1, 1, 1, 3])
{
    range.Style.Font.Bold = true;
    range.Style.Fill.PatternType = OfficeOpenXml.Style.ExcelFillStyle.Solid;
    range.Style.Fill.BackgroundColor.SetColor(System.Drawing.Color.LightGray);
}

۴) مدیریت حجم فایل

برای داده‌های حجیم می‌توان:

  • شیت‌ها را جدا کرد

  • از Stream استفاده کرد

  • از Table برای بهینه‌سازی رندر استفاده کرد

ایجاد یک سرویس مجزا برای سازمان‌دهی بهتر کد

به‌جای نوشتن تمام منطق در Controller، یک سرویس بسازید:

public interface IExcelExportService
{
    byte[] GeneratePersonReport(List<Person> data);
}

public class ExcelExportService : IExcelExportService
{
    public byte[] GeneratePersonReport(List<Person> data)
    {
        using var package = new ExcelPackage();
        var sheet = package.Workbook.Worksheets.Add("Report");

        sheet.Cells[1, 1].Value = "ID";
        sheet.Cells[1, 2].Value = "Name";
        sheet.Cells[1, 3].Value = "Age";

        int row = 2;
        foreach (var item in data)
        {
            sheet.Cells[row, 1].Value = item.Id;
            sheet.Cells[row, 2].Value = item.Name;
            sheet.Cells[row, 3].Value = item.Age;
            row++;
        }

        return package.GetAsByteArray();
    }
}

و در کنترلر فقط آن را فراخوانی کنید:

[HttpGet("export-excel")]
public IActionResult ExportExcel([FromServices] IExcelExportService service)
{
    var data = _personRepository.GetAll();
    var file = service.GeneratePersonReport(data);

    return File(file,
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "report.xlsx");
}

این معماری هم تمیزتر است و هم تست‌پذیرتر.

اگر تمایل به یادگیری اصولی و حرفه ای برنامه نویسی دارید دوره جامع برنامه نویسی وب را مشاهده کنید

نتیجه‌گیری

استفاده از پکیج EPPlus در پروژه‌های ‌Web API یک روش استاندارد، سریع و حرفه‌ای برای تولید خروجی اکسل است. این کتابخانه از جدیدترین فرمت‌های اکسل پشتیبانی می‌کند و بدون نیاز به نصب Microsoft Office، امکان ساخت فایل‌های ‎.xlsx‎ را فراهم می‌سازد.

با جداسازی منطق تولید فایل در قالب سرویس و استفاده از قابلیت‌های استایل‌دهی، جدول‌بندی و بهینه‌سازی، می‌توان خروجی‌های دقیق، خوانا و حرفه‌ای تولید کرد.

منابع

۱. مستندات رسمی EPPlus – ‎https://epplussoftware.com/docs‎