SwiftExcel (Free) Free

The free, open-source edition of SwiftExcel. Streams a single-sheet .xlsx document directly to a file or arbitrary Stream, with near-zero memory usage. Source code on GitHub.

Installation

Install via NuGet:

dotnet add package SwiftExcel

Then bring the namespace into scope:

using SwiftExcel;
using SwiftExcel.Extensions; // only if you use ExportToExcel

The library targets netstandard2.0 and depends on SharpCompress for ZIP packaging.

Quick start

The minimal "100 rows × 10 columns" example from the official sandbox:

using (var ew = new ExcelWriter("C:/temp/test.xlsx"))
{
    for (var row = 1; row <= 100; row++)
    {
        for (var col = 1; col <= 10; col++)
        {
            ew.Write($"row:{row}-col:{col}", col, row);
        }
    }
}

Wrapping the writer in using finalizes the document on Dispose(). Calling Save() manually is also supported and equivalent.

Streaming model — what you must know

• Cells must be written in increasing (row, col) order. Writing to a row or column you have already passed throws SwiftExcelException. This is what makes streaming so cheap; it is intentional.
• col and row are 1-based. Passing 0 or a negative value throws.
• Skipping rows or columns is fine — empty <row/> and empty cells are emitted automatically.
• One ExcelWriter per file/stream. Not thread-safe.

API reference

Namespace: SwiftExcel.

ExcelWriter

Implements IDisposable. Two constructor overloads:

Write()

WriteFormula()

Save() and Dispose()

DataType (enum)

FormulaType (enum)

Sheet

Optional configuration object passed to the ExcelWriter constructor.

Configuration (static)

IList<T>.ExportToExcel() — list export extension

For one-shot export of a collection of objects to a sheet, the free edition includes a reflection-based extension method in SwiftExcel.Extensions:

ExcelExportAttribute

Located in SwiftExcel.Attributes:

public class TestModel
{
    [ExcelExport(Order = 1)]
    public int FirstProperty { get; set; }

    [ExcelExport(Name = "Custom SecondProperty Name", Order = 2)]
    public string SecondProperty { get; set; }

    [ExcelExport(Name = "Third", Order = 3, Width = 40.00)]
    public char ThirdProperty { get; set; }

    [ExcelExport(Width = 60.00)]
    public DateTime FourthProperty { get; set; }

    public byte FifthProperty { get; set; }
}

Data & structure — Basic write

The canonical example from the official sandbox:

using (var ew = new ExcelWriter("C:/temp/test.xlsx"))
{
    for (var row = 1; row <= 100; row++)
    {
        for (var col = 1; col <= 100; col++)
        {
            ew.Write($"row:{row}-col:{col}", col, row);
        }
    }
}

Data & structure — Sheet name, widths, RTL, wrap text

Configure the sheet via the optional Sheet parameter and use manual Save():

var sheet = new Sheet
{
    Name = "Monthly Report",
    RightToLeft = true,
    WrapText = true,
    ColumnsWidth = new List<double> { 10, 12, 8, 8, 35 }
};

var ew = new ExcelWriter("C:/temp/test.xlsx", sheet);
for (var row = 1; row <= 100; row++)
{
    for (var col = 1; col <= 10; col++)
    {
        ew.Write($"row:{row}-col:{col}", col, row);
    }
}

ew.Save();

Data & structure — Direct streaming to Azure Blob Storage

The Stream constructor lets you upload a workbook to cloud storage while it is being generated — no temporary file, no full-document buffer. Pattern from the sandbox:

var blobServiceClient = new BlobServiceClient(connectionString);
var containerClient   = blobServiceClient.GetBlobContainerClient(containerName);
var blobClient        = containerClient.GetBlockBlobClient("report.xlsx");

using (var stream = blobClient.OpenWrite(true))
using (var ew = new ExcelWriter(stream))
{
    for (var row = 1; row <= 100; row++)
    {
        for (var col = 1; col <= 100; col++)
        {
            ew.Write($"row:{row}-col:{col}", col, row);
        }
    }
}

The Azure Blob stream is non-seekable, so SwiftExcel automatically disables Zip64 internally. The blob client is responsible for closing its own stream.

Formulas — Built-in Average / Count / Max / Sum

From the sandbox: write 20 numeric values, then four aggregate formulas under them.

using (var ew = new ExcelWriter("C:/temp/test.xlsx"))
{
    const int col = 1;
    var row = 1;
    for (; row <= 20; row++)
    {
        ew.Write(row.ToString(), col, row, DataType.Number);
    }

    ew.WriteFormula(FormulaType.Average, col, ++row, col, 1, 20);
    ew.WriteFormula(FormulaType.Count,   col, ++row, col, 1, 20);
    ew.WriteFormula(FormulaType.Max,     col, ++row, col, 1, 20);
    ew.WriteFormula(FormulaType.Sum,     col, ++row, col, 1, 20);
}

Data types — Numbers

Pass DataType.Number so Excel parses the value as numeric instead of text:

ew.Write("42",        1, 1, DataType.Number);
ew.Write("3.14159",   2, 1, DataType.Number);
ew.Write("-12.5",    3, 1, DataType.Number);

Numeric values are written using the invariant culture internally, so 3.14 stays 3.14 regardless of the user's thread culture (no surprise commas).

Data types — Dates with .ToOADate() (critical pattern)

Excel does not have a native date type — internally a date is just a double (an OLE Automation date). To write a real date value you must convert it with DateTime.ToOADate() and write it as DataType.Number:

var dateToExport = new DateTime(2023, 8, 21, 10, 51, 18);

using (var ew = new ExcelWriter("C:/temp/test.xlsx"))
{
    ew.Write($"{dateToExport.ToOADate()}", 1, 1, DataType.Number);
}

Why this matters: if you write the date as a string (DataType.Text) Excel will not let users sort, filter, or compute on it. With ToOADate() + DataType.Number the cell is genuinely a date — but in the Free edition it will display as a raw double until a user formats the column as a date in Excel.

For automatic date formatting use SwiftExcel.Pro with NumberFormat.Custom("dd/mmm/yyyy hh:mm:ss").

Hyperlinks Pro

The free edition does not support hyperlinks. To write a clickable link, install SwiftExcel.Pro and use the HYPERLINK Excel function via DataType.CustomFormula. See SwiftExcel.Pro · Hyperlinks.

A workaround in Free is to write the URL as plain text — Excel will auto-link it on cell-edit but it is not a real hyperlink.

Special values — Invalid XML & reserved characters

SwiftExcel automatically escapes < > & ' " and, when Configuration.UseEnchancedXmlEscaping is true (default), encodes XML-invalid control characters using Excel's _xHHHH_ syntax. You can pass any user input safely:

Configuration.UseEnchancedXmlEscaping = true;
using (var ew = new ExcelWriter("C:/temp/test.xlsx"))
{
    ew.Write("<",  1, 1);
    ew.Write(">",  2, 1);
    ew.Write("&",  3, 1);
    ew.Write("'",  4, 1);
    ew.Write("\"", 5, 1);
}

Bulk export — IList<T>.ExportToExcel()

One-line export of a collection. Headers are derived from property names or [ExcelExport] attributes.

var testCollection = new List<TestModel>
{
    new TestModel(),
    new TestModel()
};

// default sheet name "Sheet1"
testCollection.ExportToExcel("C:/temp/test.xlsx");

// or with a custom sheet name
testCollection.ExportToExcel("C:/temp/test.xlsx", sheetName: "Sheet2");

Property order in the workbook follows the [ExcelExport(Order = N)] attribute (ascending). Properties without an explicit order go last in the order returned by reflection.

FAQ