SpreadCheetah

https://github.com/sveinungf/spreadcheetah
Admin
SpreadCheetah is a high-performance .NET library for generating spreadsheet (Microsoft Excel XLSX)...
Tokens:10,126
Snippets:106
Trust Score:7.9
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install SpreadCheetah via .NET CLI

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

Use this command to add the SpreadCheetah package to your .NET project.

```bash
dotnet add package SpreadCheetah
```

--------------------------------

### Install SpreadCheetah via Package Manager

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

Use this command in the NuGet Package Manager console to add the library.

```powershell
Install-Package SpreadCheetah
```

--------------------------------

### Define mixed explicit and implicit column order

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Properties without the ColumnOrder attribute receive an implicit value based on the lowest available positive integer. This example results in FirstName (1), Age (2), and LastName (10).

```csharp
public class Person
{
    [ColumnOrder(10)]
    public string LastName { get; set; }

    [ColumnOrder(1)]
    public string FirstName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### Create a basic spreadsheet

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

Demonstrates initializing a spreadsheet, adding a worksheet, inserting a row of cells, and finalizing the file. Ensure FinishAsync is called before disposal to correctly generate the XLSX file.

```csharp
using (var spreadsheet = await Spreadsheet.CreateNewAsync(stream))
{
    // A spreadsheet must contain at least one worksheet.
    await spreadsheet.StartWorksheetAsync("Sheet 1");

    // Cells are inserted row by row.
    var row = new List<Cell>
    {
        new Cell("Answer to the ultimate question:"),
        new Cell(42)
    };

    // Rows are inserted from top to bottom.
    await spreadsheet.AddRowAsync(row);

    // Remember to call Finish before disposing.
    // This is important to properly finalize the XLSX file.
    await spreadsheet.FinishAsync();
}
```

--------------------------------

### Create a basic table in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Tables

Initializes a new spreadsheet and adds a basic table with defined column widths and data rows.

```cs
await using var outputStream = File.Create("table-basic.xlsx");
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);

var worksheetOptions = new WorksheetOptions();
worksheetOptions.Column(2).Width = 18;
await spreadsheet.StartWorksheetAsync("Sheet", worksheetOptions);

var table = new Table(TableStyle.Light9);
spreadsheet.StartTable(table);

string[] headerNames = ["City", "Temperature (°C)"];
DataCell[] paris = [new DataCell("Paris"), new DataCell(14)];
DataCell[] bangkok = [new DataCell("Bangkok"), new DataCell(34)];

await spreadsheet.AddHeaderRowAsync(headerNames);
await spreadsheet.AddRowAsync(paris);
await spreadsheet.AddRowAsync(bangkok);

await spreadsheet.FinishAsync();
```

--------------------------------

### Grouping Rows in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Row-grouping

Demonstrates how to apply outline levels to rows and configure the worksheet for grouping.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);

// While not strictly required, it's recommended to also set the MaxRowOutlineLevel when using row grouping.
var worksheetOptions = new WorksheetOptions { MaxRowOutlineLevel = 2 };

await spreadsheet.StartWorksheetAsync("Sheet 1", worksheetOptions);

var group1Options = new RowOptions { OutlineLevel = 1 };
var group2Options = new RowOptions { OutlineLevel = 2 };

await spreadsheet.AddRowAsync([new Cell(10)]);
await spreadsheet.AddRowAsync([new Cell(20)], group1Options);
await spreadsheet.AddRowAsync([new Cell(30)], group2Options);
await spreadsheet.AddRowAsync([new Cell(40)], group2Options);
await spreadsheet.AddRowAsync([new Cell(50)]);

await spreadsheet.FinishAsync();
```

--------------------------------

### Create a table with a total row in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Tables

Configures a table to include a total row with an average function applied to a specific column.

```cs
await using var outputStream = File.Create("table-total-row.xlsx");
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);

var worksheetOptions = new WorksheetOptions();
worksheetOptions.Column(2).Width = 18;
await spreadsheet.StartWorksheetAsync("Sheet", worksheetOptions);

var table = new Table(TableStyle.Medium3);
table.Column(1).TotalRowLabel = "Average";
table.Column(2).TotalRowFunction = TableTotalRowFunction.Average;
spreadsheet.StartTable(table);

string[] headerNames = ["City", "Temperature (°C)"];
DataCell[] paris = [new DataCell("Paris"), new DataCell(14)];
DataCell[] bangkok = [new DataCell("Bangkok"), new DataCell(34)];

await spreadsheet.AddHeaderRowAsync(headerNames);
await spreadsheet.AddRowAsync(paris);
await spreadsheet.AddRowAsync(bangkok);

await spreadsheet.FinishAsync();
```

