یک فید با کد ساده زیر به طور کامل خوانده می‌شود:

jQuery.getFeed({
   url: 'rss.xml',
   success: function(feed) {
      alert(feed.title);
   }
});

عناصر داخلی تابع

در داخل هر تابع دو شیء خاص به نامهای arguments و this وجود دارند. شیء arguments ، که قبلا در مورد آن صحبت کردیم، دارای یک ویژگی به نام callee می‌باشد که به تابعی اشاره می‌کند که arguments متعلق به آن است. به مثال زیر توجه کنید که تابع فاکتوریل را به صورت بازگشتی پیاده سازی نموده است:

function factorial(num) {
    if (num <= 1)
        return 1;
    else
        return num * factorial(num - 1);
}

function factorial(num) {
    if (num <= 1)
        return 1;
    else
        return num * arguments.callee(num - 1);
}

function factorial(num) {
    if (num <= 1)
        return 1;
    else
        return num * arguments.callee(num - 1);
}

var anotherFactorial = factorial;

factorial = function() {
    return 0;
}

alert(anotherFactorial(5));
alert(factorial(5));

خروجی :

     120

     0

در مثال فوق، ابتدا تابع factorial تعریف شده و سپس به متغیر anotherFactorial نسبت داده شده‌است. سپس تابع factorial با تعریف جدیدی جایگزین شده که مقدار 0 بر می‌گرداند. همانطور که مشاهده می‌کنید، تابع بازگشتی از طریق arguments.callee فراخوانی گردیده است. اما اگر به جای arguments.callee از نام تابع، یعنی factorial استفاده کرده بودیم، خروجی در هر دو مرحله 0 می‌بود. زیرا anotherFactorial نیز، در داخل خود، تابع factorial جایگزین شده با خروجی 0 را فراخوانی می‌نمود.

شیء دیگری که در توابع وجود دارد، شی this می‌باشد. این شیء به شیء ای اشاره می‌کند که تابع، متعلق به آن است یا برای آن فعالیت می‌کند. اگر تابعی به صورت عمومی تعریف شود، متعلق به شیء window می‌باشد. بنابراین this در این توابع به شیء window اشاره می‌کند. به مثال زیر توجه کنید:

window.color = "red";

var o = { color: "blue" };
o.showColor = sayColor;

function sayColor() {
    alert(this.color);
}

sayColor();
o.showColor();

خروجی :

     "red"

     "blue"

ابتدا ویژگی color را برای شیء window تعریف کردیم. سپس شیء ای به نام o ایجاد نمودیم که دارای ویژگی color می‌باشد. همچنین تابعی به نام showColor را برای آن تعریف نمودیم که تابع sayColor به آن نسبت داده شده است. در تابع sayColor نیز مقدار ویژگی color را به صورت پیغامی نمایش می‌دهیم. زمانی که این تابع را فراخوانی می‌نماییم، شیء this موجود در آن به شیء window اشاره می‌کند؛ بنابراین مقدار "red" را نمایش می‌دهد. سپس تابع showColor از شیء o را فراخوانی نمودیم که شیء this در آن به شیء o اشاره می‌کند. زیرا تابع showColor که به تابع sayColor اشاره می‌کند، متعلق به شیء o می‌باشد.

ویژگی‌ها و توابع اشیاء ایجاد شده از Function

ویژگی caller

یکی از ویژگی‌های توابع که می‌تواند مورد استفاده قرار بگیرد، ویژگی caller می‌باشد. این ویژگی مشخص می‌کند که چه تابعی، تابع جاری را فراخوانی نموده است. اگر فراخوانی تابع جاری در حوزه‌ی عمومی (Global Scope) صورت گرفته باشد، این ویژگی مقدار null بر می‌گرداند؛ در غیر اینصورت محتوای تابع فراخواننده برگردانده خواهد شد.

function outer() {
    inner();
}

function inner() {
    alert(inner.caller);
}

inner();
outer();

خروجی :

    null

     function outer() {
        inner();
      }

ویژگی length

ویژگی دیگری که برای توابع مورد استفاده قرار می‌گیرد، ویژگی length می‌باشد. این ویژگی تعداد Named Arguments (پارامترهای نامی) تابع را بر می‌گرداند.

function sayName(name) {
    alert(name);
}

function sum(num1,num2) {
    return num1 + num2;
}

function sayHi() {
    alert("Hi");
}

