Kwolo.ExcelParser 1.0.3

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Kwolo.ExcelParser --version 1.0.3                

                    
                

            
NuGet\Install-Package Kwolo.ExcelParser -Version 1.0.3
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Kwolo.ExcelParser" Version="1.0.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Kwolo.ExcelParser --version 1.0.3                

                    
                

            
#r "nuget: Kwolo.ExcelParser, 1.0.3"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install Kwolo.ExcelParser as a Cake Addin
#addin nuget:?package=Kwolo.ExcelParser&version=1.0.3

// Install Kwolo.ExcelParser as a Cake Tool
#tool nuget:?package=Kwolo.ExcelParser&version=1.0.3

Excel file parser

Purpose

This is a .net class library that wraps the somewhat impenetrable Open-XML-SDK nuget package (even the name is so non-Nuget, non-Microsoft, it's painful to look at...) to parse Excel files into a simple Worksheet model that comprises Rows that, you guessed it, consist of Cells.

Nuget & source

Available on nuget at https://www.nuget.org/packages/Kwolo.ExcelParser/

Source on GitLab at https://gitlab.com/skotl/excel-parser

Usage: Parsed row, cell and value

RowModel

A RowModel has a row number (one-based) and a collection of CellModels.

CellModel

The CellModel comprises the following properties, all intended to make the cell as easy to work with as possible:

Property Use
Reference The Excel friendly reference for a cell, like "A1" or "M33"
Row The one-based row number that this cell belongs to
Column The one-based column number that this cell belongs to (if you want the string translation, use Reference
Value A complex object, described below, that allows the value to be determined
StringValue A shortcut to Value.StringValue, which always holds the original text value of the cell

ValueModel

The ValueModel consists of a guessed data type (not all types are exposed by the raw Excel format) as well as potential parsed values as Dates, Strings, Integers, Decimals and Booleans.

Check ValueModel.DataType for the base type, which will be one of the following:

  • StringType
  • BoolType
  • NumberType

Note that the Excel file structure does not define specific types for dates or percentages - these are all stored as NumberTypes and it's the Excel cell's formatting that decides how they are displayed. This means that you already need to know that a cell will contain a date before attempting to read its date value.

The properties on ValueModel include:

Property Description
StringValue If the cell held any value then its text representation will be stored here
BoolValue If the cell was a NumberType and could be parsed to a bool, then it is stored here
IntValue If the cell was a NumberType and could be parsed to an int, then it is stored here
DecimalValue If the cell was a NumberType and could be parsed to a decimal, then it is stored here
DateValue If the cell was a NumberType and could be parsed to a date, then it is stored here

Usage

Instantiate a new ExcelParser and call one of the Parse() methods:

public bool Parse(Stream excelFile, bool throwOnError = false)

public bool Parse(Stream excelFile, int worksheetNumber, bool throwOnError = false)

Where you can pass a combination of these parameters:

Parameter Usage
excelFile A stream containing a raw .xlsx or .xlsxm file
worksheetNumber One-based worksheet to parse, which defaults to 1
throwOnError If true, any exceptions in parsing are rethrown

If throwOnError is false and an exception is thrown it is caught by the parser and the following properties are set:

Property Description
FailedRowCell The cell reference that generated the error, e.g. "B15"
Error A string containing the error message, without a stack trace
ErrorStackTrace The stack trace for the error

Sample app

The Source structure contains a test console application called Kwolo.ExcelParser.TestApp

This project contains a simple and a complex Excel file in the /ExcelFiles folder and dumps the contents of the rows and cells for each of these files.

You can also pass the name of an Excel file as an argument if you want to try it out with your own file.

Tests

The Source structure contains an xunit test project called Kwolo.ExcelParser.Tests that should cover most of the model and parsing functionality.

Contributions

Contributions and issues welcome within GitLab - note that no warranty is offered and, while this is an actively maintained project (I use the package in several commercial and home-based apps), not everything may get fixed!

If you are keen to contribute then please be aware that high test coverage is expected.

License

See License file, here

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.3 104 11/8/2024