Class Workbook

Represents a Microsoft Excel workbook.

Inheritance

System.Object

Workbook

Namespace: Infragistics.Documents.Excel

Assembly: IgniteUI.Blazor.Documents.Excel.dll

Syntax

public class Workbook : Object

Remarks

Every workbook consists of one or more worksheets (Worksheet). The default constructor creates an empty workbook.

Constructors

Workbook()

Creates a new instance of the Workbook class.

Declaration

public Workbook()

Remarks

The new workbook created is empty. At least one Worksheet must be added to it before it can be saved.

Workbook(WorkbookFormat)

Creates a new instance of the Workbook class.

Declaration

public Workbook(WorkbookFormat format)

Parameters

Type	Name	Description
WorkbookFormat	format	The file format to use when imposing format restrictions and saving.

Remarks

The new workbook created is empty. At least one Worksheet must be added to it before it can be saved.

Exceptions

Type	Condition
System.ComponentModel.InvalidEnumArgumentException	`format` is not defined in the WorkbookFormat enumeration.

Fields

MaxExcel2007CellFormatCount

Maximum number of distinct cell formats in the workbook allowed by the Excel 2007 file format.

Declaration

public const int MaxExcel2007CellFormatCount = 64000

Field Value

Type	Description
System.Int32

MaxExcel2007ColumnCount

Maximum number of columns in the worksheet allowed by the Excel 2007 file format.

Declaration

public const int MaxExcel2007ColumnCount = 16384

Field Value

Type	Description
System.Int32

MaxExcel2007RowCount

Maximum number of rows in the worksheet allowed by the Excel 2007 file format.

Declaration

public const int MaxExcel2007RowCount = 1048576

Field Value

Type	Description
System.Int32

MaxExcelCellFormatCount

Maximum number of distinct cell formats in the workbook allowed by the Excel 97-2003 file format.

Declaration

public const int MaxExcelCellFormatCount = 4000

Field Value

Type	Description
System.Int32

MaxExcelColumnCount

Maximum number of columns in the worksheet allowed by the Excel 97-2003 file format.

Declaration

public const int MaxExcelColumnCount = 256

Field Value

Type	Description
System.Int32

MaxExcelRowCount

Maximum number of rows in the worksheet allowed by the Excel 97-2003 file format.

Declaration

public const int MaxExcelRowCount = 65536

Field Value

Type	Description
System.Int32

MaxExcelWorkbookFonts

Maximum number fonts in a workbook allowed by Excel.

Declaration

public const int MaxExcelWorkbookFonts = 512

Field Value

Type	Description
System.Int32

Properties

CalculationMode

Gets or sets the value which indicates how a formula will be recalculated when a referenced value changes.

Declaration

public CalculationMode CalculationMode { get; set; }

Property Value

Type	Description
CalculationMode	The value which indicates how a formula will be recalculated when a referenced value changes.

Remarks

If this is set to a value of Manual, the RecalculateBeforeSave property will determine if formulas are recalculated just before saving the file. Otherwise, that property is ignored.

Exceptions

Type	Condition
System.ComponentModel.InvalidEnumArgumentException	The assigned value is not defined in the CalculationMode enumeration.

CellReferenceMode

Gets or sets the value which indicates the way cells in the workbook are referenced.

Declaration

public CellReferenceMode CellReferenceMode { get; set; }

Property Value

Type	Description
CellReferenceMode	The value which indicates the way cells in the workbook are referenced.

Remarks

The value of this property will affect the row and columns labels of the workbook when opened in Microsoft Excel. In addition, it will affect the display of formulas referencing different cells.

Exceptions

Type	Condition
System.ComponentModel.InvalidEnumArgumentException	The assigned value is not defined in the CellReferenceMode enumeration.

Culture

Gets or sets the culture to use as the current culture for the workbook when doing any culture-aware conversions or comparisons.

Declaration

public CultureInfo Culture { get; set; }

Property Value

Type	Description
System.Globalization.CultureInfo	The current culture for the workbook or Null to use the thread's current culture.

Remarks

Note: The culture is not saved or loaded in workbook files, so this is only used at when accessing and manipulating objects owned or associated with the Workbook.

CurrentFormat

Gets the current format of the workbook. This is the format which will be used when saving and imposing format restrictions.

Declaration

public WorkbookFormat CurrentFormat { get; }

Property Value

Type	Description
WorkbookFormat

CustomTableStyles

Gets the collection of custom table styles in the workbook.

Declaration

public CustomTableStyleCollection CustomTableStyles { get; }

Property Value

Type	Description
CustomTableStyleCollection

CustomViews

Gets the collection of custom views for the workbook.

Declaration

public CustomViewCollection CustomViews { get; }

Property Value

Type	Description
CustomViewCollection	The collection of custom views for the workbook.

Remarks

Each custom view stores display settings and optionally print settings, which can later be applied to the workbook and its worksheets as one operation, through both the Microsoft Excel UI and the Excel assembly by calling the Apply() method.

DateSystem

Gets or sets the date system used internally by Microsoft Excel.