alert(sayName.length);
alert(sum.length);
alert(sayHi.length);

خروجی :

     1

     2

     0

همانطور که در خروجی نیز مشاهده می‌کنید، تعداد آرگومانهای هر یک از توابع تعریف شده نمایش یافته است. به عنوان مثال تابع sayName دارای یک آرگومان ورودی است و خروجی نیز عدد 1 را نمایش داده است.

توابع apply() و call()

این دو تابع، جهت فراخوانی توابع، با یک مقدار خاص برای شیء this استفاده می‌شوند؛ در واقع مقدار شیء this را در بدنه‌ی توابع تنظیم می‌کنند. همانطور که قبلا اشاره شد، شیء this ، به شیء ای اشاره میکند که تابع متعلق به آن است. با توابع فوق می‌توانیم اشاره‌گر this را با مقدار یا شیء دیگری تنظیم کنیم. آرگومان اول هر دوی این توابع، مقداری است که باید به شیء this اختصاص یابد. آرگومان بعدی تابع apply آرایه‌ای است که آرگومان‌های ورودی را برای تابع فراخوانی شده فراهم می‌کند. آرگومانهای بعدی تابع call ، همان آرگومان هایی هستند که به صورت مجزا به تابع فراخوانی شده ارسال می‌گردند.

var color = "red";

var obj = { color: "blue" };

function sayColor(a, b) {
    alert(a + " said " + b + ": " + this.color);
}

sayColor("Sohrab", "Mitra");
sayColor.apply(this, ["Sohrab", "Mitra"]);
sayColor.call(this, "Sohrab", "Mitra");

sayColor.apply(obj, ["Sohrab", "Mitra"]);
sayColor.call(obj, "Sohrab", "Mitra");

خروجی :

     "Sohrab told Mitra: red"

     "Sohrab told Mitra: red"

     "Sohrab told Mitra: red"

     "Sohrab told Mitra: blue"

     "Sohrab told Mitra: blue"

همانطور که می‌دانید یک تابع به صورت پیش فرض متعلق به شیء window می‌باشد. در سه فراخوانی اول، تابع sayColor ، شیء this ، به شیء window اشاره می‌کند. بنابراین مقدار red را برای متغیر یا ویژگی color نمایش میدهد. دو فراخوانی آخر که obj را به عنوان آرگومان اول ارسال می‌نمایند، یعنی شیء this باید با مقدار obj جایگزین شود. بنابراین مقدار blue را برای ویژگی color ، که متعلق به شی obj می‌باشد، نمایش می‌دهند.

تنها تفاوت call() و apply() ، شیوه‌ی ارسال آرگومانها به تابع مقصد می‌باشد. مزیت استفاده از توابع call() یا apply() این است که می‌توان یک شیء را به یک تابع تزریق نمود به گونه‌ای که شیء، هیچ اطلاعی از تابع مورد نظر نداشته باشد. این مزیت مورد استفاده‌ی برخی الگوها و معماری‌ها می‌باشد که در مباحث مربوطه در مورد آن بحث خواهد شد.

تابع bind()

این تابع نمونه‌ای از یک تابع را ایجاد می‌کند و شیء this آن تابع را، با آرگومان ارسالی به تابع bind ، مقداردهی می‌نماید.

var color = "red";

var obj = { color: "blue" };

function sayColor() {
    alert(this.color);
}

var bindSayColor = sayColor.bind(obj);
bindSayColor();

خروجی :

     "blue"

در مثال فوق، نمونه‌ای از تابع sayColor ایجاد شده است که شیء obj به عنوان آرگومان ورودی تابع bind ارسال شده است. یعنی مقدار this در تابع bindSayColor به شیء obj اشاره میکند و مقدار ویژگی color شیء obj به عنوان خروجی نمایش می‌یابد. 

امکان خروجی اکسل از گزارشات سیستم، یکی از بایدهای بیشتر سیستم‌های اطلاعاتی می‌باشد؛ یکی از چالش‌های اصلی در تولید این نوع خروجی، افزایش مصرف حافظه متناسب با افزایش حجم دیتا می‌باشد. از آنجایی‌که بیشتر راهکارهای موجود از جمله ClosedXml یا Epplus کل ساختار را ابتدا تولید کرده و اصطلاحا خروجی مورد نظر را بافر می‌کنند، برای حجم بالای اطلاعات مناسب نخواهند بود. راهکار برای خروجی CSV به عنوان مثال خیلی سرراست می‌باشد و می‌توان با چند خط کد، به نتیجه دلخواه از طریق مکانیزم Streaming رسید؛ ولی ساختار Excel به سادگی فرمت CSV نیست و برای مثال فرمت Excel Workbook با پسوند xlsx یک بسته Zip شده‌ای از فایل‌های XML می‌باشد.

