Concepts

Data Operations

Data Operations

GPAL.Excel: Spreadsheet Operations

Opening a Workbook and Sheet

GPAL.ExcelFor(file) is shorthand for GPAL.Excel.WithFile(file). Both return a chain where WithSheet(index) or WithSheet(name) selects the active sheet for everything that follows. Close(saveOnClose) closes the workbook, optionally saving changes; SaveTo(file) writes the workbook out without closing it, and SaveTo(sheetIndex) or SaveTo(sheetName) write the range read into that sheet.

var excel = GPAL.ExcelFor("report.xlsx")

.WithSheet("Summary");


// ...read or write cells, ranges, etc...


excel.Close(saveOnClose: true);

Addressing Cells, Ranges, Rows, and Columns

You scope operations by selecting a range, a single cell, an entire column, or an entire row. Once the scope is set, write its contents, or modify a cell's existing value by replacing it, prepending or appending text, or inserting text before or after it with a configurable separator. The selection narrows or widens between operations without needing to rebuild the Excel object.

var excel = GPAL.ExcelFor("report.xlsx").WithSheet(1);


// Overwrite a single cell

excel.WithCell("B2").SetValue("Revised");


// Add text after the existing text, with a separator

excel.WithCell("C2")

.WithInsertPosition(1)

.WithInsertSeparator("; ")

.InsertValue("reviewed");


// Forget the ranges read so far, then read a new one

excel.ClearRanges().WithRange("A2:D2");

Calculations and Comparisons

Quick calculations like sum and count run against whatever scope is currently selected and return the result as a string. The comparison feature checks the current selection cell-by-cell against another data source -- a grid, a file, or another range -- and returns the differences as a grid you can save, convert, or email as a discrepancy report.

var excel = GPAL.ExcelFor("budget.xlsx").WithSheet("FY2026");


string total;

excel.WithColumn("D").CalculateSum(out total);


// Compare this month's sheet against last month's exported grid

IGPALGrid<string> differences;

excel.WithRange("A1:D50")

.CompareToGrid(lastMonthGrid)

.GetCompareResults(out differences);


differences.SaveTo("discrepancies.csv");

NOTE

Where the converter stops and Excel starts: GPAL.Converter turns one format into another and writes a single sheet, because the tab layout it uses is captured from a workbook it read. GPAL.Excel authors a workbook: WithNewFile starts one, WithNewSheet adds each tab, and InputFrom writes a grid of your own into a sheet.

WARNING

The underlying workbook file stays open (and may be locked) until Close(saveOnClose) is called. If a workflow needs to read the same file with another GPAL subsystem afterward -- GPALConverter or GPAL.FileFor for a copy/move, for example -- call Close first.

On this page

Data Operations
GPAL.Excel: Spreadsheet Operations
  • Opening a Workbook and Sheet
  • Addressing Cells, Ranges, Rows, and Columns
  • Calculations and Comparisons
    • 💬 Ask GPAL