--------------------------------

### Infer column headers with prefix

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Applies a prefix to the resource key lookup for all properties in the class.

```csharp
[InferColumnHeaders(typeof(MyResources), Prefix = "Header_")]
public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### Create a table with a calculated column in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Tables

Uses Open XML formula syntax to create a calculated column within a table.

```cs
await using var outputStream = File.Create("table-calculated-column.xlsx");
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);

var worksheetOptions = new WorksheetOptions();
worksheetOptions.Column(1).Width = 18;
await spreadsheet.StartWorksheetAsync("Sheet", worksheetOptions);

var table = new Table(TableStyle.Medium4, "MyProductTable");
spreadsheet.StartTable(table);

string[] headerNames = ["Product", "Qtr 1", "Qtr 2", "Total"];
var grandTotalFormula = new Formula("SUM(MyProductTable[[#This Row],[Qtr 1]:[Qtr 2]])");
Cell[] chocolate = [new("Chocolate"), new(744), new(162), new Cell(grandTotalFormula)];
Cell[] tomatoes = [new("Tomatoes"), new(345), new(377), new Cell(grandTotalFormula)];

await spreadsheet.AddHeaderRowAsync(headerNames);
await spreadsheet.AddRowAsync(chocolate);
await spreadsheet.AddRowAsync(tomatoes);

await spreadsheet.FinishAsync();
```

--------------------------------

### Configure the source generator context

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

Create a partial class inheriting from WorksheetRowContext and annotate it with WorksheetRowAttribute to trigger code generation.

```csharp
using SpreadCheetah.SourceGeneration;

namespace MyNamespace;

[WorksheetRow(typeof(MyObject))]
public partial class MyObjectRowContext : WorksheetRowContext;
```

--------------------------------

### Create multiple tables in a single worksheet in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Tables

Demonstrates how to add multiple tables to one worksheet by calling FinishTableAsync between them.

```cs
await using var outputStream = File.Create("table-multiple.xlsx");
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);

var worksheetOptions = new WorksheetOptions();
worksheetOptions.Column(2).Width = 18;
await spreadsheet.StartWorksheetAsync("Sheet", worksheetOptions);

string[] headerNames = ["City", "Temperature (°C)"];

var table1 = new Table(TableStyle.Dark5);
spreadsheet.StartTable(table1);
await spreadsheet.AddHeaderRowAsync(headerNames);
await spreadsheet.AddRowAsync([new DataCell("Paris"), new DataCell(14)]);
await spreadsheet.AddRowAsync([new DataCell("Bangkok"), new DataCell(34)]);
await spreadsheet.FinishTableAsync();

await spreadsheet.AddRowAsync([]);

var table2 = new Table(TableStyle.Dark6);
spreadsheet.StartTable(table2);
await spreadsheet.AddHeaderRowAsync(headerNames);
await spreadsheet.AddRowAsync([new DataCell("Dakar"), new DataCell(21)]);
await spreadsheet.AddRowAsync([new DataCell("Lima"), new DataCell(24)]);
await spreadsheet.FinishTableAsync();

