Working with Core Workbook Settings

Working with Core Workbook Settings

Beyond the worksheet grid, a workbook carries metadata and configuration that affects how Excel interprets it: the date system, document author, locale, and whether recovery information is stored. The Workbook class exposes these through Workbook.Settings, Workbook.Properties, and Workbook.LoadDiagnostics. Save behaviour is controlled through SaveOptions.

Workbook Settings

Workbook.Settings returns a WorkbookSettings object. Set Date1904 to true to use the 1904 date system (common in files originating from macOS Excel). Set Culture to a CultureInfo instance to control number and date parsing locale.

using Aspose.Cells_FOSS;
using System.Globalization;

var wb = new Workbook();

// Use 1904 date system
wb.Settings.Date1904 = true;

// Set culture for number/date formatting
wb.Settings.Culture = new CultureInfo("en-US");

wb.Worksheets[0].Cells["A1"].PutValue("Settings applied");
wb.Save("settings.xlsx");

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

Document Properties

Workbook.Properties returns a WorkbookProperties object with display-oriented flags such as ShowObjects and FilterPrivacy. For authorship and descriptive metadata use Workbook.DocumentProperties, which exposes Title, Subject, Author, Keywords, Comments, Category, Company, and Manager as direct string properties.

using Aspose.Cells_FOSS;

var wb = new Workbook();

var doc = wb.DocumentProperties;
doc.Title = "Quarterly Report";
doc.Subject = "Sales Data";
doc.Author = "Reporting Team";
doc.Company = "Contoso Ltd";
doc.Keywords = "sales, quarterly, 2026";
doc.Comments = "Generated by automated pipeline";

wb.Worksheets[0].Cells["A1"].PutValue("See document properties");
wb.Save("properties.xlsx");

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

Load Diagnostics

After loading a workbook, check Workbook.LoadDiagnostics to discover whether the library applied any repairs. LoadDiagnostics.HasRepairs is true if at least one structural repair was made. LoadDiagnostics.HasDataLossRisk is true if a repair discarded data. Iterate LoadDiagnostics.Issues to access individual DiagnosticEntry objects with Code, Severity, Message, RepairApplied, and DataLossRisk.

using Aspose.Cells_FOSS;

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

try
{
    var wb = new Workbook("possibly-corrupt.xlsx", opts);
    var diag = wb.LoadDiagnostics;

    if (diag.HasRepairs)
    {
        Console.WriteLine("Repairs applied: " + diag.HasRepairs);
        Console.WriteLine("Data loss risk: " + diag.HasDataLossRisk);
        foreach (var entry in diag.Issues)
        {
            Console.WriteLine($"  [{entry.Severity}] {entry.Code}: {entry.Message}");
            Console.WriteLine($"  RepairApplied={entry.RepairApplied}, DataLossRisk={entry.DataLossRisk}");
        }
    }
    else
    {
        Console.WriteLine("File loaded cleanly.");
    }
}
catch (WorkbookLoadException ex)
{
    Console.WriteLine("Unrecoverable: " + ex.Message);
}

Save Options

Workbook.Save(path, SaveOptions) accepts a SaveOptions object to customise the save output. UseSharedStrings controls whether string values are stored in the shared string table (reduces file size for sheets with many repeated strings). ValidateBeforeSave runs internal workbook validation before writing. CompactStyles removes unused styles. PreserveRecoveryMetadata controls whether Office recovery metadata is preserved.

using Aspose.Cells_FOSS;

var wb = new Workbook();
var ws = wb.Worksheets[0];

for (var i = 0; i < 100; i++)
    ws.Cells[i, 0].PutValue("Repeated string value");

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

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

Tips and Best Practices

• Check LoadDiagnostics.HasDataLossRisk after loading repaired files and warn users if data may have been dropped.
• Set DocumentProperties.Author and Company for files shared with end-users — these appear in Excel’s file info panel.
• UseSharedStrings = true is beneficial for sheets with many repeated string values (e.g. status columns); it has minimal impact on numeric-heavy sheets.
• Date1904 must match between the source and target file to avoid date-value drift when copying cells between workbooks.

Common Issues

FAQ

What is the difference between WorkbookProperties and DocumentProperties?

WorkbookProperties (via Workbook.Properties) holds OOXML display flags (e.g. ShowObjects). DocumentProperties (via Workbook.DocumentProperties) holds the Dublin-Core-style metadata strings: Title, Author, Company, etc.

Does CompactStyles delete styles I need?

CompactStyles removes only styles that are not referenced by any cell, conditional format, or named style. Styles in use are never removed.

Can I read LoadDiagnostics even when no repair was attempted?

Yes. When no repair was attempted the Issues collection is empty and both HasRepairs and HasDataLossRisk return false.

API Reference Summary