Declaration

public DateSystem DateSystem { get; set; }

Property Value

Type	Description
DateSystem	The date system used internally by Microsoft Excel.

Exceptions

Type	Condition
System.ComponentModel.InvalidEnumArgumentException	The assigned value is not defined in the DateSystem enumeration.

DefaultTableStyle

Gets or sets the default style for tables in the workbook.

Declaration

public WorksheetTableStyle DefaultTableStyle { get; set; }

Property Value

Type	Description
WorksheetTableStyle

Remarks

This can be set to any WorksheetTableStyle in the CustomTableStyles or StandardTableStyles collection.

This will never return a null value. If it is set to null, it will be reset to the TableStyleMedium2 table style.

If this value is changed, it will not be applied to existing tables in the workbook. Only newly created tables will use default table style on the workbook.

Exceptions

Type	Condition
System.ArgumentException	The specified value is not in the CustomTableStyles or StandardTableStyles collections.

DocumentProperties

Gets the properties associated with the workbook document.

Declaration

public DocumentProperties DocumentProperties { get; }

Property Value

Type	Description
DocumentProperties	The properties associated with the workbook document.

Remarks

The document properties are pieces of information which provide details on the content of the workbook, such as the author, title, and subject of the workbook.

EditingCulture

The editing culture affects certain language specific features such as formatting of dates. or comparisons.

Declaration

public CultureInfo EditingCulture { get; set; }

Property Value

Type	Description
System.Globalization.CultureInfo

Remarks

Note: The EditingCulture is not saved or loaded in workbook files, so this is only used at when accessing and manipulating objects owned or associated with the Workbook.

FileWriteProtectedBy

Gets the name of the user who initially added file write protection to the document.

Declaration

public string FileWriteProtectedBy { get; }

Property Value

Type	Description
System.String

Remarks

This value is valid if HasFileWriteProtectionPassword or IsFileWriteProtected is true. It will be updated when SetFileWriteProtectionPassword is called and a user name is specified with a new password.

Note: The Workbook and its related sub-objects do not prevent modifications at runtime when a file is write protected, as Microsoft Excel allows UI modifications to write protected files which are not unlocked with the proper password. In addition, write protected Workbook instances do not prevent saves to the file location from which they were loaded, as it is possible to overwrite files in this situation in Microsoft Excel via the 'Save As' dialog. It is the responsibility of the Workbook's consumer to prevent automatic file overwrites when IsFileWriteProtected is true.

HasFileWriteProtectionPassword

Gets the value indicating whether the Workbook has a file write protection password that will be used to protect saved files or streams.

Declaration

public bool HasFileWriteProtectionPassword { get; }

Property Value

Type	Description
System.Boolean

Remarks

Workbook instances loaded from files or streams with a write protection password will initially have IsFileWriteProtected set to true. It is recommended that consumers of these instances prevent (or at least warn) users from automatically overwriting the files or streams from which the instances were loaded. These instances will initially not have their HasFileWriteProtectionPassword set to true. Although it is possible to validate a file write protection password when provided via ValidateFileWriteProtectionPassword, it is not possible to obtain the original password from the loaded file or stream. So file write protected Workbook instances which are loaded, but which never have the proper file write protection password validated will be saved without file write protection. Only when the password is validated via ValidateFileWriteProtectionPassword or overwritten via v will HasFileWriteProtectionPassword return true, indicating that file write protection will be added to subsequently saved files or streams.

The file write protection password can be cleared or reset by using SetOpenPassword.

HasOpenPassword

Gets the value indicating whether the Workbook has an open password and will therefore be encrypted on subsequent saves.

Declaration

public bool HasOpenPassword { get; }

Property Value

Type	Description
System.Boolean

Remarks

Workbook instances loaded from encrypted files or streams will cache the password used to decrypt the document and reuse it on subsequent saves. Therefore, HasOpenPassword will initially be true for Workbooks loaded from encrypted files or streams and false for all other Workbooks.

The open password can be cleared or reset by using SetOpenPassword.

HasProtectionPassword

Returns a boolean indicating if the Workbook has been protected with a password.

Declaration

public bool HasProtectionPassword { get; }

Property Value

Type	Description
System.Boolean

Remarks

When protecting a Workbook, a password is optional. The HasProtectionPassword will return true if the Workbook is currently protected (see IsProtected) and a password was specified when it was protected. To protect a Workbook without a password, one may use the Protect(Boolean, Boolean) method that doesn't take a password. To require a specific password to be entered in order to unprotect the Workbook one could use one of the other overloads that take a password (e.g.Unprotect(String)).

InProcessRuntime

Provides the in process runtime that the workbook can use to perform operations in javascript.

Declaration

public static IJSInProcessRuntime InProcessRuntime { get; set; }

Property Value

Type	Description
Microsoft.JSInterop.IJSInProcessRuntime

IsFileWriteProtected

Gets the value indicating whether the Workbook was loaded with file write protection and the correct password has not yet been provided to ValidateFileWriteProtectionPassword.

Declaration