await spreadsheet.FinishAsync();
```

--------------------------------

### Reference resource files for localized headers

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Demonstrates using the ColumnHeader attribute to reference public static properties or resource files for localized header names.

```csharp
public class Person
{
    [ColumnHeader(typeof(MyResources), nameof(MyResources.Header_FirstName)]
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### Add a header row using the source generator

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Demonstrates using AddHeaderRowAsync to generate a header row based on a metadata type with an optional style.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var style = new Style { Font = { Bold = true } };
var styleId = spreadsheet.AddStyle(style);

// This adds a row of header names generated by the source generator
await spreadsheet.AddHeaderRowAsync(PersonContext.Default.Person, styleId);

await spreadsheet.FinishAsync();
```

--------------------------------

### Apply Metadata to Worksheet

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Methods for applying column width metadata when initializing a worksheet.

```csharp
// Option 1: Pass the metadata type to StartWorksheetAsync.
await spreadsheet.StartWorksheetAsync("Sheet", PersonContext.Default.Person);
```

```csharp
// Option 2: Create an instance of WorksheetOptions from the metadata type.
var options = PersonContext.Default.Person.CreateWorksheetOptions();

// Can now set additional options, for example frozen columns.
options.FrozenColumns = 1;

// Pass the instance to StartWorksheetAsync.
await spreadsheet.StartWorksheetAsync("Sheet", options);
```

--------------------------------

### Add objects as rows to a spreadsheet

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

Use the generated context to add objects as rows to a spreadsheet asynchronously.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var myObj = new MyObject
{
    Question = "How many Rings of Power were there?",
    Answer = 20
};

await spreadsheet.AddAsRowAsync(myObj, MyObjectRowContext.Default.MyObject);

await spreadsheet.FinishAsync();
```

--------------------------------

### Infer column headers from resource keys

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Automatically maps property names to resource keys in the specified resource class.

```csharp
[InferColumnHeaders(typeof(MyResources))]
public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### Apply a style to a specific cell

Source: https://github.com/sveinungf/spreadcheetah/wiki/Styling

Create a Style object, register it with the spreadsheet to obtain a StyleId, and pass that ID to the Cell constructor.

```csharp
var style = new Style();
style.Fill.Color = Color.Yellow;
style.Font.Bold = true;

await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var styleId = spreadsheet.AddStyle(style);

var cell = new Cell("My styled cell", styleId);
await spreadsheet.AddRowAsync([cell]);

await spreadsheet.FinishAsync();
```

--------------------------------

### Embed and add an image to a worksheet

Source: https://github.com/sveinungf/spreadcheetah/wiki/Adding-an-embedded-image

Demonstrates the full workflow of embedding an image stream and placing it into a worksheet at a specific cell location.

```cs
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);
var embeddedImage = await spreadsheet.EmbedImageAsync(imageStream);
await spreadsheet.StartWorksheetAsync("Sheet");

var canvas = ImageCanvas.OriginalSize("B3");
spreadsheet.AddImage(canvas, embeddedImage);

await spreadsheet.FinishAsync();
```

--------------------------------

### Define a C# class for worksheet rows

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Create a standard C# class to represent the data structure that will be mapped to worksheet rows.

```csharp
namespace MyNamespace;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
}
```

--------------------------------

### Apply styles to table cells and total rows in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Tables

Configures table column options for total rows and applies custom styles to individual cells within a worksheet.

```csharp
await using var outputStream = File.Create("table-total-row.xlsx");
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);

var worksheetOptions = new WorksheetOptions();
worksheetOptions.Column(2).Width = 18;
await spreadsheet.StartWorksheetAsync("Sheet", worksheetOptions);

var table = new Table(TableStyle.Medium3);
table.Column(1).TotalRowLabel = "Average";
table.Column(2).TotalRowFunction = TableTotalRowFunction.Average;
table.Column(2).TotalRowStyle = new Style { Fill = { Color = Color.Red } };
spreadsheet.StartTable(table);

var greenStyle = new Style { Fill = { Color = Color.Green } };
var greenStyleId = spreadsheet.AddStyle(greenStyle);

string[] headerNames = ["City", "Temperature (°C)"];
Cell[] paris = [new Cell("Paris"), new Cell(14, greenStyleId)];
Cell[] bangkok = [new Cell("Bangkok"), new Cell(34, greenStyleId)];

await spreadsheet.AddHeaderRowAsync(headerNames);
await spreadsheet.AddRowAsync(paris);
await spreadsheet.AddRowAsync(bangkok);

await spreadsheet.FinishAsync();
```

--------------------------------

### ImageCanvas

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet10_0.verified.txt

Provides static factory methods to define how an image is placed and sized within a worksheet.

```APIDOC
## ImageCanvas

### Description
Defines the positioning and sizing behavior for images in a spreadsheet.

