Introduction

Aspose.Cells FOSS for .NET provides a comprehensive API for managing Excel .xlsx workbooks entirely in managed code, with no Microsoft Office dependency. The Aspose.Cells_FOSS NuGet package exposes a public surface covering the complete workbook lifecycle — from loading (including repair of damaged files) through cell operations, worksheet configuration, print setup, and save.

This guide focuses on the spreadsheet management layer: how workbooks are loaded and saved, how worksheet display and protection settings are configured, how page setup is controlled for print output, and how data validation rules are defined. All code examples use verified API members from the library’s public surface.

Loading Workbooks

Standard and Repair Loading

Load an existing .xlsx file by passing the file path to new Workbook(filePath). For files that may be damaged or contain structural errors, pass a LoadOptions instance with TryRepairPackage = true and TryRepairXml = true. If the file cannot be parsed even with repair enabled, a WorkbookLoadException is thrown.

using Aspose.Cells_FOSS;

var options = new LoadOptions
{
    TryRepairPackage = true,
    TryRepairXml = true,
};

try
{
    _ = new Workbook("sample.xlsx", options);
}
catch (WorkbookLoadException exception)
{
    Console.WriteLine(exception.Message);
}

Round-Trip Fidelity

After loading, cell values of all supported types — string, int, double, decimal, bool, DateTime — are preserved on save. Formulas set via Cell.Formula are stored as formula strings and remain intact across a save-load cycle.

using Aspose.Cells_FOSS;

var outputPath = Path.Combine(AppContext.BaseDirectory, "cell-data-roundtrip.xlsx");
var timestamp = new DateTime(2024, 5, 6, 7, 8, 9, DateTimeKind.Utc);

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Cells["A1"].PutValue("Hello");
sheet.Cells["B1"].PutValue(123);
sheet.Cells["C1"].PutValue(true);
sheet.Cells["D1"].PutValue(12.5m);
sheet.Cells["E1"].PutValue(timestamp);
sheet.Cells["F1"].PutValue(10);
sheet.Cells["G1"].PutValue(20);
sheet.Cells["G1"].Formula = "=F1*2";
workbook.Save(outputPath);

var loaded = new Workbook(outputPath);
var loadedSheet = loaded.Worksheets[0];
Console.WriteLine(loadedSheet.Cells["A1"].StringValue);
Console.WriteLine(loadedSheet.Cells["G1"].Formula + " -> " + loadedSheet.Cells["G1"].StringValue);

Worksheet Settings

Display, Visibility, and Layout

Each Worksheet exposes display settings via ShowGridlines, ShowRowColumnHeaders, ShowZeros, RightToLeft, Zoom, and TabColor. Set VisibilityType to VisibilityType.Hidden to hide a sheet from the tab bar. Control row height and column width through Cells.Rows[index].Height and Cells.Columns[index].Width. Use Cells.Merge(rowIndex, colIndex, rowSpan, colSpan) to merge a block of cells into one logical cell.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var layout = workbook.Worksheets[0];
layout.Name = "Layout";
layout.VisibilityType = VisibilityType.Hidden;
layout.TabColor = Color.FromArgb(255, 34, 68, 102);
layout.ShowGridlines = false;
layout.ShowRowColumnHeaders = false;
layout.ShowZeros = false;
layout.RightToLeft = true;
layout.Zoom = 85;
layout.Protect();
layout.Protection.Objects = true;
layout.Protection.Scenarios = true;
layout.Protection.FormatCells = true;
layout.Protection.InsertRows = true;
layout.Protection.AutoFilter = true;
layout.Protection.SelectLockedCells = true;
layout.Protection.SelectUnlockedCells = true;

layout.Cells["A1"].PutValue("Merged");
layout.Cells["C4"].PutValue(99);
layout.Cells.Rows[1].Height = 22.5d;
layout.Cells.Rows[3].IsHidden = true;
layout.Cells.Columns[0].Width = 18.25d;
layout.Cells.Columns[2].IsHidden = true;
layout.Cells.Merge(0, 0, 2, 2);

var visibleIndex = workbook.Worksheets.Add("Visible");
var visibleSheet = workbook.Worksheets[visibleIndex];
visibleSheet.Cells["A1"].PutValue("Visible");
workbook.Worksheets.ActiveSheetName = "Visible";

workbook.Save("worksheet-settings-sample.xlsx");

var loaded = new Workbook("worksheet-settings-sample.xlsx");
var loadedLayout = loaded.Worksheets["Layout"];
Console.WriteLine("Active sheet: " + loaded.Worksheets.ActiveSheetName);
Console.WriteLine("Layout visibility: " + loadedLayout.VisibilityType);
Console.WriteLine("Merged regions: " + loadedLayout.Cells.MergedCells.Count);

Page Setup for Print

The Worksheet.PageSetup object controls all print-layout parameters. Configure margins, Orientation (PageOrientationType.Landscape or Portrait), PaperSize, scale, PrintArea, PrintTitleRows, PrintTitleColumns, header and footer text, gridlines, centering, and page breaks. All settings survive a save-load cycle.

using Aspose.Cells_FOSS;