معرفی MiniExcel

MiniExcel یک کتابخانه سورس باز با هدف به حداقل رساندن مصرف حافظه در زمان پردازش فایل‌های Excel در دات نت می‌باشد. در مقایسه با Aspose از منظر امکانات شاید حرفی برای گفتن نداشته باشد، ولی از جهت خواندن اطلاعات فایل‌های Excel با قابلیت پشتیبانی از ‌LINQ و Deferred Execution در کنار مصرف کم حافظه و جلوگیری از مشکل OOM خیلی خوب عمل می‌کند. در تصویر زیر مشخص است که برای عمده عملیات پیاده‌سازی شده، از استریم‌ها بهره برده شده است.

همچنین در زیر مقایسه‌ای روی خروجی ۱ میلیون رکورد با تعداد ۱۰ ستون در هر ردیف انجام شده‌است که قابل توجه می‌باشد:

Logic : create a total of 10,000,000 "HelloWorld" excel

به شدت API خوش دستی برای استفاده دارد و شاید مطالعه سورس کد آن از جهت طراحی نیز درس آموزی داشته باشد. در ادامه چند مثال از مستندات آن را می‌توانید ملاحظه کنید:

var path = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid()}.xlsx");
MiniExcel.SaveAs(path, new[] {
    new { Column1 = "MiniExcel", Column2 = 1 },
    new { Column1 = "Github", Column2 = 2}
});

// DataReader export multiple sheets (recommand by Dapper ExecuteReader)

using (var cnn = Connection)
{
    cnn.Open();
    var sheets = new Dictionary<string,object>();
    sheets.Add("sheet1", cnn.ExecuteReader("select 1 id"));
    sheets.Add("sheet2", cnn.ExecuteReader("select 2 id"));
    MiniExcel.SaveAs("Demo.xlsx", sheets);
}

طراحی یک ActionResult سفارشی برای استفاده از MiniExcel

برای این منظور نیاز است تا Stream مربوط به Response درخواست جاری را در اختیار این کتابخانه قرار دهیم و از سمت دیگر دیتای مورد نیاز را به نحوی که بافر نشود و از طریق مکانیزم Streaming در EF (استفاده از Deferred Execution و Enumerableها) مهیا کنیم. برای امکان تعویض پذیری (این سناریو در پروژه واقعی و باتوجه به جهت وابستگی‌ها می‌تواند ضروری باشد) از دو واسط زیر استفاده خواهیم کرد:

public interface IExcelDocumentFactory
{
    ILargeExcelDocument CreateLargeDocument(IEnumerable<ExcelColumn> headers, Stream stream);
}


public interface ILargeExcelDocument : IAsyncDisposable, IDisposable
{
    Task Write<T>(
        PaginatedEnumerable<T> items,
        int count,
        int sizeLimit,
        CancellationToken cancellationToken = default) where T : notnull;
}

متد CreateLargeDocument یک وهله از ILargeExcelDocument را در اختیار مصرف کننده قرار می‌دهد که قابلیت نوشتن روی آن از طریق متد Write را خواهد داشت. روش واکشی دیتا از طریق Delegate تعریف شده با نام PaginatedEnumerable به مصرف کننده محول شده‌است که در ادامه امضای آن را می‌توانید مشاهده کنید:

public delegate IEnumerable<T> PaginatedEnumerable<out T>(int page, int pageSize);

در ادامه پیاده‌سازی واسط ILargeExcelDocument برای MiniExcel به شکل زیر خواهد بود:

internal sealed class MiniExcelDocument(Stream stream, IEnumerable<ExcelColumn> columns) : ILargeExcelDocument
{
    private const int SheetLimit = 1_048_576;
    private bool _disposedValue;