### Methods
- **Dimensions(ReadOnlySpan<char> upperLeftReference, int width, int height, bool moveWithCells)**: Sets specific dimensions for the image.
- **FillCell(ReadOnlySpan<char> cellReference, bool moveWithCells, bool resizeWithCells)**: Fits the image to a single cell.
- **FillCells(ReadOnlySpan<char> upperLeftReference, ReadOnlySpan<char> lowerRightReference, bool moveWithCells, bool resizeWithCells)**: Stretches the image across a range of cells.
- **OriginalSize(ReadOnlySpan<char> upperLeftReference, bool moveWithCells)**: Places the image at its original size.
- **Scaled(ReadOnlySpan<char> upperLeftReference, float scale, bool moveWithCells)**: Places the image scaled by a factor.
```

--------------------------------

### Apply Unique Values Conditional Formatting in C#

Source: https://github.com/sveinungf/spreadcheetah/wiki/Conditional-formatting

Demonstrates creating a unique values rule with a yellow fill style and applying it to a specific cell range.

```csharp
await using var outputStream = File.Create("conditional-formatting.xlsx");
await using var spreadsheet = await Spreadsheet.CreateNewAsync(outputStream);

await spreadsheet.StartWorksheetAsync("Sheet");

var style = new ConditionalFormatStyle { Fill = { Color = Color.Yellow } };
var rule = ConditionalFormatRule.UniqueValues().WithStyle(style);

const string cellRange = "A1:E1";
spreadsheet.AddConditionalFormatRule(cellRange, rule);

DataCell[] row = [new(1), new(2), new(3), new(3), new(1)];
await spreadsheet.AddRowAsync(row);

await spreadsheet.FinishAsync();
```

--------------------------------

### Define Column Width with Attributes

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Apply the ColumnWidth attribute to class properties to set specific column widths in Excel.

```csharp
public class Person
{
    [ColumnWidth(20)]
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### TryGetColumnNameUtf8(int columnNumber, Span<byte> destination, out int bytesWritten)

Source: https://github.com/sveinungf/spreadcheetah/wiki/Utility-methods

Converts a 1-based column number to a UTF-8 encoded column name written directly into a provided Span.

```APIDOC
## bool TryGetColumnNameUtf8(int columnNumber, Span<byte> destination, out int bytesWritten)

### Description
Writes the UTF-8 representation of a column name into the provided destination span to avoid allocations.

### Parameters
- **columnNumber** (int) - Required - The 1-based column number to convert.
- **destination** (Span<byte>) - Required - The buffer to write the UTF-8 column name into.
- **bytesWritten** (out int) - Required - The number of bytes written to the destination.

### Returns
- **bool** - Returns true if the operation was successful.
```

--------------------------------

### Add rows using the generated metadata

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Use the generated metadata from the context class to add instances of the type to a spreadsheet.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var person = new Person
{
    FirstName = "Ola",
    LastName = "Nordmann"
};

// Here the metadata type is passed as the second argument.
// This will in turn use the code generated by the source generator.
await spreadsheet.AddAsRowAsync(person, PersonContext.Default.Person);

await spreadsheet.FinishAsync();
```

--------------------------------

### SpreadCheetah.Validations.DataValidation

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet10_0.verified.txt

Provides static factory methods to create various data validation rules for spreadsheet cells.

```APIDOC
## DataValidation Static Methods

### Description
Factory methods to create validation rules for Date/Time and Decimal values.

### Methods
- **DateTimeBetween(DateTime min, DateTime max)** - Creates a validation rule for dates within a range.
- **DateTimeEqualTo(DateTime value)** - Creates a validation rule for a specific date.
- **DecimalBetween(double min, double max)** - Creates a validation rule for decimal values within a range.
- **DecimalEqualTo(double value)** - Creates a validation rule for a specific decimal value.

### Properties
- **ErrorMessage** (string?) - The message displayed when validation fails.
- **ErrorTitle** (string?) - The title of the error alert box.
- **ErrorType** (ValidationErrorType) - The type of error alert (e.g., Stop, Warning, Information).
```

--------------------------------

### Formula.Hyperlink

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet8_0.verified.txt

Creates a hyperlink formula for use in spreadsheet cells.

```APIDOC
## Formula.Hyperlink

### Description
Creates a new Formula instance representing a hyperlink.

### Parameters
- **uri** (Uri) - Required - The target URI.
- **friendlyName** (string) - Optional - The display text for the hyperlink.
```

--------------------------------

### Source Generation Attributes

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet10_0.verified.txt

Attributes used to configure spreadsheet generation from classes.

```APIDOC
## Source Generation Attributes

### Description
Attributes applied to class properties to control how they are exported to spreadsheet columns.

### Attributes
- **CellFormatAttribute**: Defines number formatting for a cell.
- **CellStyleAttribute**: Applies a named style to a cell.
- **CellValueConverterAttribute**: Specifies a custom converter for cell values.
- **CellValueTruncateAttribute**: Truncates string values to a specific length.
- **ColumnHeaderAttribute**: Sets a custom header name for a column.
- **ColumnIgnoreAttribute**: Excludes a property from the generated spreadsheet.
- **ColumnOrderAttribute**: Defines the order of the column.
- **ColumnWidthAttribute**: Sets the width of a specific column.
- **DefaultColumnWidthAttribute**: Sets the default width for all columns in the class.
```

--------------------------------

### Configure the default font

Source: https://github.com/sveinungf/spreadcheetah/wiki/Styling

Set the DefaultFont property within SpreadCheetahOptions when initializing the spreadsheet.

```csharp
var defaultFont = new DefaultFont
{
    Name = "Consolas",
    Size = 14
};

var options = new SpreadCheetahOptions { DefaultFont = defaultFont };

await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream, options);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var cell = new Cell("My cell value");
await spreadsheet.AddRowAsync([cell]);