public bool IsFileWriteProtected { get; }

Property Value

Type	Description
System.Boolean

Remarks

Workbook instances loaded from files or streams with a write protection password will initially have IsFileWriteProtected set to true. It is recommended that consumers of these instances prevent (or at least warn) users from automatically overwriting the files or streams from which the instances were loaded. These instances will initially not have their HasFileWriteProtectionPassword set to true. Although it is possible to validate a file write protection password when provided via ValidateFileWriteProtectionPassword, it is not possible to obtain the original password from the loaded file or stream. So file write protected Workbook instances which are loaded, but which never have the proper file write protection password validated will be saved without file write protection. Only when the password is validated via ValidateFileWriteProtectionPassword or overwritten via SetFileWriteProtectionPassword will HasFileWriteProtectionPassword return true, indicating that file write protection will be added to subsequently saved files or streams.

When IsFileWriteProtected is true and the file write protected password is validated via ValidateFileWriteProtectionPassword or overwritten via SetFileWriteProtectionPassword, IsFileWriteProtected will subsequently return false, indicating that the file or stream from which the Workbook was loaded can automatically be overwritten by the user if desired.

IsProtected

Returns a boolean indicating if the Workbook has been protected.

Declaration

public bool IsProtected { get; }

Property Value

Type	Description
System.Boolean

Remarks

The IsProtected property will return true if the Workbook is currently protected. When a Workbook is protected certain operations related to the Worksheets displayed or their order or the properties of the windows for the Workbook may be restricted based on the values of the Protection.

IterativeCalculationsEnabled

Gets or sets the value which indicates whether iterations are allowed while calculating formulas containing circular references.

Declaration

public bool IterativeCalculationsEnabled { get; set; }

Property Value

Type	Description
System.Boolean	The value which indicates whether iterations are allowed while calculating recursive formulas.

Remarks

When iterative calculations are enabled, a formula is allowed to use circular references, or directly or indirectly reference the cell to which it belongs. Microsoft Excel stops iteratively calculating formulas after iterating MaxRecursionIterations times or when all formula values change by less than MaxChangeInIteration between two iterations.

When iterative calculations are disabled, circular references are not allowed, and a formula which references the cell to which it belongs, directly or indirectly, will cause Microsoft Excel to show an error message and the cell will contain a Circularity error.

MaxChangeInIteration

Gets or sets the maximum change of the values in a formula between iterations which will exit from iteration.

Declaration

public double MaxChangeInIteration { get; set; }

Property Value

Type	Description
System.Double	The maximum change of the values in a formula between iterations which will exit from iteration.

Remarks

This property is only valid when IterativeCalculationsEnabled is True. Otherwise it is ignored.

When iterative calculations, or circular references, are enabled, this property determines the maximum change in all values of a formula between two iterations that will cause the formula to exit iterative calculations. Iterative calculations will also be stopped if the formula iterates MaxRecursionIterations times.

MaxColumnCount

Gets the maximum number of columns allowed in each worksheet based on the CurrentFormat.

Declaration

public int MaxColumnCount { get; }

Property Value

Type	Description
System.Int32

MaxRecursionIterations

Gets or sets the maximum number of times formulas should be iteratively calculated.

Declaration

public int MaxRecursionIterations { get; set; }

Property Value

Type	Description
System.Int32	The maximum number of times formulas should be iteratively calculated.

Remarks

This property is only valid when IterativeCalculationsEnabled is True. Otherwise it is ignored.

When iterative calculations, or circular references, are enabled, this property determines the number of iterations allowed when calculating iteratively.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The assigned value is outside the valid range of 1 and 32767.

MaxRowCount

Gets the maximum number of rows allowed in each worksheet based on the CurrentFormat.

Declaration

public int MaxRowCount { get; }

Property Value

Type	Description
System.Int32

NamedReferences

Gets the collection of named references in the workbook.

Declaration

public NamedReferenceCollection NamedReferences { get; }

Property Value

Type	Description
NamedReferenceCollection	The collection of named references in the workbook.

Remarks

Named references are typically used to refer to cells or ranges of cells by name. The named reference names are used by formulas instead of explicitly naming the cells or cell ranges.

Palette

Gets the color palette used when the saved file is opened in Microsoft Excel 2003 and earlier versions.

Declaration

public WorkbookColorPalette Palette { get; }

Property Value

Type	Description
WorkbookColorPalette

Remarks

When the file is opened in Microsoft Excel 2003 and earlier versions, the actual colors used in cells and shapes may not be displayed. Instead, the closest color in the palette will be displayed instead. Therefore, the palette can be customized if necessary to keep the colors as accurate as possible in older versions of Excel.

Precision

Gets or sets the precision to use when obtaining a cell's value.

Declaration

public Precision Precision { get; set; }

Property Value

Type	Description
Precision	The precision to use when obtaining a cell's value.

Remarks

The precision determines whether to use the actual value of the cell or the display value of the cell. These are typically the same, but the format of a cell could cause a loss of precision in the displayed value. For example, if a cell's value is 18.975, and a currency format is used for the cell, the display value will be 18.98.

