How to Work with Core Workbook Settings in .NET

Aspose.Cells FOSS for .NET exposes workbook-level configuration through Workbook.Settings (locale and date system), Workbook.DocumentProperties (author metadata), Workbook.LoadDiagnostics (repair report), and SaveOptions (save behaviour). Install with dotnet add package Aspose.Cells_FOSS.

Step-by-Step Guide

Step 1: Install the Package

dotnet add package Aspose.Cells_FOSS

Step 2: Import the Namespace

using Aspose.Cells_FOSS;
using System.Globalization;

Step 3: Configure WorkbookSettings

Workbook.Settings returns a WorkbookSettings object. Set Date1904 = true for macOS-originated files that use the 1904 date system. Set Culture to control number and date parsing locale.

using Aspose.Cells_FOSS;
using System.Globalization;

var wb = new Workbook();
wb.Settings.Date1904 = false;
wb.Settings.Culture = new CultureInfo("en-US");
wb.Worksheets[0].Cells["A1"].PutValue("Settings configured");
wb.Save("settings.xlsx");

var loaded = new Workbook("settings.xlsx");
Console.WriteLine("Date1904: " + loaded.Settings.Date1904);

Step 4: Set Document Properties

Workbook.DocumentProperties exposes Title, Subject, Author, Keywords, Comments, Category, Company, and Manager as direct string properties.

using Aspose.Cells_FOSS;

var wb = new Workbook();
wb.DocumentProperties.Title = "Quarterly Report";
wb.DocumentProperties.Author = "Reporting Team";
wb.DocumentProperties.Company = "Contoso Ltd";
wb.DocumentProperties.Keywords = "quarterly, sales, 2026";
wb.Save("properties.xlsx");

var loaded = new Workbook("properties.xlsx");
Console.WriteLine("Title: " + loaded.DocumentProperties.Title);
Console.WriteLine("Author: " + loaded.DocumentProperties.Author);

Step 5: Use SaveOptions

Workbook.Save(path, SaveOptions) accepts a SaveOptions object to customise the output. Key properties: UseSharedStrings (reduces file size for sheets with repeated strings), ValidateBeforeSave (runs validation before writing), and CompactStyles (removes unused styles).

using Aspose.Cells_FOSS;

var wb = new Workbook();
var ws = wb.Worksheets[0];
for (var i = 0; i < 50; i++)
    ws.Cells[i, 0].PutValue("Repeated text");

var opts = new SaveOptions
{
    UseSharedStrings = true,
    ValidateBeforeSave = true,
    CompactStyles = true,
};

wb.Save("compact.xlsx", opts);
Console.WriteLine("Saved with SaveOptions.");

Step 6: Read LoadDiagnostics After Repair

After loading with TryRepairPackage = true, check Workbook.LoadDiagnostics to see whether any repairs were applied.

using Aspose.Cells_FOSS;

var opts = new LoadOptions { TryRepairPackage = true, TryRepairXml = true };
var wb = new Workbook("file.xlsx", opts);
var diag = wb.LoadDiagnostics;

Console.WriteLine("HasRepairs: " + diag.HasRepairs);
Console.WriteLine("HasDataLossRisk: " + diag.HasDataLossRisk);
foreach (var entry in diag.Issues)
    Console.WriteLine($"  [{entry.Severity}] {entry.Code}: {entry.Message}");

Common Issues and Fixes

WorkbookSaveException when ValidateBeforeSave = true. The workbook contains a structural inconsistency. Disable ValidateBeforeSave temporarily to save and inspect the file, then fix the problematic content.

Document properties not visible in Excel’s File Info panel. Ensure you are setting properties on Workbook.DocumentProperties, not Workbook.Properties. The latter holds display flags, not metadata strings.

Date1904 = true causes date values to shift. Date1904 changes the epoch used for date serial numbers. Only set it to true for files that originated from macOS Excel with the 1904 date system enabled; mixing systems causes off-by-1462-day errors.

Frequently Asked Questions

What is the difference between `WorkbookSettings` and `WorkbookProperties`?

WorkbookSettings (via Workbook.Settings) holds configuration values like Date1904 and Culture. WorkbookProperties (via Workbook.Properties) holds OOXML display flags such as ShowObjects. Document metadata strings (Title, Author, etc.) live in Workbook.DocumentProperties.

Does `CompactStyles` ever remove styles I need?

No. CompactStyles only removes styles that are not referenced by any cell or format rule in the workbook.

Can I read `LoadDiagnostics` even when no repair was attempted?

Yes. The Issues collection will be empty and both HasRepairs and HasDataLossRisk will return false.