await spreadsheet.FinishAsync();
```

--------------------------------

### Auto-generated Worksheet Row Metadata Context

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.SourceGenerator.SnapshotTest/Snapshots/G.Caching_IncrementalSourceGeneratorCachingCorrectly.verified.txt

This class provides the necessary infrastructure for source-generated spreadsheet row serialization, including header row creation and row-by-row data insertion.

```csharp
// <auto-generated />
#nullable enable
using SpreadCheetah;
using SpreadCheetah.SourceGeneration;
using SpreadCheetah.Styling;
using System;
using System.Buffers;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace MyNamespace
{
    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("SpreadCheetah.SourceGenerator", "1.0.0")]
    public partial class MyContext
    {
        private static MyContext? _default;

        /// <summary>The default context instance.</summary>
        public static MyContext Default => _default ??= new MyContext();

        /// <inheritdoc/>
        public MyContext()
        {
        }

        private WorksheetRowTypeInfo<MyNamespace.MyRecord>? _MyRecord;

        /// <summary>
        /// Defines the source generated worksheet row metadata for a given type.
        /// </summary>
        public WorksheetRowTypeInfo<MyNamespace.MyRecord> MyRecord => _MyRecord
            ??= WorksheetRowMetadataServices.CreateObjectInfo<MyNamespace.MyRecord>(
                AddHeaderRow0Async, AddAsRowAsync, AddRangeAsRowsAsync, null);

        private static async ValueTask AddHeaderRow0Async(SpreadCheetah.Spreadsheet spreadsheet, SpreadCheetah.Styling.StyleId? styleId, CancellationToken token)
        {
            var headerNames = ArrayPool<string?>.Shared.Rent(1);
            try
            {
                headerNames[0] = "Name";
                await spreadsheet.AddHeaderRowAsync(headerNames.AsMemory(0, 1)!, styleId, token).ConfigureAwait(false);
            }
            finally
            {
                ArrayPool<string?>.Shared.Return(headerNames, true);
            }
        }

        private static ValueTask AddAsRowAsync(SpreadCheetah.Spreadsheet spreadsheet, MyNamespace.MyRecord? obj, CancellationToken token)
        {
            if (spreadsheet is null)
                throw new ArgumentNullException(nameof(spreadsheet));
            if (obj is null)
                return spreadsheet.AddRowAsync(ReadOnlyMemory<DataCell>.Empty, token);
            return AddAsRowInternalAsync(spreadsheet, obj, token);
        }

        private static ValueTask AddRangeAsRowsAsync(SpreadCheetah.Spreadsheet spreadsheet,
            IEnumerable<MyNamespace.MyRecord?> objs,
            CancellationToken token)
        {
            if (spreadsheet is null)
                throw new ArgumentNullException(nameof(spreadsheet));
            if (objs is null)
                throw new ArgumentNullException(nameof(objs));
            return AddRangeAsRowsInternalAsync(spreadsheet, objs, token);
        }

        private static async ValueTask AddAsRowInternalAsync(SpreadCheetah.Spreadsheet spreadsheet,
            MyNamespace.MyRecord obj,
            CancellationToken token)
        {
            var cells = ArrayPool<DataCell>.Shared.Rent(1);
            try
            {
                var styleIds = Array.Empty<StyleId>();
                await AddCellsAsRowAsync(spreadsheet, obj, cells, styleIds, token).ConfigureAwait(false);
            }
            finally
            {
                ArrayPool<DataCell>.Shared.Return(cells, true);
            }
        }

        private static async ValueTask AddRangeAsRowsInternalAsync(SpreadCheetah.Spreadsheet spreadsheet,
            IEnumerable<MyNamespace.MyRecord?> objs,
            CancellationToken token)
        {
            var cells = ArrayPool<DataCell>.Shared.Rent(1);
            try
            {
                var styleIds = Array.Empty<StyleId>();
                foreach (var obj in objs)
                {
                    await AddCellsAsRowAsync(spreadsheet, obj, cells, styleIds, token).ConfigureAwait(false);
                }
            }
            finally
            {
                ArrayPool<DataCell>.Shared.Return(cells, true);
            }
        }

        private static ValueTask AddCellsAsRowAsync(SpreadCheetah.Spreadsheet spreadsheet,
            MyNamespace.MyRecord? obj,
            DataCell[] cells, IReadOnlyList<StyleId> styleIds, CancellationToken token)
        {
            if (obj is null)
                return spreadsheet.AddRowAsync(ReadOnlyMemory<DataCell>.Empty, token);

            cells[0] = new DataCell(obj.Name);
            return spreadsheet.AddRowAsync(cells.AsMemory(0, 1), token);
        }
    }
}
```

--------------------------------

### Convert property values with CellValueConverter

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Implement CellValueConverter to define custom mapping logic for properties, such as handling null values or custom types.

```csharp
public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    [CellValueConverter(typeof(AgeConverter))]
    public int? Age { get; set; }
}