Exceptions

Type	Condition
System.ComponentModel.InvalidEnumArgumentException	The assigned value is not defined in the Precision enumeration.

Protected

Gets or sets the value which indicates whether the workbook is protected.

Declaration

public bool Protected { get; set; }

Property Value

Type	Description
System.Boolean	The value which indicates whether the workbook is protected.

Remarks

If True, prevents changes to worksheet and to locked cells.

Protection

Returns an object that provides information used when the Workbook has been protected.

Declaration

public WorkbookProtection Protection { get; }

Property Value

Type	Description
WorkbookProtection

RecalculateBeforeSave

Gets or sets the value which indicates whether the workbook should recalculate all formulas before saving.

Declaration

public bool RecalculateBeforeSave { get; set; }

Property Value

Type	Description
System.Boolean	The value which indicates whether the workbook should recalculate all formulas before saving.

Remarks

This property only applies if the CalculationMode is set to Manual. Otherwise, it is ignored.

SaveExternalLinkedValues

Gets or sets the value which indicates whether to save values linked from external workbooks.

Declaration

public bool SaveExternalLinkedValues { get; set; }

Property Value

Type	Description
System.Boolean	The value which indicates whether to save values linked from external workbooks.

Remarks

This value will only be used when the workbook is opened in Microsoft Excel. When referencing external values and saving a workbook through the Excel assembly, external linked values will never be saved.

ScreenDpi

Gets or sets the Dpi to use when calculating row and column sizes for the workbook. If empty, the system Dpi will be used.

Declaration

public Size ScreenDpi { get; set; }

Property Value

Type	Description
Size

Exceptions

Type	Condition
System.ArgumentException	Occurs when the specified value is not empty and does not have two positive values.

Sheets

Gets the collection of sheets in the workbook.

Declaration

public SheetCollection Sheets { get; }

Property Value

Type	Description
SheetCollection	The collection of worksheets in the workbook.

Remarks

Use SelectedSheet to set the selected sheet. The selected sheet is the sheet seen when the workbook is opened in Microsoft Excel.

ShouldRemoveCarriageReturnsOnSave

Gets or sets the value which indicates whether carriage return characters should be removed from string values in cells when the workbook is saved to an Excel file.

Declaration

public bool ShouldRemoveCarriageReturnsOnSave { get; set; }

Property Value

Type	Description
System.Boolean	True if the saved workbook file should not contain the carriage return characters from cell values; False to export the string values as they have been set on the cells.

Remarks

In Microsoft Excel 2003, carriage return characters are displayed as boxes. Most of the time, this should not be seen and removing the carriage return characters has no adverse effect on the layout of the text within a cell. Therefore, this property is True by default.

StandardTableStyles

Gets the read-only collection of preset table styles in the workbook.

Declaration

public StandardTableStyleCollection StandardTableStyles { get; }

Property Value

Type	Description
StandardTableStyleCollection

Styles

Gets the collection of custom styles in the workbook.

Declaration

public WorkbookStyleCollection Styles { get; }

Property Value

Type	Description
WorkbookStyleCollection	The collection of custom styles in the workbook.

Remarks

Use this collection to add custom styles to Excel workbook. The user can apply those styles to different parts of excel workbook and thereby set complex formatting with ease.

SystemDpi

Gets or sets the default Dpi to use when calculating row and column sizes for the workbook. If empty, the resolved system Dpi will be used.

Declaration

public static Size SystemDpi { get; set; }

Property Value

Type	Description
Size

ValidateFormatStrings

Gets or sets the value indicating whether the format strings should be validated when they are set.

Declaration

