ExcelizeCs 0.0.3

excelize-cs

Package excelize-cs is a C# port of Go Excelize library, providing a set of functions that allow you to write and read from XLAM / XLSM / XLSX / XLTM / XLTX files. Supports reading and writing spreadsheet documents generated by Microsoft Excel™ 2007 and later. Supports complex components by high compatibility, and provided streaming API for generating or reading data from a worksheet with huge amounts of data. This library needs .NET version 6, C# version 10 or later. The full API docs can be found at docs reference.

Basic Usage

Installation

dotnet add package ExcelizeCs --version 0.0.3

Create spreadsheet

Here is a minimal example usage that will create spreadsheet file.

using ExcelizeCs;

class Program
{
    static void Main()
    {
        var f = Excelize.NewFile();
        try
        {
            // Create a new sheet.
            var index = f.NewSheet("Sheet2");
            // Set value of a cell.
            f.SetCellValue("Sheet2", "A1", "Hello world.");
            f.SetCellValue("Sheet1", "B2", 100);
            // Set active sheet of the workbook.
            f.SetActiveSheet(index);
            // Save spreadsheet by the given path.
            f.SaveAs("Book1.xlsx");
        }
        catch (RuntimeError err)
        {
            Console.WriteLine(err.Message);
        }
        finally
        {
            var err = f.Close();
            if (!string.IsNullOrEmpty(err))
                Console.WriteLine(err);
        }
    }
}

Reading spreadsheet

The following constitutes the bare to read a spreadsheet document.

using ExcelizeCs;

class Program
{
    static void Main()
    {
        ExcelizeCs.File? f;
        try
        {
            f = Excelize.OpenFile("Book1.xlsx");
        }
        catch (RuntimeError err)
        {
            Console.WriteLine(err.Message);
            return;
        }
        try
        {
            // Get value from cell by given worksheet name and cell reference.
            var cell = f.GetCellValue("Sheet1", "B2");
            Console.WriteLine(cell);
            // Get all the rows in the Sheet1.
            var rows = f.GetRows("Sheet1");
            foreach (var row in rows)
            {
                foreach (var c in row)
                {
                    Console.Write($"{c}\t");
                }
                Console.WriteLine();
            }
        }
        catch (RuntimeError err)
        {
            Console.WriteLine(err.Message);
        }
        finally
        {
            // Close the spreadsheet.
            var err = f.Close();
            if (!string.IsNullOrEmpty(err))
                Console.WriteLine(err);
        }
    }
}

Add chart to spreadsheet file

With Excelize chart generation and management is as easy as a few lines of code. You can build charts based on data in your worksheet or generate charts without any data in your worksheet at all.

using ExcelizeCs;

class Program
{
    static void Main()
    {
        var f = Excelize.NewFile();
        var data = new List<List<object?>>
        {
            new() { null, "Apple", "Orange", "Pear" },
            new() { "Small", 2, 3, 3 },
            new() { "Normal", 5, 2, 4 },
            new() { "Large", 6, 7, 8 },
        };
        var text = "Fruit 3D Clustered Column Chart";
        try
        {
            foreach (var row in data)
            {
                f.SetSheetRow(
                    "Sheet1",
                    Excelize.CoordinatesToCellName(1, data.IndexOf(row) + 1),
                    row
                );
            }
            var chart = new Chart
            {
                Type = ChartType.Col3DClustered,
                Series = new ChartSeries[]
                {
                    new()
                    {
                        Name = "Sheet1!$A$2",
                        Categories = "Sheet1!$B$1:$D$1",
                        Values = "Sheet1!$B$2:$D$2",
                    },
                    new()
                    {
                        Name = "Sheet1!$A$3",
                        Categories = "Sheet1!$B$1:$D$1",
                        Values = "Sheet1!$B$3:$D$3",
                    },
                    new()
                    {
                        Name = "Sheet1!$A$4",
                        Categories = "Sheet1!$B$1:$D$1",
                        Values = "Sheet1!$B$4:$D$4",
                    },
                },
                Title = new RichTextRun[] { new() { Text = text } },
            };
            f.AddChart("Sheet1", "E1", chart);
            // Save spreadsheet by the given path.
            f.SaveAs("Book1.xlsx");
        }
        catch (RuntimeError err)
        {
            Console.WriteLine(err.Message);
        }
        finally
        {
            var err = f.Close();
            if (!string.IsNullOrEmpty(err))
                Console.WriteLine(err);
        }
    }
}

Add picture to spreadsheet file

using ExcelizeCs;

class Program
{
    static void Main()
    {
        ExcelizeCs.File? f;
        try
        {
            f = Excelize.OpenFile("Book1.xlsx");
        }
        catch (RuntimeError err)
        {
            Console.WriteLine(err.Message);
            return;
        }
        try
        {
            // Insert a picture.
            f.AddPicture("Sheet1", "A1", "image.png", null);
            // Insert a picture to worksheet with scaling.
            f.AddPicture(
                "Sheet1",
                "A1",
                "image.jpg",
                new GraphicOptions
                {
                    ScaleX = 0.1,
                    ScaleY = 0.1,
                }
            );
            // Insert a picture offset in the cell with printing support.
            f.AddPicture(
                "Sheet1",
                "A1",
                "image.jpg",
                new GraphicOptions
                {
                    PrintObject = true,
                    LockAspectRatio = false,
                    OffsetX = 15,
                    OffsetY = 10,
                    Locked = false,
                }
            );
            // Save the spreadsheet with the origin path.
            f.Save();
        }
        catch (RuntimeError err)
        {
            Console.WriteLine(err.Message);
        }
        finally
        {
            // Close the spreadsheet.
            var err = f.Close();
            if (!string.IsNullOrEmpty(err))
                Console.WriteLine(err);
        }
    }
}

Contributing

Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature or change.

Licenses

This program is under the terms of the BSD 3-Clause License. See https://opensource.org/licenses/BSD-3-Clause.

The Excel logo is a trademark of Microsoft Corporation. This artwork is an adaptation.

The Go gopher was created by Renee French. Licensed under the Creative Commons 4.0 Attributions license.