public class AgeConverter : CellValueConverter<int?>
{
    public override DataCell ConvertToDataCell(int? age)
    {
        return age is null
            ? new DataCell("N/A")
            : new DataCell(age.Value);
    }
}
```

```csharp
public record Name(string Value);

public class Person
{
    [CellValueConverter(typeof(NameConverter))]
    public Name FirstName { get; set; }

    [CellValueConverter(typeof(NameConverter))]
    public Name LastName { get; set; }

    public int? Age { get; set; }
}

public class NameConverter : CellValueConverter<Name>
{
    public override DataCell ConvertToDataCell(Name name) => new(name.Value);
}
```

--------------------------------

### Define Default Column Width

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Use the DefaultColumnWidth attribute at the class level to set a uniform width for all columns, with individual ColumnWidth attributes taking precedence.

```csharp
[DefaultColumnWidth(20)]
public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    [ColumnWidth(10)]
    public int? Age { get; set; }
}
```

--------------------------------

### Define custom column headers with attributes

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Uses the ColumnHeader attribute to override default property-name-based header generation.

```csharp
public class Person
{
    [ColumnHeader("First name")]
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### Merge cells basic usage

Source: https://github.com/sveinungf/spreadcheetah/wiki/Merging-cells

Demonstrates merging a single row range using the MergeCells method.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

await spreadsheet.AddRowAsync([new Cell("A long report title")]);
spreadsheet.MergeCells("A1:C1");

await spreadsheet.FinishAsync();
```

--------------------------------

### Define a data object for spreadsheet rows

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

Define a plain C# class with public properties to be used as spreadsheet rows. The source generator uses public getters to determine cell order.

```csharp
namespace MyNamespace;

// A plain old C# class which we want to add as a row in a worksheet.
// The source generator will pick the properties with public getters.
// The order of the properties will decide the order of the cells.
public class MyObject
{
    public string Question { get; set; }
    public int Answer { get; set; }
}
```

--------------------------------

### Apply a default style to a column

Source: https://github.com/sveinungf/spreadcheetah/wiki/Styling

Use WorksheetOptions to set a DefaultStyle for a specific column index.

```csharp
var style = new Style();
style.Fill.Color = Color.Yellow;
style.Font.Bold = true;

await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);

var worksheetOptions = new WorksheetOptions();
worksheetOptions.Column(1).DefaultStyle = style;

await spreadsheet.StartWorksheetAsync("Sheet 1", worksheetOptions);

var cell = new Cell("My styled cell");
await spreadsheet.AddRowAsync([cell]);

