PadronetXLSXReader 1.0.5

📊 Padronet XLSX Reader

Leitor genérico de arquivos XLSX (Excel) em .NET, responsável por ler planilhas e convertê-las em objetos fortemente tipados, de acordo com um modelo pré-definido (DTO / Model).

Este componente isola toda a complexidade de leitura de Excel (múltiplas abas, conversões culturais, mapeamento de colunas e validações básicas), mantendo a aplicação limpa, testável e aderente a boas práticas de arquitetura.

🎯 Objetivo

• Ler arquivos XLSX
• Converter linhas da planilha em objetos C#
• Suportar múltiplas abas
• Mapear colunas via atributo ([XlsxColumn])
• Realizar conversões no padrão pt-BR (dd/MM/yyyy, 1.234,56)
• Ignorar linhas vazias
• Retornar erros por linha, sem interromper o processamento
• Ser reutilizável em integrações, BI, ETL e automações

🧩 Responsabilidade

✔️ Ler planilhas Excel (.xlsx)
✔️ Mapear colunas para propriedades
✔️ Converter tipos (datas, decimais, etc.)
✔️ Coletar erros de leitura por linha

❌ Não valida regras de negócio
❌ Não persiste dados

🏗️ Arquitetura

Controller / Job / Worker
        ↓
Application Service
        ↓
IXlsxReaderService
        ↓
Arquivo XLSX

🔌 Interface

public interface IXlsxReaderService
{
    XlsxReadResult<T> Read<T>(byte[] file);
}

📦 Resultado da Leitura

public class XlsxReadResult<T>
{
    public List<T> Items { get; set; } = new();
    public List<XlsxRowError> Errors { get; set; } = new();
}

public class XlsxRowError
{
    public int RowNumber { get; set; }
    public string Column { get; set; } = string.Empty;
    public string Message { get; set; } = string.Empty;
}

🧷 Mapeamento de Colunas

[AttributeUsage(AttributeTargets.Property)]
public class XlsxColumnAttribute : Attribute
{
    public string Name { get; }
    public string[] Aliases { get; }

    public XlsxColumnAttribute(string name, params string[] aliases)
    {
        Name = name;
        Aliases = aliases;
    }
}

📄 Exemplo de Model (DTO)

public class BillingRow
{
    [XlsxColumn("Billing Date", "Data Faturamento")]
    public DateTime BillingDate { get; set; }

    [XlsxColumn("Invoice Number", "Nota")]
    public string InvoiceNumber { get; set; } = string.Empty;

    [XlsxColumn("Total Amount", "Valor Total")]
    public decimal TotalAmount { get; set; }
}

🚀 Uso

var result = _xlsxReader.Read<BillingRow>(fileBytes);

var items = result.Items;
var errors = result.Errors;

⚠️ Tratamento de Erros

• Coluna obrigatória ausente
• Conversão inválida (data, decimal, número)
• Linha parcialmente inválida

O processamento não é interrompido em caso de erro.

🌎 Conversões Culturais

O serviço utiliza a cultura pt-BR por padrão:

• Datas: dd/MM/yyyy
• Decimais: 1.234,56

🔧 Registro no DI (ASP.NET Core)

services.AddScoped<IXlsxReaderService, XlsxReaderService>();

📌 Boas práticas adotadas

• Separação clara de responsabilidades
• Mapeamento explícito por atributo
• Leitura tolerante a erros
• Suporte a múltiplas abas
• Pronto para ambientes enterprise

🔥 Possíveis extensões

• Validação por atributo (Required, Range, Regex)
• Geração de planilha de retorno com erros destacados
• Suporte a CSV
• Leitura streaming para arquivos grandes
• Customização de cultura

🧠 Quando usar este leitor?

• Importação de planilhas de faturamento
• Integrações com SAP / ERP
• Processos de BI
• Cargas em lote
• Automação de processos