API Reference
ExcelDocument
Represents an Excel document and provides methods for creating, loading and saving spreadsheets.
Inheritance
- Object
- ExcelDocument
Usage
This type appears in these public API surfaces even when no hand-authored example is attached directly to the page.
Returned or exposed by
- Method ExcelDocument.Create
- Method ExcelDocument.Create
- Method ExcelDocument.Create
- Method ExcelDocument.Load
- Method ExcelDocument.Load
- Method ExcelDocument.LoadAsync
- Method ExcelDocument.LoadAsync
- Method ExcelDocument.LoadEncrypted
- Method ExcelDocument.LoadEncrypted
- Method ExcelDocument.LoadEncryptedAsync
- Method ExcelDocument.LoadEncryptedAsync
- Method ExcelFluentWorkbook.End
Accepted by parameters
- Constructor ApplicationProperties.ApplicationProperties
- Constructor BuiltinDocumentProperties.BuiltinDocumentProperties
- Extension method ExcelDocument.GetOrCreateSheet
- Method ExcelDocument.CopyWorkSheetFrom
- Method ExcelDocument.CopyWorksheetFrom
- Method ExcelHostExtensions.GetOrCreateSheet
- Method ExcelRead.ReadUsedRangeObjects
- Constructor ExcelSheet.ExcelSheet
- Constructor ExcelSheet.ExcelSheet
- Constructor ExcelFluentWorkbook.ExcelFluentWorkbook
- Constructor SheetComposer.SheetComposer
- Method SheetIndex.Add
- Method SheetIndex.AddBackLinks
- Method SharedStringPlanner.ApplyAndFixup
- Method SharedStringPlanner.ApplyTo
Constructors
public ExcelDocument() #Methods
public Void AddBackLinksToToc(String tocSheetName = "TOC", Int32 row = 2, Int32 col = 1, String text = "← TOC") #VoidAdds a small back link to the TOC on each worksheet at the given cell (default A2).
Parameters
- tocSheetName System.String = "TOC"
- row System.Int32 = 2
- col System.Int32 = 1
- text System.String = "← TOC"
public Void AddTableOfContents(String sheetName = "TOC", Boolean placeFirst = true, Boolean withHyperlinks = true, Boolean includeNamedRanges = false, Boolean includeHiddenNamedRanges = false, Predicate<String> rangeNameFilter = null, Boolean styled = true) #VoidAdds or refreshes a visually styled Table of Contents sheet with hyperlinks.
Parameters
- sheetName System.String = "TOC"
- TOC sheet name.
- placeFirst System.Boolean = true
- Move TOC as the first sheet.
- withHyperlinks System.Boolean = true
- Create internal hyperlinks.
- includeNamedRanges System.Boolean = false
- Also list defined names in a dedicated column.
- includeHiddenNamedRanges System.Boolean = false
- When listing defined names, include ones marked Hidden.
- rangeNameFilter System.Predicate{System.String} = null
- Optional filter to include only matching defined names.
- styled System.Boolean = true
- When true, renders a banner and a formatted table with AutoFilter.
public ExcelSheet AddWorkSheet(String workSheetName = "") #ExcelSheetAdds a worksheet to the document.
Parameters
- workSheetName System.String = ""
- Worksheet name.
Returns
Created ExcelSheet instance.
public ExcelSheet AddWorkSheet(String workSheetName, SheetNameValidationMode validationMode) #ExcelSheetAdds a worksheet to the document with control over name validation.
Parameters
- workSheetName System.String
- Requested worksheet name.
- validationMode OfficeIMO.Excel.SheetNameValidationMode
- How to validate the sheet name: None (no checks), Sanitize (coerce), or Strict (throw on invalid).
Returns
Created ExcelSheet instance.
public Int32 ApplyTemplate(IDictionary<String, Object> values, IFormatProvider provider = null, Boolean throwOnMissing = false) #Int32Replaces {{Marker}} placeholders across all worksheets using the supplied values.
Parameters
- values System.Collections.Generic.IDictionary{System.String,System.Object}
- provider System.IFormatProvider = null
- throwOnMissing System.Boolean = false
public Int32 ApplyTemplate(Object model, ExcelTemplateOptions options) #Int32Replaces {{Marker}} placeholders across all worksheets using the supplied values and options.
Parameters
- values System.Collections.Generic.IDictionary{System.String,System.Object}
- options OfficeIMO.Excel.ExcelTemplateOptions
public Int32 ApplyTemplate(Object model, IFormatProvider provider = null, Boolean throwOnMissing = false) #Int32Replaces {{Marker}} placeholders across all worksheets using public properties from the supplied model. Nested properties are exposed as dotted marker names, for example {{Customer.Name}}.
Parameters
- model System.Object
- provider System.IFormatProvider = null
- throwOnMissing System.Boolean = false
ApplyTemplate(System.Object model, OfficeIMO.Excel.ExcelTemplateOptions options) #Replaces {{Marker}} placeholders across all worksheets using public properties from the supplied model and options. Nested properties are exposed as dotted marker names, for example {{Customer.Name}}.
Parameters
- model System.Object
- options OfficeIMO.Excel.ExcelTemplateOptions
public Int32 ApplyTemplateSheets<T>(String templateSheetName, IEnumerable<T> models, Func<T, Int32, String> sheetNameSelector = null, ExcelTemplateOptions options = null) #Int32Repeats a template worksheet for each supplied value dictionary and applies markers to each generated sheet.
Type Parameters
- T
Parameters
- templateSheetName System.String
- Worksheet to use as the sheet template.
- sheets System.Collections.Generic.IEnumerable{System.Collections.Generic.IDictionary{System.String,System.Object}}
- Per-sheet value dictionaries.
- sheetNameSelector System.Func{System.Collections.Generic.IDictionary{System.String,System.Object},System.Int32,System.String} = null
- Optional generated sheet name selector. The index is zero-based.
- options OfficeIMO.Excel.ExcelTemplateOptions = null
- Optional template binding options.
Returns
Total marker replacements across all generated sheets.
ApplyTemplateSheets``1(System.String templateSheetName, System.Collections.Generic.IEnumerable{``0} models, System.Func{``0,System.Int32,System.String} sheetNameSelector, OfficeIMO.Excel.ExcelTemplateOptions options) #Repeats a template worksheet for each supplied model and applies markers to each generated sheet. Public properties are exposed as marker names, including nested dotted names.
Parameters
- templateSheetName System.String
- Worksheet to use as the sheet template.
- models System.Collections.Generic.IEnumerable{``0}
- Per-sheet models.
- sheetNameSelector System.Func{``0,System.Int32,System.String}
- Optional generated sheet name selector. The index is zero-based.
- options OfficeIMO.Excel.ExcelTemplateOptions
- Optional template binding options.
Returns
Total marker replacements across all generated sheets.
public ExcelFluentWorkbook AsFluent() #ExcelFluentWorkbookReturns a fluent API wrapper for this document.
public Int32 Calculate() #Int32Calculates formulas that are supported by OfficeIMO's lightweight formula engine and writes cached values. Unsupported formulas are preserved unchanged for Excel-compatible applications to calculate.
Returns
The number of formula cells with updated cached values.
public IReadOnlyList<ExcelRangeDifference> CompareRanges(ExcelSheet leftSheet, String leftRange, ExcelSheet rightSheet, String rightRange, ExcelRangeCompareOptions options = null) #IReadOnlyList<ExcelRangeDifference>Compares two worksheet ranges and returns cell-level differences.
Parameters
- leftSheet OfficeIMO.Excel.ExcelSheet
- leftRange System.String
- rightSheet OfficeIMO.Excel.ExcelSheet
- rightRange System.String
- options OfficeIMO.Excel.ExcelRangeCompareOptions = null
public IReadOnlyList<ExcelRangeDifference> CompareWorksheets(ExcelSheet leftSheet, ExcelSheet rightSheet, ExcelRangeCompareOptions options = null) #IReadOnlyList<ExcelRangeDifference>Compares the used ranges of two worksheets.
Parameters
- leftSheet OfficeIMO.Excel.ExcelSheet
- rightSheet OfficeIMO.Excel.ExcelSheet
- options OfficeIMO.Excel.ExcelRangeCompareOptions = null
CompareWorksheets(OfficeIMO.Excel.ExcelSheet leftSheet, OfficeIMO.Excel.ExcelSheet rightSheet, OfficeIMO.Excel.ExcelRangeCompareOptions options) #Compares the used ranges of two worksheets.
Parameters
- leftSheet OfficeIMO.Excel.ExcelSheet
- rightSheet OfficeIMO.Excel.ExcelSheet
- options OfficeIMO.Excel.ExcelRangeCompareOptions
public Void Compose(String sheetName, Action<SheetComposer> compose, SheetTheme theme = null) #VoidFluent sugar: compose a worksheet using SheetComposer without exposing the builder type to callers.
Parameters
- sheetName System.String
- compose System.Action{OfficeIMO.Excel.Fluent.SheetComposer}
- theme OfficeIMO.Excel.Fluent.SheetTheme = null
public Void ConfigureFullCalculationOnOpen() #VoidRequests a full workbook recalculation when the file is opened.
public ExcelSheet CopyWorksheet(ExcelSheet sourceSheet, String newSheetName, SheetNameValidationMode validationMode = Sanitize) #ExcelSheetCopies a worksheet within this workbook.
Parameters
- sourceSheetName System.String
- Name of the worksheet to copy.
- newSheetName System.String
- Requested name for the copied worksheet.
- validationMode OfficeIMO.Excel.SheetNameValidationMode = Sanitize
- How to validate or sanitize newSheetName.
Returns
The copied worksheet.
CopyWorksheet(System.String sourceSheetName, System.String newSheetName, OfficeIMO.Excel.SheetNameValidationMode validationMode) #Copies a worksheet within this workbook.
Parameters
- sourceSheetName System.String
- newSheetName System.String
- validationMode OfficeIMO.Excel.SheetNameValidationMode
CopyWorkSheet(OfficeIMO.Excel.ExcelSheet sourceSheet, System.String newSheetName, OfficeIMO.Excel.SheetNameValidationMode validationMode) #Copies a worksheet within this workbook.
Parameters
- sourceSheet OfficeIMO.Excel.ExcelSheet
- Worksheet to copy.
- newSheetName System.String
- Requested name for the copied worksheet.
- validationMode OfficeIMO.Excel.SheetNameValidationMode
- How to validate or sanitize newSheetName.
Returns
The copied worksheet.
CopyWorksheet(OfficeIMO.Excel.ExcelSheet sourceSheet, System.String newSheetName, OfficeIMO.Excel.SheetNameValidationMode validationMode) #Copies a worksheet within this workbook.
Parameters
- sourceSheet OfficeIMO.Excel.ExcelSheet
- newSheetName System.String
- validationMode OfficeIMO.Excel.SheetNameValidationMode
public ExcelSheet CopyWorksheetFrom(ExcelDocument sourceDocument, String sourceSheetName, String newSheetName, SheetNameValidationMode validationMode = Sanitize) #ExcelSheetCopies a worksheet from another workbook into this workbook. Values are copied through the reader/writer surface so callers can combine workbooks without sharing package parts.
Parameters
- sourceDocument OfficeIMO.Excel.ExcelDocument
- Workbook containing the source worksheet.
- sourceSheetName System.String
- Name of the worksheet to copy.
- newSheetName System.String
- Requested name for the copied worksheet.
- validationMode OfficeIMO.Excel.SheetNameValidationMode = Sanitize
- How to validate or sanitize newSheetName.
Returns
The copied worksheet.
CopyWorksheetFrom(OfficeIMO.Excel.ExcelDocument sourceDocument, System.String sourceSheetName, System.String newSheetName, OfficeIMO.Excel.SheetNameValidationMode validationMode) #Copies a worksheet from another workbook into this workbook.
Parameters
- sourceDocument OfficeIMO.Excel.ExcelDocument
- sourceSheetName System.String
- newSheetName System.String
- validationMode OfficeIMO.Excel.SheetNameValidationMode
public static ExcelDocument Create(String filePath) #ExcelDocumentCreates a new Excel document at the specified path.
Parameters
- filePath System.String
- Path to the new file.
Returns
Created ExcelDocument instance.
public static ExcelDocument Create(Stream stream, Boolean autoSave = true) #ExcelDocumentCreates a new Excel document at the specified path with explicit AutoSave behavior.
Parameters
- filePath System.String
- Path to the new file.
- autoSave System.Boolean = true
- When true, saves changes on dispose.
Returns
Created ExcelDocument instance.
Create(System.IO.Stream stream, System.Boolean autoSave) #Creates a new Excel document in memory and optionally persists it to the provided stream on dispose.
Parameters
- stream System.IO.Stream
- Destination stream to receive the workbook package.
- autoSave System.Boolean
- When true, the package is written back to the stream on dispose.
Returns
Created ExcelDocument instance.
public static ExcelDocument Create(String filePath, String workSheetName) #ExcelDocumentCreates a new Excel document with a single worksheet.
Parameters
- filePath System.String
- Path to the new file.
- workSheetName System.String
- Name of the worksheet.
Returns
Created ExcelDocument instance.
public ExcelWorkbookSnapshot CreateInspectionSnapshot(ExcelReadOptions options = null) #ExcelWorkbookSnapshotCreates an immutable workbook snapshot that exposes OfficeIMO's current workbook model for downstream integrations.
Parameters
- options OfficeIMO.Excel.ExcelReadOptions = null
public ExcelDocumentReader CreateReader(ExcelReadOptions options = null) #ExcelDocumentReaderCreates a reader that shares this document's underlying OpenXML handle (no new file handle). Caller should dispose the reader after use; it will not close this document.
Parameters
- options OfficeIMO.Excel.ExcelReadOptions = null
public Void CreateTableOfContents(String sheetName = "TOC") #VoidBackward-compatible alias for AddTableOfContents.
Parameters
- sheetName System.String = "TOC"
public virtual async ValueTask DisposeAsync() #ValueTaskAsynchronously releases resources used by the document.
EnsureValidDefinedName(System.String arg1, OfficeIMO.Excel.NameValidationMode arg2) #Ensures a defined name complies with Excel rules. In Sanitize mode, returns a corrected name. Throws in Strict mode when input is invalid. Rules: - 1..255 characters - First char must be a letter or underscore - Allowed characters: letters, digits, underscore, period - Cannot look like a cell reference (e.g., A1, AA10) or an R1C1 reference - Cannot be TRUE or FALSE (case-insensitive)
Parameters
- arg1 System.String
- arg2 OfficeIMO.Excel.NameValidationMode
public IReadOnlyDictionary<String, String> GetAllNamedRanges(ExcelSheet scope = null) #IReadOnlyDictionary<String, String>Returns all defined names with their A1 ranges, optionally limited to a sheet scope.
Parameters
- scope OfficeIMO.Excel.ExcelSheet = null
public String GetNamedRange(String name, ExcelSheet scope = null) #StringReturns the A1 range for a defined name. If scope is supplied, searches a sheet‑local name first.
Parameters
- name System.String
- Defined name to resolve.
- scope OfficeIMO.Excel.ExcelSheet = null
- Optional sheet scope to resolve a local name.
Returns
A1 range string or null if not found.
GetOrInitTableNameCache() #Returns the workbook-level cache of table names, initializing it from the current document if needed. Case-insensitive comparison.
public IReadOnlyList<ExcelPivotTableInfo> GetPivotTables() #IReadOnlyList<ExcelPivotTableInfo>Returns all pivot tables defined in the workbook.
public ExcelSheet GetSheet(String name) #ExcelSheetGets a worksheet by name.
Parameters
- name System.String
public IReadOnlyList<String> GetSheetNames() #IReadOnlyList<String>Returns worksheet names in workbook order.
public IReadOnlyList<ExcelTableInfo> GetTables() #IReadOnlyList<ExcelTableInfo>Returns all Excel tables defined in the workbook.
public IReadOnlyList<ExcelDataSetImportResult> InsertDataSet(DataSet dataSet, Boolean createTables = true, TableStyle tableStyle = TableStyleMedium2, Boolean includeHeaders = true, Boolean includeAutoFilter = true, Boolean autoFit = false, Nullable<ExecutionMode> mode = null, CancellationToken ct = null) #IReadOnlyList<ExcelDataSetImportResult>Imports a DataSet into the workbook with one worksheet per source DataTable.
Parameters
- dataSet System.Data.DataSet
- Source dataset.
- createTables System.Boolean = true
- Create an Excel table over each imported DataTable.
- tableStyle OfficeIMO.Excel.TableStyle = TableStyleMedium2
- Excel table style to use when createTables is true.
- includeHeaders System.Boolean = true
- Write source column names as the first row.
- includeAutoFilter System.Boolean = true
- Include table AutoFilter dropdowns when creating tables.
- autoFit System.Boolean = false
- Auto-fit imported columns after each sheet is created.
- mode System.Nullable{OfficeIMO.Excel.ExecutionMode} = null
- Optional execution mode override for DataTable writes.
- ct System.Threading.CancellationToken = null
- Cancellation token.
Returns
Import results describing the created worksheets and ranges.
public ExcelFeatureReport InspectFeatures() #ExcelFeatureReportInspects workbook features and reports which ones OfficeIMO can edit, partially edit, preserve, or does not support yet.
public ExcelFormulaInspection InspectFormulas() #ExcelFormulaInspectionInspects formula cells across all worksheets without changing workbook contents.
public ExcelTemplateInspection InspectTemplate() #ExcelTemplateInspectionInspects {{Marker}} placeholders across all worksheets without modifying the workbook.
public ExcelTemplateInspection InspectTemplate(IDictionary<String, Object> values) #ExcelTemplateInspectionInspects {{Marker}} placeholders across all worksheets and reports which markers are missing from the supplied values.
Parameters
- values System.Collections.Generic.IDictionary{System.String,System.Object}
public ExcelTemplateInspection InspectTemplate(Object model) #ExcelTemplateInspectionInspects {{Marker}} placeholders across all worksheets and reports which markers are missing from public properties on the supplied model.
Parameters
- model System.Object
public Void InvalidateFormulas() #VoidMarks all formulas dirty so Excel-compatible applications recalculate them on open.
public ExcelWorksheetMergeResult JoinWorksheets(ExcelSheet targetSheet, ExcelSheet sourceSheet, ExcelWorksheetMergeOptions options = null) #ExcelWorksheetMergeResultAlias for ExcelWorksheetMergeOptions).
Parameters
- targetSheet OfficeIMO.Excel.ExcelSheet
- sourceSheet OfficeIMO.Excel.ExcelSheet
- options OfficeIMO.Excel.ExcelWorksheetMergeOptions = null
JoinWorksheets(OfficeIMO.Excel.ExcelSheet targetSheet, OfficeIMO.Excel.ExcelSheet sourceSheet, OfficeIMO.Excel.ExcelWorksheetMergeOptions options) #Alias for ExcelWorksheetMergeOptions).
Parameters
- targetSheet OfficeIMO.Excel.ExcelSheet
- sourceSheet OfficeIMO.Excel.ExcelSheet
- options OfficeIMO.Excel.ExcelWorksheetMergeOptions
public static ExcelDocument Load(String filePath, Boolean readOnly = false, Boolean autoSave = false, Action<String, Exception> log = null, OpenSettings openSettings = null) #ExcelDocumentLoads an existing Excel document.
Parameters
- filePath System.String
- Path to the file.
- readOnly System.Boolean = false
- Open the file in read-only mode.
- autoSave System.Boolean = false
- Enable auto-save on dispose.
- log System.Action{System.String,System.Exception} = null
- Optional callback invoked when normalization failures are encountered.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
public static ExcelDocument Load(Uri uri, ExcelHttpLoadOptions httpOptions = null, Boolean readOnly = true, OpenSettings openSettings = null) #ExcelDocumentLoads an existing Excel document from the provided stream.
Parameters
- stream System.IO.Stream
- Input stream containing the workbook package.
- readOnly System.Boolean = null
- Open the document in read-only mode.
- autoSave System.Boolean = true
- Enable auto-save on dispose.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
Load(System.Uri uri, OfficeIMO.Excel.ExcelHttpLoadOptions httpOptions, System.Boolean readOnly, DocumentFormat.OpenXml.Packaging.OpenSettings openSettings) #Loads an Excel workbook from a remote URI.
Parameters
- uri System.Uri
- HTTP or HTTPS URI of the workbook.
- httpOptions OfficeIMO.Excel.ExcelHttpLoadOptions
- Optional HTTP loading options.
- readOnly System.Boolean
- Open the document in read-only mode. Remote loads are read-only by default.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
public static async Task<ExcelDocument> LoadAsync(String filePath, Boolean readOnly = false, Boolean autoSave = false, OpenSettings openSettings = null) #Task<ExcelDocument>Asynchronously loads an Excel document from the specified path.
Parameters
- filePath System.String
- Path to the Excel file.
- readOnly System.Boolean = false
- Open the file in read-only mode.
- autoSave System.Boolean = false
- Enable auto-save on dispose.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
Exceptions
FileNotFoundException– Thrown when the file does not exist.
public static async Task<ExcelDocument> LoadAsync(Uri uri, ExcelHttpLoadOptions httpOptions = null, Boolean readOnly = true, OpenSettings openSettings = null, CancellationToken cancellationToken = null) #Task<ExcelDocument>Asynchronously loads an Excel document from the provided stream.
Parameters
- stream System.IO.Stream
- Input stream containing the workbook package.
- readOnly System.Boolean = null
- Open the document in read-only mode.
- autoSave System.Boolean = true
- Enable auto-save on dispose.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
Returns
Loaded ExcelDocument instance.
LoadAsync(System.Uri uri, OfficeIMO.Excel.ExcelHttpLoadOptions httpOptions, System.Boolean readOnly, DocumentFormat.OpenXml.Packaging.OpenSettings openSettings, System.Threading.CancellationToken cancellationToken) #Asynchronously loads an Excel workbook from a remote URI.
Parameters
- uri System.Uri
- HTTP or HTTPS URI of the workbook.
- httpOptions OfficeIMO.Excel.ExcelHttpLoadOptions
- Optional HTTP loading options.
- readOnly System.Boolean
- Open the document in read-only mode. Remote loads are read-only by default.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings
- Optional Open XML settings to control how the package is opened.
- cancellationToken System.Threading.CancellationToken
- Cancellation token.
Returns
Loaded ExcelDocument instance.
public static ExcelDocument LoadEncrypted(String filePath, String password, Boolean readOnly = false, Boolean autoSave = false, Action<String, Exception> log = null, OpenSettings openSettings = null) #ExcelDocumentLoads a password-encrypted Office Open XML workbook.
Parameters
- filePath System.String
- Path to the encrypted workbook.
- password System.String
- Password used to decrypt the workbook package.
- readOnly System.Boolean = false
- Open the decrypted workbook in read-only mode.
- autoSave System.Boolean = false
- Encrypted loads do not support auto-save. Use ExcelSaveOptions) to persist encrypted changes.
- log System.Action{System.String,System.Exception} = null
- Optional callback invoked when normalization failures are encountered.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
public static ExcelDocument LoadEncrypted(Stream stream, String password, Boolean readOnly = false, Boolean autoSave = false, OpenSettings openSettings = null) #ExcelDocumentLoads a password-encrypted Office Open XML workbook from a stream.
Parameters
- stream System.IO.Stream
- Input stream containing the encrypted workbook.
- password System.String
- Password used to decrypt the workbook package.
- readOnly System.Boolean = false
- Open the decrypted workbook in read-only mode.
- autoSave System.Boolean = false
- Encrypted loads do not support auto-save. Use ExcelSaveOptions) to persist encrypted changes.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
public static async Task<ExcelDocument> LoadEncryptedAsync(String filePath, String password, Boolean readOnly = false, Boolean autoSave = false, OpenSettings openSettings = null) #Task<ExcelDocument>Asynchronously loads a password-encrypted Office Open XML workbook.
Parameters
- filePath System.String
- Path to the encrypted workbook.
- password System.String
- Password used to decrypt the workbook package.
- readOnly System.Boolean = false
- Open the decrypted workbook in read-only mode.
- autoSave System.Boolean = false
- Encrypted loads do not support auto-save. Use ExcelSaveOptions) to persist encrypted changes.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
Returns
Loaded ExcelDocument instance.
public static async Task<ExcelDocument> LoadEncryptedAsync(Stream stream, String password, Boolean readOnly = false, Boolean autoSave = false, OpenSettings openSettings = null, CancellationToken cancellationToken = null) #Task<ExcelDocument>Asynchronously loads a password-encrypted Office Open XML workbook from a stream.
Parameters
- stream System.IO.Stream
- Input stream containing the encrypted workbook.
- password System.String
- Password used to decrypt the workbook package.
- readOnly System.Boolean = false
- Open the decrypted workbook in read-only mode.
- autoSave System.Boolean = false
- Encrypted loads do not support auto-save. Use ExcelSaveOptions) to persist encrypted changes.
- openSettings DocumentFormat.OpenXml.Packaging.OpenSettings = null
- Optional Open XML settings to control how the package is opened.
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
Returns
Loaded ExcelDocument instance.
public ExcelWorksheetMergeResult MergeWorksheets(ExcelSheet targetSheet, ExcelSheet sourceSheet, ExcelWorksheetMergeOptions options = null) #ExcelWorksheetMergeResultMerges source worksheet rows into a target worksheet by appending or writing to a requested target position. This is a workbook operation over worksheet values; callers own any data shaping or relational joins before writing.
Parameters
- targetSheet OfficeIMO.Excel.ExcelSheet
- sourceSheet OfficeIMO.Excel.ExcelSheet
- options OfficeIMO.Excel.ExcelWorksheetMergeOptions = null
MergeWorksheets(OfficeIMO.Excel.ExcelSheet targetSheet, OfficeIMO.Excel.ExcelSheet sourceSheet, OfficeIMO.Excel.ExcelWorksheetMergeOptions options) #Merges source worksheet rows into a target worksheet.
Parameters
- targetSheet OfficeIMO.Excel.ExcelSheet
- sourceSheet OfficeIMO.Excel.ExcelSheet
- options OfficeIMO.Excel.ExcelWorksheetMergeOptions
NormalizeRange(System.String arg1) #Normalizes an A1-style range, ensuring absolute references and validating format. Accepts an optional sheet prefix (e.g. ''Sheet1'!A1:B2'). Throws ArgumentException if the input is not a valid A1 range or cell reference.
Parameters
- arg1 System.String
public Void Open(String filePath = "", Boolean openExcel = true) #VoidOpens the document with the associated application.
Parameters
- filePath System.String = ""
- Optional path to open.
- openExcel System.Boolean = true
- Whether to launch Excel.
public Void PreflightWorkbook() #VoidPerforms a safety preflight across all worksheets to reduce the likelihood of Excel prompting for repairs on open. It removes empty containers (Hyperlinks/MergeCells), drops orphaned drawing and header/footer references, and cleans up invalid table references.
public Void ProtectWorkbook(ExcelWorkbookProtectionOptions options = null) #VoidProtects workbook structure/window metadata. This is not file encryption.
Parameters
- options OfficeIMO.Excel.ExcelWorkbookProtectionOptions = null
public ExcelFluentReadWorkbook Read(ExcelReadOptions options = null) #ExcelFluentReadWorkbookStarts a fluent read pipeline over this open document.
Parameters
- options OfficeIMO.Excel.ExcelReadOptions = null
public Int32 RecalculateSupportedFormulas() #Int32Evaluates supported formulas and writes cached values.
public Boolean RemoveNamedRange(String name, ExcelSheet scope = null, Boolean save = true) #BooleanRemoves a defined name. If scope is provided, removes the sheet‑local name; otherwise the global name.
Parameters
- name System.String
- Defined name to remove.
- scope OfficeIMO.Excel.ExcelSheet = null
- Optional sheet scope.
- save System.Boolean = true
- When true, saves the workbook after removal.
Returns
True if the name existed and was removed; otherwise false.
RemoveReservedTableName(System.String arg1) #Removes the given table name from the cache. Intended for future table deletion APIs. Safe to call even if the cache hasn't been initialized.
Parameters
- arg1 System.String
public Void RemoveWorkSheet(String sheetName) #VoidRemoves a worksheet by name, deleting its part and entry in the workbook.
Parameters
- sheetName System.String
public Void ReorderWorksheet(ExcelSheet sheet, Int32 targetIndex) #VoidReorders a worksheet by name using a zero-based target index.
Parameters
- sheetName System.String
- targetIndex System.Int32
ReorderWorksheet(System.String sheetName, System.Int32 targetIndex) #Reorders a worksheet by name using a zero-based target index.
Parameters
- sheetName System.String
- targetIndex System.Int32
ReorderWorkSheet(OfficeIMO.Excel.ExcelSheet sheet, System.Int32 targetIndex) #Reorders a worksheet using a zero-based target index.
Parameters
- sheet OfficeIMO.Excel.ExcelSheet
- targetIndex System.Int32
ReorderWorksheet(OfficeIMO.Excel.ExcelSheet sheet, System.Int32 targetIndex) #Reorders a worksheet using a zero-based target index.
Parameters
- sheet OfficeIMO.Excel.ExcelSheet
- targetIndex System.Int32
RepairDefinedNames(System.Boolean arg1) #Repairs common issues with defined names that can trigger Excel's file repair, such as duplicates within the same scope, invalid LocalSheetId after sheet reordering/removal, or references containing #REF!.
Parameters
- arg1 System.Boolean
ReserveTableName(System.String arg1) #Adds the given table name to the cache. Should be called once the name is finalized.
Parameters
- arg1 System.String
public Void SafeSave(String filePath = "", Boolean openExcel = false, Boolean writeReportOnIssues = true) #VoidSaves the document and writes an optional OpenXML validation report (sidecar file) next to the saved .xlsx when issues are detected. Useful to diagnose any remaining problems that could cause Excel's repair dialog.
Parameters
- filePath System.String = ""
- Destination path. Empty uses FilePath.
- openExcel System.Boolean = false
- When true, launches the saved file.
- writeReportOnIssues System.Boolean = true
- When true (default), writes .xlsx.validation.txt on issues.
public Void Save(Stream destination, ExcelSaveOptions options) #VoidSaves the document and optionally opens it.
Parameters
- filePath System.String
- Path to save to.
- openExcel System.Boolean
- Whether to open the file after saving.
public Void Save(String filePath, Boolean openExcel, ExcelSaveOptions options) #VoidSaves the document with optional robustness options.
Parameters
- filePath System.String
- Destination path. When empty, uses the original FilePath.
- openExcel System.Boolean
- When true, opens the saved file in the system's associated app.
- options OfficeIMO.Excel.ExcelSaveOptions
- Optional save behaviors (safe defined-name repair, post-save Open XML validation).
public Void Save(Stream destination) #VoidSaves the document and optionally opens it.
Parameters
- openExcel System.Boolean
- Whether to open the file after saving.
Save(System.IO.Stream destination) #Saves the document into a writable stream.
Parameters
- destination System.IO.Stream
- Writable stream that receives the Excel package content.
Save(System.IO.Stream destination, OfficeIMO.Excel.ExcelSaveOptions options) #Saves the document into a writable stream with optional robustness options.
Parameters
- destination System.IO.Stream
- Writable stream that receives the Excel package content.
- options OfficeIMO.Excel.ExcelSaveOptions
- Optional save behaviors (safe defined-name repair, post-save Open XML validation).
public async Task SaveAsync(Stream destination, ExcelSaveOptions options, CancellationToken cancellationToken = null) #TaskAsynchronously saves the document.
Parameters
- filePath System.String
- Optional path to save to.
- openExcel System.Boolean
- Whether to open Excel after saving.
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
Returns
A task representing the asynchronous operation.
public async Task SaveAsync(String filePath, Boolean openExcel, ExcelSaveOptions options, CancellationToken cancellationToken = null) #TaskAsynchronously saves the document with optional robustness options.
Parameters
- filePath System.String
- Destination path. When empty, uses the original FilePath.
- openExcel System.Boolean
- When true, opens the saved file in the system's associated app.
- options OfficeIMO.Excel.ExcelSaveOptions
- Optional save behaviors (safe defined-name repair, post-save Open XML validation).
- cancellationToken System.Threading.CancellationToken = null
- Cancels the asynchronous save work.
public Task SaveAsync(Boolean openExcel, CancellationToken cancellationToken = null) #TaskAsynchronously saves the document into a writable stream.
Parameters
- destination System.IO.Stream
- Writable stream that receives the Excel package content.
- cancellationToken System.Threading.CancellationToken = null
- Cancels the asynchronous save work.
SaveAsync(System.IO.Stream destination, OfficeIMO.Excel.ExcelSaveOptions options, System.Threading.CancellationToken cancellationToken) #Asynchronously saves the document into a writable stream with optional robustness options.
Parameters
- destination System.IO.Stream
- Writable stream that receives the Excel package content.
- options OfficeIMO.Excel.ExcelSaveOptions
- Optional save behaviors (safe defined-name repair, post-save Open XML validation).
- cancellationToken System.Threading.CancellationToken
- Cancels the asynchronous save work.
public Task SaveAsync(CancellationToken cancellationToken = null) #TaskAsynchronously saves the document.
Parameters
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
SaveAsync(System.Boolean openExcel, System.Threading.CancellationToken cancellationToken) #Asynchronously saves the document and optionally opens Excel.
Parameters
- openExcel System.Boolean
- Whether to open Excel after saving.
- cancellationToken System.Threading.CancellationToken
- Cancellation token.
public Void SaveEncrypted(String filePath, String password, Boolean openExcel = false, ExcelSaveOptions saveOptions = null) #VoidSaves the workbook as a password-encrypted Office Open XML package.
Parameters
- filePath System.String
- Destination path. When empty, uses the original FilePath.
- password System.String
- Password used to encrypt the workbook package.
- openExcel System.Boolean = false
- When true, opens the saved file in the system's associated app.
- saveOptions OfficeIMO.Excel.ExcelSaveOptions = null
- Optional save behaviors (safe defined-name repair, post-save Open XML validation).
public Void SaveEncrypted(Stream destination, String password, ExcelSaveOptions saveOptions = null) #VoidSaves the workbook as a password-encrypted Office Open XML package to a stream.
Parameters
- destination System.IO.Stream
- Writable stream that receives the encrypted workbook.
- password System.String
- Password used to encrypt the workbook package.
- saveOptions OfficeIMO.Excel.ExcelSaveOptions = null
- Optional save behaviors (safe defined-name repair, post-save Open XML validation).
public Void SetNamedRange(String name, String range, ExcelSheet scope = null, Boolean save = true, Boolean hidden = false, NameValidationMode validationMode = Sanitize) #VoidCreates or updates a defined name pointing to an A1 range. When scope is provided, the name is local to that sheet; otherwise it is workbook‑global.
Parameters
- name System.String
- Defined name to create or update.
- range System.String
- A1 range (e.g. "A1:B10"). Can include a sheet prefix.
- scope OfficeIMO.Excel.ExcelSheet = null
- Optional sheet scope for a local name.
- save System.Boolean = true
- When true, saves the workbook after the change.
- hidden System.Boolean = false
- When true, marks the defined name as hidden.
- validationMode OfficeIMO.Excel.NameValidationMode = Sanitize
- Controls how the name and range are validated: Sanitize (default) clamps/adjusts; Strict throws on invalid input.
public Void SetPrintArea(ExcelSheet sheet, String range, Boolean save = true) #VoidSets the print area for a given sheet by creating a sheet-local defined name _xlnm.Print_Area.
Parameters
- sheet OfficeIMO.Excel.ExcelSheet
- range System.String
- save System.Boolean = true
public Void SetPrintTitles(ExcelSheet sheet, Nullable<Int32> firstRow, Nullable<Int32> lastRow, Nullable<Int32> firstCol, Nullable<Int32> lastCol, Boolean save = true) #VoidSets rows/columns to repeat at top/left when printing a specific sheet by creating a sheet-local defined name _xlnm.Print_Titles. Pass nulls to clear existing print titles.
Parameters
- sheet OfficeIMO.Excel.ExcelSheet
- Target sheet.
- firstRow System.Nullable{System.Int32}
- First row to repeat (1-based), or null.
- lastRow System.Nullable{System.Int32}
- Last row to repeat (1-based), or null.
- firstCol System.Nullable{System.Int32}
- First column to repeat (1-based), or null.
- lastCol System.Nullable{System.Int32}
- Last column to repeat (1-based), or null.
- save System.Boolean = true
- Whether to save the workbook after the change.
TryGetDirectTabularSaveCandidateRange(OfficeIMO.Excel.ExcelSheet sheet, System.String@ range) #Returns the pending used range for a clean direct-tabular save candidate before the package is materialized.
Parameters
- sheet OfficeIMO.Excel.ExcelSheet
- Worksheet whose pending direct-tabular range should be reported.
- range System.String@
- The candidate worksheet range in A1 notation when available.
Returns
true when the workbook has a valid single-sheet direct-tabular candidate for the worksheet.
public Boolean TryGetSheet(String name, out ExcelSheet sheet) #BooleanTries to get a worksheet by name.
Parameters
- name System.String
- sheet OfficeIMO.Excel.ExcelSheet@
public Void UnprotectWorkbook() #VoidRemoves workbook-level structure/window protection metadata.
public List<ValidationErrorInfo> ValidateDocument(FileFormatVersions fileFormatVersions = Microsoft365) #List<ValidationErrorInfo>Validates the document using the specified file format version.
Parameters
- fileFormatVersions DocumentFormat.OpenXml.FileFormatVersions = Microsoft365
- File format version to validate against.
Returns
List of validation errors.
public IReadOnlyList<String> ValidateOpenXml() #IReadOnlyList<String>Validates the current spreadsheet with Open XML validator and returns error messages (if any). Useful for troubleshooting "Repaired Records" issues in Excel.
public static IReadOnlyList<ExcelDataSetImportResult> WriteDataSet(Stream stream, DataSet dataSet, TableStyle tableStyle = TableStyleMedium2, Boolean includeHeaders = true, Boolean includeAutoFilter = true, CancellationToken ct = null) #IReadOnlyList<ExcelDataSetImportResult>Writes a DataSet directly to an XLSX package, using one worksheet and one Excel table per DataTable. This path is intended for export workloads where the caller does not need to keep editing the workbook object.
Parameters
- stream System.IO.Stream
- dataSet System.Data.DataSet
- tableStyle OfficeIMO.Excel.TableStyle = TableStyleMedium2
- includeHeaders System.Boolean = true
- includeAutoFilter System.Boolean = true
- ct System.Threading.CancellationToken = null
Inherited Methods
public override Boolean Equals(Object obj) #BooleanParameters
- obj Object
Properties
public ExcelCalculationOptions Calculation { get; } #Formula calculation and cached-result policy used during save.
public Boolean IsWorkbookProtected { get; } #Returns true when workbook-level structure or window protection is present.
public Boolean SheetCachingEnabled { get; set; } #Enables caching of ExcelSheet wrappers for faster repeat access at the cost of higher memory usage. Set to false to avoid holding references to every sheet in very large workbooks.
public IEqualityComparer<String> TableNameComparer { get; set; } #Controls how workbook-level table name uniqueness is compared. Defaults to OrdinalIgnoreCase. Changing this will reset the internal cache and rebuild it on next use. Set it once before adding tables for predictable behavior.
public ExcelChartStylePreset DefaultChartStylePreset { get; set; } #Optional default chart style preset applied to charts created in this workbook.
public ExecutionPolicy Execution { get; } #Execution policy for controlling parallel vs sequential operations.
public Func<DateTimeOffset, DateTime> DateTimeOffsetWriteStrategy { get; set; } #Controls how DateTimeOffset values are converted to DateTime before being written to worksheet cells. Defaults to LocalDateTime.
public List<ExcelSheet> Sheets { get; } #Gets a list of worksheets contained in the document.
public ExcelSaveDiagnostics LastSaveDiagnostics { get; set; } #Diagnostics for the most recent save operation.
public FileAccess FileOpenAccess { get; } #FileOpenAccess of the document
public Boolean DocumentIsValid { get; } #Indicates whether the document is valid.
public List<ValidationErrorInfo> DocumentValidationErrors { get; } #Gets the list of validation errors for the document.
public ExcelSheet Item { get; } #Gets a worksheet by name (case-insensitive).
Item #Gets a worksheet by 0-based index in workbook order.
Fields
public SpreadsheetDocument _spreadSheetDocument #Underlying Open XML spreadsheet document instance.
public String FilePath #Path to the file backing this document.
public BuiltinDocumentProperties BuiltinDocumentProperties #Built-in (core) document properties (Title, Creator, etc.).
public ApplicationProperties ApplicationProperties #Extended (application) properties (Company, Manager, etc.).
Extension Methods
public static ExcelSheet GetOrCreateSheet(ExcelDocument document, String name, SheetNameValidationMode validationMode) #ExcelSheetReturns the named sheet if it exists, otherwise creates it; falls back to the last sheet.
Parameters
- document OfficeIMO.Excel.ExcelDocument
- name System.String
- validationMode OfficeIMO.Excel.SheetNameValidationMode