var outputPath = Path.Combine(AppContext.BaseDirectory, "page-setup-sample.xlsx");

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Name = "Print Sheet";
sheet.Cells["A1"].PutValue("Title");
sheet.Cells["C10"].PutValue(42);

var pageSetup = sheet.PageSetup;
pageSetup.LeftMarginInch = 0.25d;
pageSetup.RightMarginInch = 0.4d;
pageSetup.TopMarginInch = 0.5d;
pageSetup.BottomMarginInch = 0.6d;
pageSetup.HeaderMarginInch = 0.2d;
pageSetup.FooterMarginInch = 0.22d;
pageSetup.Orientation = PageOrientationType.Landscape;
pageSetup.PaperSize = PaperSizeType.PaperA4;
pageSetup.FirstPageNumber = 3;
pageSetup.Scale = 95;
pageSetup.FitToPagesWide = 1;
pageSetup.FitToPagesTall = 2;
pageSetup.PrintArea = "$A$1:$C$10";
pageSetup.PrintTitleRows = "$1:$2";
pageSetup.PrintTitleColumns = "$A:$B";
pageSetup.LeftHeader = "Left Header";
pageSetup.CenterHeader = "Center Header";
pageSetup.RightHeader = "Right Header";
pageSetup.LeftFooter = "Left Footer";
pageSetup.CenterFooter = "Center Footer";
pageSetup.RightFooter = "Right Footer";
pageSetup.PrintGridlines = true;
pageSetup.PrintHeadings = true;
pageSetup.CenterHorizontally = true;
pageSetup.CenterVertically = true;
pageSetup.AddHorizontalPageBreak(4);
pageSetup.AddHorizontalPageBreak(7);
pageSetup.AddVerticalPageBreak(2);

workbook.Save(outputPath);

var loaded = new Workbook(outputPath);
var loadedPageSetup = loaded.Worksheets[0].PageSetup;
Console.WriteLine("Orientation: " + loadedPageSetup.Orientation);
Console.WriteLine("Paper size: " + loadedPageSetup.PaperSize);
Console.WriteLine("Print area: " + loadedPageSetup.PrintArea);

Data Validation

Worksheet.Validations manages all input-constraint rules on a sheet. Call Validations.Add(CellArea) to register a rule, then configure its Type (ValidationType.List, Decimal, Custom), Operator, formula bounds, alert style (ValidationAlertType.Warning or Stop), and prompt messages.

using Aspose.Cells_FOSS;

var outputPath = Path.Combine(AppContext.BaseDirectory, "validations-sample.xlsx");

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Name = "Validation Sheet";

sheet.Cells["A1"].PutValue("Open");
sheet.Cells["B2"].PutValue(5);
sheet.Cells["C3"].PutValue(7);
sheet.Cells["E2"].PutValue(8);
sheet.Cells["G1"].PutValue("ABCDE");

var listValidationIndex = sheet.Validations.Add(CellArea.CreateCellArea("A1", "A3"));
var listValidation = sheet.Validations[listValidationIndex];
listValidation.Type = ValidationType.List;
listValidation.Formula1 = "\"Open,Closed\"";
listValidation.IgnoreBlank = true;
listValidation.InCellDropDown = true;
listValidation.ShowInput = true;
listValidation.InputTitle = "Status";
listValidation.InputMessage = "Pick a status";
listValidation.ShowError = true;
listValidation.ErrorTitle = "Invalid";
listValidation.ErrorMessage = "Choose from the list";

var decimalValidationIndex = sheet.Validations.Add(CellArea.CreateCellArea("B2", "C3"));
var decimalValidation = sheet.Validations[decimalValidationIndex];
decimalValidation.Type = ValidationType.Decimal;
decimalValidation.Operator = OperatorType.Between;
decimalValidation.Formula1 = "1.5";
decimalValidation.Formula2 = "9.5";
decimalValidation.ErrorTitle = "Range";
decimalValidation.ErrorMessage = "Enter 1.5-9.5";
decimalValidation.ShowError = true;
decimalValidation.AddArea(CellArea.CreateCellArea("E2", "E3"));

var customValidationIndex = sheet.Validations.Add(CellArea.CreateCellArea("G1", "G1"));
var customValidation = sheet.Validations[customValidationIndex];
customValidation.Type = ValidationType.Custom;
customValidation.AlertStyle = ValidationAlertType.Warning;
customValidation.Formula1 = "LEN(G1)<=5";
customValidation.ShowInput = true;
customValidation.InputTitle = "Code";
customValidation.InputMessage = "Up to 5 chars";

workbook.Save(outputPath);

var loaded = new Workbook(outputPath);
var loadedSheet = loaded.Worksheets["Validation Sheet"];
Console.WriteLine("Validation count: " + loadedSheet.Validations.Count);

Quick Start

dotnet add package Aspose.Cells_FOSS

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Cells["A1"].PutValue("Hello");
sheet.Cells["B1"].PutValue(123);
sheet.Cells["C1"].Formula = "=B1*2";
workbook.Save("output.xlsx");

Supported Formats

FormatExtensionReadWrite
Xlsx.xlsx✓✓
Auto(various)✓—

Open Source & Licensing

Aspose.Cells FOSS for .NET is published under the MIT license and distributed via NuGet as Aspose.Cells_FOSS. It is suitable for both open-source and commercial use.

Getting Started