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 and IWorkbookImporter Interfaces
In RadSpreadStreamProcessing, the workbook is represented by the IWorkbookExporter and IWorkbookImporter interface interfaces. These interfaces define members for adding worksheets, parsing them, 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. The same applies when importing with IWorkbookImporter.
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.
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.
Example 2: Create IWorkbookExporter and append the content from the stream
IWorkbookExporter workbook = SpreadExporter.CreateWorkbookExporter(SpreadDocumentFormat.Xlsx, stream, SpreadExportMode.Append);
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.
Example 3: Using IWorkbookExporter.GetSheetInfos()
using (IWorkbookExporter workbookExporter = SpreadExporter.CreateWorkbookExporter(SpreadDocumentFormat.Xlsx, stream))
{
IEnumerable<SheetInfo> sheetInfos = workbookExporter.GetSheetInfos();
string firstNameSheet = sheetInfos.First().Name;
}
You can find a runnable example showing how to append a worksheet to an existing workbook in the SDK repository on GitHub.
Using IWorkbookImporter to Read a File
The IWorkbookImporter interface is the entry point for reading a document and allows you iterate the worksheet importers. You can get an instance of IWorkbookImporter through the CreateWorkbookImporter() method of SpreadExporter. The first parameter of the CreateWorkbookImporter() method specifies the file format of the document that will be imported and the second one represents the stream with the file data. For more information on how to read the data, check the Import help topic.