Class XlsxFormat
- Namespace
- DocToolkit
- Assembly
- DocToolkit.Xlsx.dll
The presentation Format(byte[], string, XlsxFormat) applies to a sheet: a bold header row, a freeze position, auto-fitted or explicit column widths, a number format per column, an autofilter, conditional formats and data validations.
public sealed class XlsxFormat- Inheritance
-
XlsxFormat
- Inherited Members
Remarks
The boundary here is a CLOSED vocabulary, not a small one — and that is a change. This type used to say the smallness was the design, and excluded conditional rules by name. It was reversed deliberately on 2026-08-26, because "small" stops being a boundary the moment anything is added, while "closed" survives the question.
| in | out |
|---|---|
| a vocabulary this library can enumerate, measure and guarantee — six rule conditions, five validation kinds, four highlights, a freeze position, a column width | an open one it would have to own forever — arbitrary fonts, borders, fills, merged ranges, colour scales, icon sets |
XlsxHighlight is the test case for that line: four named intents can be enumerated and guaranteed, a colour picker cannot. If what you need cannot be expressed as a closed set, the original answer still stands — use ClosedXML directly rather than have this package grow a second, worse styling API in front of it.
Immutable, with With… methods returning a new instance — the same shape as
PageSetup.
Properties
AutoFilter
Whether the sheet's used range carries an autofilter.
public bool AutoFilter { get; }Property Value
Remarks
A sheet with no data has no used range, so it gets no filter rather than an error.
AutoFitColumns
Whether each column is widened to fit its contents.
public bool AutoFitColumns { get; }Property Value
BoldHeaderRow
Whether the first row is bold.
public bool BoldHeaderRow { get; }Property Value
ColumnNumberFormats
Number formats by column letter — "B" to "#,##0.00", for instance. Empty
unless set.
public IReadOnlyDictionary<string, string> ColumnNumberFormats { get; }Property Value
Remarks
Keyed by column letter rather than index, because that is how a spreadsheet's user
refers to a column and how ReadCell(byte[], string, string)
already addresses cells. Case-insensitive: "b" and "B" are the same column.
The strings are Excel's own number-format codes, passed through unaltered. DocToolkit does not validate or translate them — inventing a format language in front of a standard one would be a second thing to learn and a second thing to get wrong.
ColumnWidths
An explicit width per column letter. Empty unless set.
public IReadOnlyDictionary<string, double> ColumnWidths { get; }Property Value
Remarks
Applied after AutoFitColumns, so a named column takes this width while the rest stay auto-fitted. A specific instruction beats a blanket one.
FreezeAt
Where the sheet is frozen, or null if it is not.
public XlsxFreeze? FreezeAt { get; }Property Value
FreezeHeaderRow
Whether the first row stays visible while the rest of the sheet scrolls.
public bool FreezeHeaderRow { get; }Property Value
Remarks
Derived from FreezeAt rather than stored, so the two cannot disagree. Freezing anywhere else makes this false, which is the honest answer rather than a stale one.
None
Applies nothing. The starting point for building a format up.
public static XlsxFormat None { get; }Property Value
Report
The three settings that make a generated sheet readable: a bold header row, that row frozen so it stays visible while scrolling, and columns wide enough to show their contents.
public static XlsxFormat Report { get; }Property Value
Remarks
A preset rather than three calls because it is the answer to the question people actually have — "make this look like a report" — and because leaving it out would mean every caller rediscovering the same three settings.
Rules
The conditional formats to apply, in the order given. Empty unless set.
public IReadOnlyList<XlsxRule> Rules { get; }Property Value
Validations
The data validations to apply, in the order given. Empty unless set.
public IReadOnlyList<XlsxValidation> Validations { get; }Property Value
Remarks
Overlapping ranges are consolidated by the library beneath, and the LATER one wins.
Measured: a whole-number validation on B2:B10 followed by a list on B5:B15
leaves the first covering only B2:B4; the same range twice leaves only the second.
Rules does not behave this way — six conditional formats over two ranges
stay six — so do not reason from one to the other.
Methods
WithAutoFilter(bool)
Returns a copy that puts an autofilter on the sheet's used range.
public XlsxFormat WithAutoFilter(bool enabled = true)Parameters
enabledboolWhether to apply one.
Returns
WithAutoFitColumns(bool)
Returns a copy with AutoFitColumns set.
public XlsxFormat WithAutoFitColumns(bool autoFit = true)Parameters
autoFitboolWhether each column is widened to fit its contents.
Returns
WithBoldHeaderRow(bool)
Returns a copy with BoldHeaderRow set.
public XlsxFormat WithBoldHeaderRow(bool bold = true)Parameters
boldboolWhether the first row is bold.
Returns
WithColumnWidth(string, double)
Returns a copy that gives column an explicit width.
public XlsxFormat WithColumnWidth(string column, double width)Parameters
columnstringA column letter, such as
"A". Case-insensitive.widthdoubleThe width in Excel's character units. Must be positive.
Returns
Remarks
Applied after AutoFitColumns, so this wins for the column it names while the rest stay auto-fitted.
Exceptions
- ArgumentNullException
columnis null.- ArgumentException
columnis not one or more letters.- ArgumentOutOfRangeException
widthis not positive.
WithFreezeAt(int, int)
Returns a copy frozen at a position.
public XlsxFormat WithFreezeAt(int row, int column)Parameters
Returns
Remarks
(0, 0) is refused: it would freeze nothing while making FreezeAt report a
value, which is two spellings of one state. Use WithFrozenHeaderRow(bool) with false
to freeze nothing. Rows-only and columns-only are both legal.
Exceptions
- ArgumentOutOfRangeException
Either is negative, or both are zero.
WithFrozenHeaderRow(bool)
Returns a copy that freezes row 1, or that freezes nothing.
public XlsxFormat WithFrozenHeaderRow(bool frozen = true)Parameters
frozenboolWhether to freeze row 1.
Returns
Remarks
frozen false clears whatever freeze is set, not only a header-row
one — the state is a single position rather than two independent switches, and a method that
did something different depending on the current value would be worse than one that is blunt
about it.
WithNumberFormat(string, string)
Returns a copy that formats column with numberFormat.
public XlsxFormat WithNumberFormat(string column, string numberFormat)Parameters
columnstringA column letter, such as
"B". Case-insensitive.numberFormatstringAn Excel number-format code, such as
"#,##0.00"or"yyyy-mm-dd".
Returns
Exceptions
- ArgumentNullException
Either argument is null.
- ArgumentException
columnis not one or more letters, ornumberFormatis blank. Checked here rather than at apply time so a typo fails where it was written.
WithRule(XlsxRule)
Returns a copy carrying one more conditional format.
public XlsxFormat WithRule(XlsxRule rule)Parameters
ruleXlsxRuleThe rule to add.
Returns
Exceptions
- ArgumentNullException
ruleis null.
WithValidation(XlsxValidation)
Returns a copy carrying one more data validation.
public XlsxFormat WithValidation(XlsxValidation validation)Parameters
validationXlsxValidationThe validation to add.
Returns
Exceptions
- ArgumentNullException
validationis null.