Edit this page
Available for: UI for ASP.NET AJAX | UI for ASP.NET MVC | UI for WPF | UI for WinForms | UI for Xamarin

Workbook

This article will help you get familiar with the concept of a workbook and its features.

What is a Workbook?

The workbook is the primary document that you use to manipulate and store data. The workbook can also be described as a collection of worksheets, where a worksheet is in turn defined as a collection of cells organized in rows and columns. Each workbook contains, at least, one worksheet and often holds several sheets with related information.

The workbook is designed to hold together multiple worksheets in order to allow efficient organization and consolidation of data. Typically, a workbook contains worksheets with related data.

IWorkbookExporter Interface

In RadSpreadStreamProcessing, the workbook is represented by the IWorkbookExporter interface. This interface defines members for adding worksheets and accessing the cell styles of the workbook.

IWorkbookExporter is responsible for exporting a workbook. Due to the specifics of the different file formats, different concrete instances of this interface take care about the creation and export of a document.

Using IWorkbookExporter

You can obtain an instance of IWorkbookExporter through the CreateWorkbookExporter() method of SpreadExporter. The first parameter of the CreateWorkbookExporter() method specifies the file format that will be used to save the document and the second one represents the stream in which the document will be saved.

The code from Example 1 creates an empty workbook and exports it to an XLSX file.

[C#] Example 1: Create IWorkbookExporter

using (FileStream stream = File.OpenWrite("sample.xlsx"))
{
    using (IWorkbookExporter workbook = SpreadExporter.CreateWorkbookExporter(SpreadDocumentFormat.Xlsx, stream))
    {
        using (IWorksheetExporter worksheet = workbook.CreateWorksheetExporter("First sheet"))
        {
            using (IRowExporter row = worksheet.CreateRowExporter())
            {
            }
        }
    }
}

Append Content to an Existing Document

The CreateWorkbookExporter method creates a new workbook which overrides the content of the document contained in the stream if it's not empty. You can change that by using the second overload of the CreateWorkbookExporter method and pass the export mode explicitly. You can do that via the last parameter of the method (exportMode) which is of type SpreadExportMode. SpreadExportMode is an enum that exposes two constants - Create and Append. The default export mode is Create, which overrides the stream's content. If you set the export mode to Append, an existing workbook from the stream will be opened if there is any content in it. Then you can append the new content to the already existing document.

[C#] Example 2: Create IWorkbookExporter and append the content from the stream

IWorkbookExporter workbook = SpreadExporter.CreateWorkbookExporter(SpreadDocumentFormat.Xlsx, stream, SpreadExportMode.Append);

The Šppend mode is not supported in Xamarin.

IWorkbookExporter inherits from IDisposable. Make sure the object is disposed when you are done with it. Otherwise, the content won't be written in the exported file. The best way to ensure this is handled properly is to wrap it in a using statement.

In the spreadsheet documents, the names of the sheets are unique. If you try to add a sheet with a name that is already present in the workbook, you will get an ArgumentException. This is where the GetSheetInfos() method comes in handy. The method returns information about the sheets currently present in the workbook (imported or added). It could be used to check whether a particular sheet name is available (not already present) when appending a worksheet to an existing workbook. Example 3 demonstrates how you can use it.

[C#] Example 3: Using IWorkbookExporter.GetSheetInfos()

using (IWorkbookExporter workbookExporter = SpreadExporter.CreateWorkbookExporter(SpreadDocumentFormat.Xlsx, stream))
{
    IEnumerable<SheetInfo> sheetInfos = workbookExporter.GetSheetInfos();
    string firstNameSheet = sheetInfos.First().Name;
}

Since the CSV format doesn't have the concept for multiple sheets, invoking GetSheetInfos() for a CSV document returns an empty collection.

You can find a runnable example showing how to append a worksheet to an existing workbook in the SDK repository on GitHub.

See Also