Net4x.SpreadsheetLibrary.Utility 1.9.9.6

SpreadsheetLibrary.Utility

Small utility helpers used by the SpreadsheetLibrary projects to support saving workbooks, converting legacy XLS to XLSX, and simple file-picking abstractions for UI/tooling integrations.

Purpose

• Provide lightweight helpers that are orthogonal to core spreadsheet processing: converting .xls streams to .xlsx, selecting a save target via an abstraction, converting collections of CSV text into DataSet instances and other small helpers.
• Keep UI/OS-specific file-picking code isolated behind ISaveFilePicker so library code remains testable and cross-platform where possible.

Main components

• ISaveFilePicker (interface)

  • Abstraction for picking a file name/path to save to. Implement this in your UI layer or test harness to control where save dialogs appear.
  • Method: Task<(bool, string)> PickFile(string fileName) � returns a tuple indicating whether a file was selected and the selected path.

• SaveFilePickerExtension (extensions)

  • Helpers for coordinating multiple DataTable/DataSet saves using an ISaveFilePicker implementation.
  • SaveDataTablesToExcelAsync helpers will prompt (via ISaveFilePicker) and then write Excel files when appropriate, logging issues via ILogger.

• XlsToXlsxConverter

  • Converts an in-memory stream containing a legacy HSSF .xls workbook into an XSSF .xlsx byte array using NPOI.
  • Preserves sheet names, cell values, styles, merged regions and column widths where possible.
  • Useful for workflows that need to normalize legacy Excel files to XLSX prior to further processing.

• SaveToDictionaryExtension and ListExtension (CSV helpers)

  • Convert string/CSV collections into dictionary-backed DataSet instances for later export to Excel or processing.
  • Provide small helpers to normalize collections and read CSV via SpreadsheetLibrary.Csv utilities.

Compatibility and dependencies

• The utilities use NPOI (NPOI.HSSF, NPOI.XSSF, NPOI.SS) to manipulate Excel workbooks and ICSharpCode.SharpZipLib where appropriate (transitive dependency via NPOI for some runtimes).
• The project includes code compiled for older frameworks (net35/net40) and newer netstandard targets; ensure you reference compatible NPOI packages for your target framework.

Usage examples

Convert a legacy .xls stream to .xlsx bytes:

using (var fs = File.OpenRead("legacy.xls"))
{
    var xlsxBytes = fs.ConvertXlsToXlsx();
    File.WriteAllBytes("converted.xlsx", xlsxBytes);
}

Pick a save file and write a dataset to Excel (UI specific ISaveFilePicker required):

var (ok, path) = await saveFilePicker.PickFile("20250101-120000.xls");
if (ok && !string.IsNullOrWhiteSpace(path))
{
    dataSet.ToExcel(path, isXlsx: false, logger: logger);
}

Convert an enumerable of CSV text into a DataSet for export:

var dict = SaveToDictionaryExtension.SaveToDictionary(myEnumerable);
var dataSet = dict.GetAsDataSet("Export");

Notes and recommendations

• XlsToXlsxConverter attempts to copy styles and merged regions but very complex legacy workbooks may not round-trip perfectly.
• ISaveFilePicker is intentionally minimal � provide an implementation appropriate for desktop, web or automated test environments.
• The save helpers prefer a non-empty selection; callers should validate returned paths.

License / Contributing

See repository root for license and contribution guidelines.