public bool ValidateFormatStrings { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

This value is False by default to maintain backward compatibility.

When True, format strings will be validated when a FormatString property is set. An invalid format string will cause an exception. When False, invalid format strings will be allowed, but if the display text of a cell is requested, an exception will be thrown at that time. If invalid format strings are allowed and the workbook is saved and opened in Microsoft Excel, it will show an error.

WindowOptions

Gets the options which control various workbook level display properties.

Declaration

public WorkbookWindowOptions WindowOptions { get; }

Property Value

Type	Description
WorkbookWindowOptions	The options which control various workbook level display properties.

Remarks

The window options control properties of the child MDI window showing the workbook in Microsoft Excel. They also control display options of the workbook which do not change based on the selected worksheet.

Worksheets

Gets the collection of worksheets in the workbook.

Declaration

public WorksheetCollection Worksheets { get; }

Property Value

Type	Description
WorksheetCollection	The collection of worksheets in the workbook.

Remarks

Use SelectedWorksheet to set the selected worksheet. The selected worksheet is the worksheet seen when the workbook is opened in Microsoft Excel.

Methods

CharacterWidth256thsToPixels(Double)

Converts units of 1/256s of the average character width to pixels.

Declaration

public double CharacterWidth256thsToPixels(double characterWidth256ths)

Parameters

Type	Name	Description
System.Double	characterWidth256ths	The number of units of 1/256s of the average character width.

Returns

Type	Description
System.Double	The number of pixels equivalent to the `characterWidth256ths` value.

Remarks

The units of 1/256s of the average character width are based on the font height of the normal style.

ClearConnectionData()

Clears all external data connections from the Workbook.

Declaration

public void ClearConnectionData()

ClearPivotTableData()

Clears all pivot tables and associated slicers from the Workbook.

Declaration

public void ClearPivotTableData()

ClearVbaData()

Clears all vba information from the Workbook.

Declaration

public void ClearVbaData()

CreateNewWorkbookFont()

Factory method which creates new workbook font.

Declaration

public IWorkbookFont CreateNewWorkbookFont()

Returns

Type	Description
IWorkbookFont	The created excel font object.

Remarks

IWorkbookFont describes font used in excel workbook. If many parts of excel workbook have same and complex (more than one property in common) font formatting, use this method in following manner:

Create new font format with CreateNewWorkbookFont(),
Set all necessary properties on given font format,
Apply font format to all excel objects which use it with SetFontFormatting(IWorkbookFont) method.

Use of this procedure will simplify you code for complex font formats and increase speed of resulting program. It will not reduce total number of font formats in a workbook as font formats are internally cached no matter which method is used.

CreateNewWorksheetCellFormat()

Creates new worksheet cell format.

Declaration

public IWorksheetCellFormat CreateNewWorksheetCellFormat()

Returns

Type	Description
IWorksheetCellFormat	The cell format which was created.

Remarks

IWorksheetCellFormat describes cell specific formatting (font, number format, appearance etc.). Total number of different cell formats in excel workbook is limited to MaxExcelCellFormatCount. If many parts of excel workbook have same and complex (more than one property in common) cell formatting, use this method in following manner:

Create new cell format with CreateNewWorksheetCellFormat(),
Set all necessary properties on given cell format,
Apply cell format to all excel objects which use it with SetFormatting(IWorksheetCellFormat) method.

Use of this procedure will simplify you code for complex cell formats and increase speed of resulting program. It will not reduce total number of cell formats in a workbook as cell formats are internally cached no matter which method is used.

GetMaxColumnCount(WorkbookFormat)

Returns the number of columns that are supported by the specified format.

Declaration

public static int GetMaxColumnCount(WorkbookFormat format)

Parameters

Type	Name	Description
WorkbookFormat	format	The format used by the workbook.

Returns

Type	Description
System.Int32	The maximum number of columns supported by the format.

GetMaxRowCount(WorkbookFormat)

Returns the number of rows that are supported by the specified format.

Declaration

public static int GetMaxRowCount(WorkbookFormat format)

Parameters

Type	Name	Description
WorkbookFormat	format	The format used by the workbook.

Returns

Type	Description
System.Int32	The maximum number of rows supported by the format.

GetTable(String)

Gets the table with the specified name.

Declaration

public WorksheetTable GetTable(string name)

Parameters

Type	Name	Description
System.String	name	The name of the table to get.

Returns

Type	Description
WorksheetTable	A WorksheetTable instance if a table exists with the specified name; Otherwise null.

Remarks

Table names are compared case-insensitively.

GetWorkbookFormat(String)

Returns the WorkbookFormat based on the file extension of the specified file.

Declaration

public static Nullable<WorkbookFormat> GetWorkbookFormat(string fileName)

Parameters

Type	Name	Description
System.String	fileName	The filename of an excel file.

Returns

Type	Description
System.Nullable<WorkbookFormat>	The workbook format based on the file extension of the file, or null if the correct format cannot be determined.

IsValidFunctionName(String)

Gets a value indicating whether the specified function will be recognized and solved by Microsoft Excel when the workbook is saved out.

Declaration

public bool IsValidFunctionName(string functionName)

Parameters

Type	Name	Description
System.String	functionName	The case-insensitive name of the function.

Returns

Type	Description
System.Boolean	True if the function will be recognized in Microsoft Excel; False otherwise.

IsWorkbookEncrypted(Stream)

Determines whether the workbook in the specified stream is encrypted with an open password.

Declaration

public static bool IsWorkbookEncrypted(Stream stream)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream to check for encryption.

Returns

Type	Description
System.Boolean	True if the stream contains a workbook which is encrypted; False otherwise

Exceptions

Type	Condition
System.ArgumentNullException	Occurs when `stream` is null.

Load(Stream, WorkbookLoadOptions)

Reads a workbook from a stream.

Declaration

public static Workbook Load(Stream stream, WorkbookLoadOptions loadOptions = null)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream to read the workbook from.
WorkbookLoadOptions	loadOptions	The options to use to load the stream or null to use the default options.

Returns

Type	Description
Workbook	The workbook loaded from the stream.

Remarks

When loading the workbook, the format will be determined the file extension or by the contents of the file. If a FileStream is specified, the extension of the file will be examined. If the extension is a standard Excel format extension, the workbook will be assumed to be in the corresponding format. Otherwise, the contents of the file will be examined to try to determine the format. The CurrentFormat of the returned workbook will indicate the format the workbook was loaded from.

Exceptions

Type	Condition
System.ArgumentException	`stream` does not contain valid Microsoft Excel file contents.
System.ArgumentException	The file format cannot be determined from the specified stream.
System.InvalidOperationException	The format of the workbook data is in an unsupported format.
System.NotSupportedException	The workbook being loaded is in an Excel 2007 format and the CLR 2.0 Excel assembly is being used. The overload taking an IPackageFactory must be used in this case so the Excel 2007 file package can be accessed.
InvalidPasswordException	Occurs when the workbook is encrypted and the open password specified in the `loadOptions` is not correct.
DocumentEncryptedException	Occurs when the workbook is encrypted and no password was specified to open the stream in the `loadOptions`.
EncryptionAlgorithmNotSupportedException	Occurs when the workbook is encrypted with an unsupported encryption algorithm and cannot be decrypted.

PixelsToCharacterWidth256ths(Double)

Converts pixels to units of 1/256s of the average character width.

Declaration

public double PixelsToCharacterWidth256ths(double pixels)

Parameters

Type	Name	Description
System.Double	pixels	The number of pixels.

Returns

Type	Description
System.Double	The number of units of 1/256s of the average character width equivalent to the `pixels` value.

Remarks

The units of 1/256s of the average character width are based on the font height of the normal style.

Protect(Boolean, Boolean)

Protects the Workbook without a password.

Declaration

public void Protect(bool allowEditStructure = false, bool allowEditWindows = true)

Parameters

Type	Name	Description
System.Boolean	allowEditStructure	Optional boolean indicating the new value for the AllowEditStructure.
System.Boolean	allowEditWindows	Optional boolean indicating the new value for the AllowEditWindows.

Remarks

When a Workbook is protected without a password, the end user may unprotect the Workbook in Excel without having to supply a password. To programatically unprotect a Workbook, one may use the Unprotect() method.

When a Workbook is protected, the values of the properties of the WorkbookProtection instance from this Workbook's Protection property indicate the disabled operations.

Note: If IsProtected is already true, the method will be ignored.

Protect(SecureString, Boolean, Boolean)

Protects the worksheet with the specified password.

Declaration

public void Protect(SecureString password, bool allowEditStructure = false, bool allowEditWindows = true)

Parameters

Type	Name	Description
System.Security.SecureString	password	The password used to protect the Worksheet.
System.Boolean	allowEditStructure	Optional boolean indicating the new value for the AllowEditStructure.
System.Boolean	allowEditWindows	Optional boolean indicating the new value for the AllowEditWindows.

Remarks

When a Workbook is protected, the values of the properties of the WorkbookProtection instance from this Workbook's Protection property indicate the disabled operations.

Note: If IsProtected is already true, the method will be ignored.

Protect(String, Boolean, Boolean)

Protects the worksheet with the specified password.

Declaration

public void Protect(string password, bool allowEditStructure = false, bool allowEditWindows = true)

Parameters

Type	Name	Description
System.String	password	The password used to protect the Worksheet.
System.Boolean	allowEditStructure	Optional boolean indicating the new value for the AllowEditStructure.
System.Boolean	allowEditWindows	Optional boolean indicating the new value for the AllowEditWindows.

Remarks

When a Workbook is protected, the values of the properties of the WorkbookProtection instance from this Workbook's Protection property indicate the disabled operations.

Note: If IsProtected is already true, the method will be ignored.

Recalculate()

Recalculates all dirty formulas pending a calculation on the workbook.

Declaration

public void Recalculate()

Remarks

This can be used when the CalculationMode is Manual. In Manual mode, when cells are dirtied, formulas referencing those cells will not be recalculated until Recalculate is called or RecalculateBeforeSave is True and the workbook is saved.

To force a recalculation of non-dirty formulas, use the Recalculate(Boolean) overload and specify True for the includeNonDirtyFormulas parameter.

Recalculate(Boolean)

Recalculates all formulas on the workbook.

Declaration

public void Recalculate(bool includeNonDirtyFormulas)

Parameters

Type	Name	Description
System.Boolean	includeNonDirtyFormulas	True to recalculate all formulas on the workbook regardless of whether they had a pending evaluation. False to only calculate dirty formulas.

Remarks

RegisterUserDefinedFunction(ExcelCalcFunction)

Registers a single ExcelCalcFunction instance.

Declaration

public bool RegisterUserDefinedFunction(ExcelCalcFunction userDefinedFunction)

Parameters

Type	Name	Description
ExcelCalcFunction	userDefinedFunction	User defined function instance to register

Returns

Type	Description
System.Boolean	Returns true if the type was registered successfully, else false if the registration failed

Remarks

Users can build custom functions used in formulas by sub-classing the ExcelCalcFunction class. Once the derived class is instantiated it must be registered by using the RegisterUserDefinedFunction method before being available and referenced by a formulas. Users can build a library of functions packaged in an assembly and register all the functions within the assembly by using the RegisterUserDefinedFunctionLibrary(Assembly) method.

RegisterUserDefinedFunctionLibrary(Assembly)

Registers an assembly containing ExcelCalcFunction derived types.

Declaration

public bool RegisterUserDefinedFunctionLibrary(Assembly assembly)

Parameters

Type	Name	Description
System.Reflection.Assembly	assembly	Loaded assembly to register

Returns

Type	Description
System.Boolean	Returns true if the assembly was registered successfully, else false if the registration failed

Remarks

All types within the registered assembly are enumerated and any that derive from ExcelCalcFunction class are added to the list of available formula functions

ResumeCalculations()

Resumes the calculation of formulas.

Declaration

public void ResumeCalculations()

Remarks

If calculations were not suspended when this is called, it will have no effect.

For each call to SuspendCalculations(), a call to ResumeCalculations must be made. As soon as the number of calls to ResumeCalculations equals the number of calls to SuspendCalculations, calculations will be resumed.

Save(Stream, IPackageFactory)

Writes the workbook to a stream.

Declaration

public void Save(Stream stream, IPackageFactory packageFactory)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream to write the workbook to.
IPackageFactory	packageFactory	An IPackageFactory which can be used to open an IPackage from a stream.

Remarks

The workbook will be written in the format specified by the CurrentFormat.

Exceptions

Type	Condition
System.ArgumentNullException	`stream` is null.
System.InvalidOperationException	The workbook has no worksheets in its Worksheets collection.
System.InvalidOperationException	No worksheet in this workbook's Worksheets collection has its Visibility set to Visible.
System.InvalidOperationException	A CustomView in the workbook's CustomViews collection has all worksheets hidden. At least one worksheet must be visible in all custom views.

Save(Stream, WorkbookSaveOptions)

Writes the workbook to a stream.

Declaration

public void Save(Stream stream, WorkbookSaveOptions saveOptions = null)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream to write the workbook to.
WorkbookSaveOptions	saveOptions	The options to use to save the stream or null to use the default options.

Remarks

The workbook will be written in the format specified by the CurrentFormat.

Exceptions

Type	Condition
System.ArgumentNullException	`stream` is null.
System.InvalidOperationException	The workbook has no worksheets in its Worksheets collection.
System.InvalidOperationException	No worksheet in this workbook's Worksheets collection has its Visibility set to Visible.
System.InvalidOperationException	A CustomView in the workbook's CustomViews collection has all worksheets hidden. At least one worksheet must be visible in all custom views.

SetCurrentFormat(WorkbookFormat)

Sets the current format of the workbook.

Declaration

public void SetCurrentFormat(WorkbookFormat format)

Parameters

Type	Name	Description
WorkbookFormat	format	The file format to use when imposing format restrictions and saving.

Exceptions

Type	Condition
System.ComponentModel.InvalidEnumArgumentException	`format` is not defined in the WorkbookFormat enumeration.
System.InvalidOperationException	The workbook already contains data which exceeds the limits imposed by `format`.

SetEncryptionMode(WorkbookEncryptionMode)

Sets the encryption modes to use to encrypt documents saved in the 2007 file formats and later.

Declaration

public void SetEncryptionMode(WorkbookEncryptionMode encryptionMode)

Parameters

Type	Name	Description
WorkbookEncryptionMode	encryptionMode

SetFileWriteProtectionPassword(SecureString, String)

Sets the password used to protect the file from automatic writes.

Declaration

public void SetFileWriteProtectionPassword(SecureString password, string userName = null)

Parameters

Type	Name	Description
System.Security.SecureString	password	The password to use to protect the file; null or the empty string will remove write protection from the file.
System.String	userName	The name of the user to store as the FileWriteProtectedBy value. If null is specified and a valid password is specified, the Environment.UserName will be used instead (on all platforms except for Silverlight and WinRT).

Remarks

If the userName is specified but the password is being clear because it is being set to null or empty, the user name is ignored and FileWriteProtectedBy is set to null.

SetFileWriteProtectionPassword(String, String)

Sets the password used to protect the file from automatic writes.

Declaration

public void SetFileWriteProtectionPassword(string password, string userName = null)

Parameters

Type	Name	Description
System.String	password	The password to use to protect the file; null or the empty string will remove write protection from the file.
System.String	userName	The name of the user to store as the FileWriteProtectedBy value. If null is specified and a valid password is specified, the Environment.UserName will be used instead (on all platforms except for Silverlight and WinRT).

Remarks

If the userName is specified but the password is being clear because it is being set to null or empty, the user name is ignored and FileWriteProtectedBy is set to null.

SetOpenPassword(SecureString)

Sets the password used to encrypt the document on subsequent saves.

Declaration

public void SetOpenPassword(SecureString password)

Parameters

Type	Name	Description
System.Security.SecureString	password	The password to use to encrypt the document; null will prevent the document from being encrypted on subsequent saves.

SetOpenPassword(String)

Sets the password used to encrypt the document on subsequent saves.

Declaration

public void SetOpenPassword(string password)

Parameters

Type	Name	Description
System.String	password	The password to use to encrypt the document; null or the empty string will prevent the document from being encrypted on subsequent saves.

SuspendCalculations()

Temporarily suspends the calculation of formulas.

Declaration

public void SuspendCalculations()

Remarks

This should be used when adding many formulas or modifying large amounts of data on a workbook at once so formulas are not calculated each time cells are dirtied.

For each call to SuspendCalculations, a call to ResumeCalculations() must be made. As soon as the number of calls to ResumeCalculations equals the number of calls to SuspendCalculations, calculations will be resumed.

Unprotect()

Removes the Workbook protection.

Declaration

public void Unprotect()

Remarks

Note: If the HasProtectionPassword returns true and you only want to remove the protection if the correct password was provided then the Unprotect(String) should be used instead.

Declaration

public void Unprotect(SecureString password)

Parameters

Type	Name	Description
System.Security.SecureString	password	The password to validate against the current Worksheet protection password

Remarks

Note: If the Worksheet is not currently protected (i.e. IsProtected returns false) the method will not do anything. Also, if the Worksheet was not protected with a password (i.e. HasProtectionPassword returns false) the specified password will not be used and the protection will removed as if the Unprotect() method had been invoked.

Unprotect(String)

Attempts to use the specified password to remove the Worksheet protection currently in place.

Declaration

public void Unprotect(string password)

Parameters

Type	Name	Description
System.String	password	The password to validate against the current Worksheet protection password

Remarks

ValidateFileWriteProtectionPassword(SecureString)

Validates the password for a Workbook loaded with file write protection. and returns the value indicating whether the protection was successfully disabled.

Declaration

public bool ValidateFileWriteProtectionPassword(SecureString password)

Parameters

Type	Name	Description
System.Security.SecureString	password

Returns

Type	Description
System.Boolean	True if the workbook file is write protected or has a file write protection password to be used on subsequent saves and the specified password matches the password used to protect the file.

Remarks

Workbook instances loaded from files or streams with a write protection password will initially have IsFileWriteProtected set to true. It is recommended that consumers of these instances prevent (or at least warn) users from automatically overwriting the files or streams from which the instances were loaded. These instances will initially not have their HasFileWriteProtectionPassword set to true. Although it is possible to validate a file write protection password when provided via ValidateFileWriteProtectionPassword, it is not possible to obtain the original password from the loaded file or stream. So file write protected Workbook instances which are loaded, but which never have the proper file write protection password validated will be saved without file write protection. Only when the password is validated via ValidateFileWriteProtectionPassword or overwritten via SetFileWriteProtectionPassword will HasFileWriteProtectionPassword return true, indicating that file write protection will be added to subsequently saved files or streams.

Declaration

public bool ValidateFileWriteProtectionPassword(string password)

Parameters

Type	Name	Description
System.String	password

Returns

Type	Description
System.Boolean	True if the workbook file is write protected or has a file write protection password to be used on subsequent saves and the specified password matches the password used to protect the file.

Remarks

Workbook instances loaded from files or streams with a write protection password will initially have IsFileWriteProtected set to true. It is recommended that consumers of these instances prevent (or at least warn) users from automatically overwriting the files or streams from which the instances were loaded. These instances will initially not have their HasFileWriteProtectionPassword set to true. Although it is possible to validate a file write protection password when provided via ValidateFileWriteProtectionPassword, it is not possible to obtain the original password from the loaded file or stream. So file write protected Workbook instances which are loaded, but which never have the proper file write protection password validated will be saved without file write protection. Only when the password is validated via ValidateFileWriteProtectionPassword or overwritten via SetFileWriteProtectionPassword will HasFileWriteProtectionPassword return true, indicating that file write protection will be added to subsequently saved files or streams.

Class Workbook

Inheritance

Namespace: Infragistics.Documents.Excel

Assembly: IgniteUI.Blazor.Documents.Excel.dll

Syntax

Remarks

Constructors

Workbook()

Declaration

Remarks

See Also

Workbook(WorkbookFormat)

Declaration

Parameters

Remarks

Exceptions

See Also

Fields

MaxExcel2007CellFormatCount

Declaration

Field Value

MaxExcel2007ColumnCount

Declaration

Field Value

MaxExcel2007RowCount

Declaration

Field Value

MaxExcelCellFormatCount

Declaration

Field Value

MaxExcelColumnCount

Declaration

Field Value

MaxExcelRowCount

Declaration

Field Value

MaxExcelWorkbookFonts

Declaration

Field Value

Properties

CalculationMode

Declaration

Property Value

Remarks

Exceptions

See Also

CellReferenceMode

Declaration

Property Value

Remarks

Exceptions

Culture

Declaration

Property Value

Remarks

CurrentFormat

Declaration

Property Value

See Also

CustomTableStyles

Declaration

Property Value

See Also

CustomViews

Declaration

Property Value

Remarks

See Also

DateSystem

Declaration

Property Value

Exceptions

DefaultTableStyle

Declaration

Property Value

Remarks

Exceptions

See Also

DocumentProperties

Declaration