Aquila.ExcelReader 1.0.3

Aquila.ExcelReader — README & User Documentation

📦 Overview

Aquila.ExcelReader is a lightweight, fluent, and developer-friendly Excel parsing library for .NET / .NET MAUI applications. It allows you to map Excel columns directly to C# models using a simple fluent API — without complex configuration.

Designed for:

• Mobile apps (MAUI)
• Desktop apps
• Web APIs
• Data import tools
• Enterprise systems

✨ Key Features

• Fluent column mapping
• Header-based parsing
• Custom value converters
• Row validation support
• Skip empty rows
• Lightweight & fast
• Async streaming read
• Works across platforms (Windows / Android / etc.)

🧩 Installation

Add Package

Install via NuGet (or local reference):

dotnet add package Aquila.ExcelReader

Or add project reference if using source.

📁 Excel File Requirements

Your Excel sheet must:

• Contain a header row
• Header names must match mapped names
• Data must begin below header row

Example Excel

🏗 Step-by-Step Usage

1️⃣ Create a Model

Define the class representing a row:

public class Item
{
    public string ItemName { get; set; }
    public decimal Price { get; set; }
}

2️⃣ Configure Mapping

Create column mapping between Excel headers and model properties.

var map = new AqlExcelMap<Item>()
    .Map(x => x.ItemName)
        .FromHeader("itemname")
        .Build()
    .Map(x => x.Price)
        .FromHeader("price")
        .WithConverter(v => decimal.Parse(v!))
        .Build();

Mapping Options

3️⃣ Read Excel File

var options = new AqlExcelOptions
{
    HeaderRowNumber = 1,
    SkipEmptyRows = true
};

var reader = new AqlExcelReader<Item>(map, options);

using var stream = File.OpenRead("items.xlsx");
var result = await reader.ReadAsync(stream);

4️⃣ Access Results

foreach (var item in result.Records)
{
    Console.WriteLine(item.ItemName);
    Console.WriteLine(item.Price);
}

🛡 Validation Example

RowValidator = obj =>
{
    var item = (Item)obj;
    return item.Price < 0
        ? "Price cannot be negative"
        : null;
}

📊 Result Object

AqlExcelResult<T> provides:

Example:

if(result.HasErrors)
{
    Console.WriteLine(result.Errors.Count);
}

🧪 Full Demo Service Example

public sealed class ExcelService
{
    private readonly AqlExcelMap<Item> _map;

    public ExcelService()
    {
        _map = new AqlExcelMap<Item>()
            .Map(x => x.ItemName)
                .FromHeader("itemname")
                .Build()
            .Map(x => x.Price)
                .FromHeader("price")
                .WithConverter(v => decimal.Parse(v!))
                .Build();
    }

    public async Task<AqlExcelResult<Item>> ReadExcelAsync(Stream stream)
    {
        var options = new AqlExcelOptions
        {
            HeaderRowNumber = 1,
            SkipEmptyRows = true
        };

        var reader = new AqlExcelReader<Item>(_map, options);
        return await reader.ReadAsync(stream);
    }
}

⚠️ Common Mistakes

✅ Best Practices

• Keep headers lowercase & simple
• Trim Excel header spaces
• Always call .Build()
• Validate numeric fields
• Use converters for culture-specific parsing
• Test mapping with small Excel files first

🚀 Performance Tips

• Avoid heavy converters
• Skip validation if not needed
• Use async streams
• Map only required columns

📌 Platform Support

• .NET 8 / 9
• .NET MAUI
• Windows
• Android
• iOS (supported by design)
• macOS

🔮 Roadmap (Planned)

• Multi-sheet reading
• Column index mapping
• Header fuzzy matching
• Bulk import optimization
• Streaming low-memory mode
• Excel export companion

👨‍💻 Support

For issues or contributions:

• Submit GitHub issue
• Contact Aquila Innovations
• Review examples in DemoExcel_App

❤️ Conclusion

Aquila.ExcelReader provides a clean, modern way to import Excel data into .NET applications with minimal setup while remaining highly extensible.

It’s designed to scale from small mobile apps to enterprise-grade data pipelines.

Happy building 🚀