await spreadsheet.FinishAsync();
```

--------------------------------

### Apply CellStyle to properties

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Reference a named style created on the Spreadsheet instance using the CellStyle attribute.

```csharp
public class Person
{
    [CellStyle("My bold style")]
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var style = new Style { Font = { Bold = true } };

// This adds a named style
spreadsheet.AddStyle(style, "My bold style");

var person = new Person
{
    FirstName = "Ola",
    LastName = "Nordmann"
};

await spreadsheet.AddAsRowAsync(person, PersonContext.Default.Person);

await spreadsheet.FinishAsync();
```

--------------------------------

### SpreadCheetah.Tables.Table

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet10_0.verified.txt

Represents a table structure that can be added to a spreadsheet, allowing for configuration of banded rows/columns and column-specific options.

```APIDOC
## Table(TableStyle style, string? name = null)

### Description
Initializes a new instance of the Table class with a specified style and optional name.

### Properties
- **BandedColumns** (bool) - Gets or sets whether banded columns are enabled.
- **BandedRows** (bool) - Gets or sets whether banded rows are enabled.
- **NumberOfColumns** (int?) - Gets or sets the total number of columns in the table.

### Methods
- **Column(int columnNumber)** - Returns a TableColumnOptions object for the specified column index.
```

--------------------------------

### View generated row addition code

Source: https://github.com/sveinungf/spreadcheetah/blob/main/README.md

The source generator creates an internal method that utilizes ArrayPool to minimize memory allocations during row creation.

```csharp
// <auto-generated />
private static async ValueTask AddAsRowInternalAsync(Spreadsheet spreadsheet, MyObject obj, CancellationToken token)
{
    var cells = ArrayPool<DataCell>.Shared.Rent(2);
    try
    {
        cells[0] = new DataCell(obj.Question);
        cells[1] = new DataCell(obj.Answer);
        await spreadsheet.AddRowAsync(cells.AsMemory(0, 2), token).ConfigureAwait(false);
    }
    finally
    {
        ArrayPool<DataCell>.Shared.Return(cells, true);
    }
}
```

--------------------------------

### Apply CellFormat to properties

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Use the CellFormat attribute to apply standard or custom number formats to class properties.

```csharp
using SpreadCheetah.SourceGeneration;
using SpreadCheetah.Styling;

namespace MyNamespace;

public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    [CellFormat(StandardNumberFormat.LongDate)]
    public DateTime DateOfBirth { get; set; }

    [CellFormat("#.0#")]
    public decimal Age { get; set; }
}
```

--------------------------------

### Apply a default style to a row

Source: https://github.com/sveinungf/spreadcheetah/wiki/Styling

Pass a RowOptions object with a DefaultStyle property to the AddRowAsync method.

```csharp
var style = new Style();
style.Fill.Color = Color.Yellow;
style.Font.Bold = true;

await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var rowOptions = new RowOptions { DefaultStyle = style };

var cell = new Cell("My styled cell");
await spreadsheet.AddRowAsync([cell], rowOptions);

await spreadsheet.FinishAsync();
```

--------------------------------

### Spreadsheet.AddHeaderRowAsync

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet8_0.verified.txt

Adds a header row to the current worksheet.

```APIDOC
## AddHeaderRowAsync

### Description
Adds a header row to the worksheet, optionally applying a style.

### Parameters
- **headerNames** (IList<string>/ReadOnlyMemory<string>/string[]) - Required - The names of the headers.
- **styleId** (StyleId) - Optional - The style to apply to the header row.
- **token** (CancellationToken) - Optional - A cancellation token.
```

--------------------------------

### TryParseColumnName(ReadOnlySpan<char> columnName, out int columnNumber)

Source: https://github.com/sveinungf/spreadcheetah/wiki/Utility-methods

Converts a spreadsheet column name string into its corresponding 1-based column number.

```APIDOC
## bool TryParseColumnName(ReadOnlySpan<char> columnName, out int columnNumber)

### Description
Parses a case-sensitive uppercase column name (A-Z) into its integer column number.

### Parameters
- **columnName** (ReadOnlySpan<char>) - Required - The column name to parse.
- **columnNumber** (out int) - Required - The resulting 1-based column number.