    public async Task Write<T>(
        PaginatedEnumerable<T> items,
        int count,
        int sizeLimit,
        CancellationToken cancellationToken = default)
        where T : notnull
    {
        ThrowIfDisposed();
        
        // TODO: apply sizeLimit
        var properties = FastReflection.Instance.GetProperties(typeof(T))
            .ToDictionary(p => p.Name, StringComparer.OrdinalIgnoreCase);

        var sheets = new Dictionary<string, object>();
        var index = 1;
        while (count > 0)
        {
            cancellationToken.ThrowIfCancellationRequested();

            IEnumerable<Dictionary<string, object>> reader = items(index, SheetLimit)
                .Select(item =>
                {
                    cancellationToken.ThrowIfCancellationRequested();
                    return columns.ToDictionary(h => h.Title, h => ValueOf(item, h.Name, properties));
                });

            sheets.Add($"sheet_{index}", reader);
            count -= SheetLimit;
            index++;
        }

        // This part is forward-only, and we are pretty sure that streaming will happen without buffering.
        await stream.SaveAsAsync(sheets, cancellationToken: cancellationToken);
    }

    private void Dispose(bool disposing)
    {
        if (!_disposedValue)
        {
            if (disposing)
            {
                // TODO: dispose managed state (managed objects)
            }

            // TODO: free unmanaged resources (unmanaged objects) and override finalizer
            // TODO: set large fields to null
            _disposedValue = true;
        }
    }

    ~MiniExcelDocument()
    {
        Dispose(disposing: false);
    }

    public void Dispose()
    {
        // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
    }

    public async ValueTask DisposeAsync()
    {
        Dispose();
        await ValueTask.CompletedTask;
    }

    private void ThrowIfDisposed()
    {
        if (!_disposedValue) return;
        
        throw new ObjectDisposedException(nameof(MiniExcelDocument));
    }
    private static object ValueOf<T>(T record, string prop, IDictionary<string, FastPropertyInfo> properties)
        where T : notnull
    {
        var property = properties[prop] ??
                       throw new InvalidOperationException($"There is no property with given name [{prop}]");

        return NormalizeValue(property.GetValue?.Invoke(record));
    }

    private static object NormalizeValue(object? value)
    {
        if (value == null) return null!;

        return value switch
        {
            DateTime dateTime => dateTime.ToShortPersianDateTimeString(),
            TimeSpan time => time.ToString(@"hh\:mm\:ss"),
            DateOnly dateTime => dateTime.ToShortPersianDateString(false),
            TimeOnly time => time.ToString(@"hh\:mm\:ss"),
            bool boolean => boolean ? "بلی" : "خیر",
            IEnumerable<object> values => string.Join(',', values.Select(NormalizeValue).ToList()),
            Enum enumField => enumField.GetEnumStringValue(),
            _ => value
        };
    }
}

در بدنه متد Write باتوجه به تعداد کل رکوردها، یک کوئری برای هر شیت از طریق فراخوانی متد منتسب به پارامتر items اجرا خواهد شد؛ توجه کنید که اجرای این کوئری مشخصا به تعویق افتاده و تا زمان اولین MoveNext، اجرایی صورت نخواهد گرفت (مفهوم Deferred Execution). به این ترتیب باقی کارها از جمله فرمت کردن مقادیر در سمت برنامه و از طریق Linq To Object انجام خواهد شد. همچنین پیاده‌سازی Factory مرتبط با آن به شکل زیر خواهد بود:

internal sealed class ExcelDocumentFactory : IExcelDocumentFactory
{
    public ILargeExcelDocument CreateLargeDocument(IEnumerable<ExcelColumn> columns, Stream stream)
    {
        return new MiniExcelDocument(stream, columns);
    }
}

در ادامه ActionResult سفارشی برای گرفتن خروجی اکسل را به شکل زیر می توان پیاده‌سازی کرد:

public class ExcelExportResult<T>(PaginatedEnumerable<T> items, int count, ExportMetadata metadata) : ActionResult
    where T : notnull
{
    private const string ContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
    private const string Extension = ".xlsx";
    private const int SizeLimit = int.MaxValue;

    private readonly IReadOnlyList<FastPropertyInfo> _properties = FastReflection.Instance.GetProperties(typeof(T));

    public override async Task ExecuteResultAsync(ActionContext context)
    {
        var sp = context.HttpContext.RequestServices;
        var factory = sp.GetRequiredService<IExcelDocumentFactory>();

        var disposition = new ContentDispositionHeaderValue(DispositionTypeNames.Attachment);
        disposition.SetHttpFileName(MakeFilename());

        context.HttpContext.Response.Headers[HeaderNames.ContentDisposition] = disposition.ToString();
        context.HttpContext.Response.Headers.Append(HeaderNames.ContentType, ContentType);
        context.HttpContext.Response.StatusCode = StatusCodes.Status200OK;

        //TODO: deal with exception, because our global exception handling cannot take into account while the response is started.

        await using var bodyStream = context.HttpContext.Response.BodyWriter.AsStream();
        await context.HttpContext.Response.StartAsync(context.HttpContext.RequestAborted);
        await using (var document = factory.CreateLargeDocument(MakeColumns(), bodyStream))
        {
            await document.Write(items, count, SizeLimit, context.HttpContext.RequestAborted);
        }

        await context.HttpContext.Response.CompleteAsync();
    }

    private string MakeFilename()
    {
        return
            $"{metadata.Title} - {DateTime.UtcNow.ToEpochSeconds()}{Extension}";
    }

    private IEnumerable<ExcelColumn> MakeColumns()
    {
        var types = _properties.ToDictionary(p => p.Name, p => p.PropertyType, StringComparer.OrdinalIgnoreCase);
        return metadata.Fields.Select(f =>
        {
            var type = types[f.Name];

            type = Nullable.GetUnderlyingType(type) ?? type;

            if (type.IsEnum ||
                type == typeof(DateOnly) ||
                type == typeof(TimeOnly) ||
                type == typeof(bool) ||
                type == typeof(TimeSpan) ||
                type == typeof(DateTime))
            {
                type = typeof(string);
            }

            return new ExcelColumn(f.Name, f.Title, type);
        });
    }
}

در اینجا از طریق ExportMetadata که از سمت کاربر تعیین می‌شود، مشخص خواهد شد که کدام فیلدها در فایل نهایی حضور داشته باشند. در بدنه متد ExecuteResultAsync یکسری هدر مرتبط با کار با فایل‌ها تنظیم شده‌است و سپس از طریق BodyWriter و متد AsStream به استریم مورد نظر دست یافته و در اختیار متد Write مربوط به document ایجاد شده، قرار داده‌ایم. یک نمونه استفاده از آن برای موجودیت فرضی مشتری می تواند به شکل زیر باشد:

[ApiController, Route("api/customers")]
public class CustomersController(IDbContext dbContext) : ControllerBase
{
    [HttpGet("export")]
    public async Task<ActionResult> ExportCustomers([FromQuery] ExportMetadata metadata,
        CancellationToken cancellationToken)
    {
        var count = await dbContext.Set<Customer>().CountAsync(cancellationToken);
        return this.Export(
            (page, pageSize) => dbContext.Set<Customer>()
                .OrderBy(c => c.Id)
                .Skip((page - 1) * pageSize)
                .Take(pageSize)
                .AsNoTracking()
                .AsEnumerable(), // Enable streaming instead of buffering through deferred execution
            count,
            metadata);
    }
}

در اینجا از طریق Extension Method مهیا شده روش کوئری کردن برای هر شیت را مشخص کرده‌ایم؛ نکته مهم در ایجاد استفاده از ‌متد AsEnumerable می باشد که در عمل یک Type Casting انجام می دهد که باقی متدهای استفاده شده روی خروجی، از طریق Linq To Object اعمال شود و همچنین نیاز به استفاده از ToList و یا موارد مشابه را نخواهیم داشت. نمونه درخواست GET برای این API می تواند به شکل زیر باشد:

http://localhost:5118/api/customers/export?Title=Test&Fields[0].Name=FirstName&Fields[0].Title=First name&Fields[1].Name=LastName&Fields[1].Title=Last name&Fields[2].Name=BirthDate&Fields[2].Title=BirthDate

سورس کد مثال قابل اجرا از طریق مخزن زیر قابل دسترس می باشد:

https://github.com/rabbal/large-excel-streaming

در این مثال در زمان آغاز برنامه، ۱۰ میلیون رکورد در جدول Customer ثبت خواهد شد که در ادامه می توان از آن خروجی Excel تهیه کرد.

نکته مهم: توجه داشته باشید که استفاده از این روش قابلیت از سرگیری مجدد برای دانلود را نخواهد داشت و شاید بهتر است این فرآیند را از طریق یک Job انجام داده و با استفاده از قابلیت‌های Multipart Upload مربوط به یک BlobStroage مانند Minio، خروجی مورد نظر از قبل ذخیره کرده و لینک دانلودی را در اختیار کاربر قرار دهید.