### Returns
- **bool** - Returns true if the column name is valid, otherwise false.
```

--------------------------------

### Spreadsheet.AddRowAsync

Source: https://github.com/sveinungf/spreadcheetah/blob/main/SpreadCheetah.Test/Tests/PublicApiTests.PublicApi_Generate.DotNet8_0.verified.txt

Adds a row of cells to the current worksheet asynchronously.

```APIDOC
## AddRowAsync

### Description
Adds a row of cells to the current worksheet. Supports various cell types including Cell, DataCell, and StyledCell.

### Parameters
- **cells** (Cell[]/DataCell[]/StyledCell[]/IList) - Required - The collection of cells to add as a row.
- **token** (CancellationToken) - Optional - A cancellation token to observe while waiting for the task to complete.
```

--------------------------------

### Ignore properties with ColumnIgnore

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Use the ColumnIgnore attribute to exclude specific properties from being generated as columns in the worksheet.

```csharp
public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    [ColumnIgnore]
    public int? Age { get; set; }
}
```

--------------------------------

### Inherit columns from base classes

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Apply the InheritColumns attribute to include properties from base classes in the generated worksheet row.

```csharp
namespace MyNamespace;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
}

[InheritColumns]
public class Student : Person
{
    public int StudentId { get; set; }
}

[WorksheetRow(typeof(Student))]
public partial class StudentContext : WorksheetRowContext;
```

--------------------------------

### Define explicit column order with attributes

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Use the ColumnOrder attribute to define the sequence of columns in the worksheet. Properties are ordered by the attribute values in ascending order.

```csharp
public class Person
{
    [ColumnOrder(3)]
    public string LastName { get; set; }

    [ColumnOrder(1)]
    public string FirstName { get; set; }

    [ColumnOrder(2)]
    public int? Age { get; set; }
}
```

--------------------------------

### Truncate cell values with CellValueTruncate

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Apply the CellValueTruncate attribute to a string property to limit its length in the generated spreadsheet.

```csharp
public class Person
{
    [CellValueTruncate(30)]
    public string FirstName { get; set; }

    public string LastName { get; set; }

    public int? Age { get; set; }
}
```

--------------------------------

### GetColumnName(int columnNumber)

Source: https://github.com/sveinungf/spreadcheetah/wiki/Utility-methods

Converts a 1-based column number to its corresponding spreadsheet column name string.

```APIDOC
## string GetColumnName(int columnNumber)

### Description
Converts a 1-based column number to its corresponding spreadsheet column name string. Throws an exception if the number is less than 1 or greater than 16384.

### Parameters
- **columnNumber** (int) - Required - The 1-based column number to convert.

### Returns
- **string** - The column name (e.g., "A", "AA").
```

--------------------------------

### Merge cells with alignment

Source: https://github.com/sveinungf/spreadcheetah/wiki/Merging-cells

Applies horizontal and vertical center alignment to a merged cell range.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

var centerAlignStyle = new Style
{
    Alignment = new Alignment
    {
        Horizontal = HorizontalAlignment.Center,
        Vertical = VerticalAlignment.Center
    }
};

var centerAlignStyleId = spreadsheet.AddStyle(centerAlignStyle);

await spreadsheet.AddRowAsync([new Cell("Content...", centerAlignStyleId)]);
spreadsheet.MergeCells("A1:C5");

await spreadsheet.FinishAsync();
```

--------------------------------

### Override inferred column headers

Source: https://github.com/sveinungf/spreadcheetah/wiki/Source-generator

Uses the ColumnHeader attribute to manually specify a header, overriding the automatic resource key lookup for that property.

```csharp
[InferColumnHeaders(typeof(MyResources), Prefix = "Header_")]
public class Person
{
    public string FirstName { get; set; }

    public string LastName { get; set; }

    [ColumnHeader("How old?")]
    public int? Age { get; set; }
}
```

--------------------------------

### Merge cells with hidden values

Source: https://github.com/sveinungf/spreadcheetah/wiki/Merging-cells

Shows that only the top-left cell value remains visible when merging a range containing multiple values.

```csharp
await using var spreadsheet = await Spreadsheet.CreateNewAsync(stream);
await spreadsheet.StartWorksheetAsync("Sheet 1");

Cell[] row = [new(1), new(2), new(3), new(4), new(5)];
await spreadsheet.AddRowAsync(row);
spreadsheet.MergeCells("B1:D1");

await spreadsheet.FinishAsync();
```
Tokens:
Raw