DotNetConsultaFeriados 0.1.0

DotNetConsultaFeriados

Uma biblioteca .NET para consulta de feriados bancários brasileiros.

Visão Geral (Overview)

O DotNetConsultaFeriados é uma biblioteca .NET leve e eficiente que fornece acesso facilitado aos feriados bancários do Brasil. Permite consultar feriados de qualquer ano, verificar se uma data específica é feriado e validar se o dia atual é feriado. A biblioteca inclui suporte nativo a cache e logging para otimização de performance e depuração (debugging).

Funcionalidades (Features)

• 🎯 Consulta de feriados por ano - Obtém todos os feriados bancários para um ano específico
• 📅 Verificação de data - Valida se uma data específica é um feriado
• ⏰ Verificação da data atual - Checa se o dia de hoje é feriado
• 💾 Cache em memória (In-memory caching) - Caching automático para reduzir chamadas HTTP/API
• 📝 Logging estruturado - Suporte nativo a logging através da interface ILogger
• 🧪 Totalmente testado - Cobertura de testes unitários abrangente com xUnit
• 🚀 Suporte a Async/await - Todas as operações são assíncronas
• 🔒 Validação de entrada - Validação de ano com mensagens de erro detalhadas

Requisitos

• .NET 10.0 ou superior
• Suportado em Windows, Linux e macOS

Instalação

Via Pacote NuGet

dotnet add package DotNetConsultaFeriados

Ou diretamente no seu arquivo .csproj:

<ItemGroup>
  <PackageReference Include="DotNetConsultaFeriados" Version="0.1.0" />
</ItemGroup>

Guia Rápido (Quick Start)

1. Configuração da Injeção de Dependência (DI)

Primeiro, configure os serviços necessários no container de DI:

using Microsoft.Extensions.DependencyInjection;
using DotNet.Consulta.Feriados;

var services = new ServiceCollection();
services.AddHttpClient();
services.AddMemoryCache();
services.AddTransient<ConsultaFeriados>();

using var provider = services.BuildServiceProvider();
var consultaFeriados = provider.GetRequiredService<ConsultaFeriados>();

2. Obter Feriados de um Ano

try
{
    var feriados = await consultaFeriados.ObterFeriados(2024);
    foreach (var feriado in feriados)
    {
        Console.WriteLine($"{feriado.DiaMes} - {feriado.NomeFeriado}");
    }
}
catch (ArgumentOutOfRangeException ex)
{
    Console.WriteLine($"Erro: {ex.Message}");
}

3. Verificar se uma Data é Feriado

var data = new DateTime(2024, 12, 25); // Natal
var isFeriado = await consultaFeriados.IsFeriado(data);

if (isFeriado)
{
    Console.WriteLine($"{data:yyyy-MM-dd} é um feriado bancário!");
}
else
{
    Console.WriteLine($"{data:yyyy-MM-dd} não é um feriado bancário.");
}

4. Verificar se Hoje é Feriado

var hojeEhFeriado = await consultaFeriados.HojeEhFeriado();

if (hojeEhFeriado)
{
    Console.WriteLine("Hoje é um feriado bancário!");
}
else
{
    Console.WriteLine("Hoje não é um feriado bancário.");
}

Documentação da API

Classe ConsultaFeriados

Métodos

ObterFeriados(int ano)

Retorna uma lista com todos os feriados bancários para o ano especificado.

Parâmetros:

• ano (int): O ano a ser consultado (entre 2001 e o ano atual)

Retorno:

• Task<List<Feriado>>: Uma lista de feriados para o ano consultado

Exceções (Throws):

• ArgumentOutOfRangeException: Lançada se o ano estiver fora do intervalo válido (2001 até o ano atual)

Exemplo:

var feriados = await consultaFeriados.ObterFeriados(2024);

IsFeriado(DateTime date)

Verifica se uma data específica é um feriado bancário.

Parâmetros:

• date (DateTime): A data a ser verificada

Retorno:

• Task<bool>: true se a data for um feriado; caso contrário, false

Exemplo:

bool isHoliday = await consultaFeriados.IsFeriado(new DateTime(2024, 12, 25));

HojeEhFeriado()

Verifica se a data atual (hoje) é um feriado bancário.

Retorno:

• Task<bool>: true se hoje for um feriado; caso contrário, false

Exemplo:

bool todayIsHoliday = await consultaFeriados.HojeEhFeriado();

Classe Feriado

Representa um feriado bancário brasileiro.

Propriedades:

• DiaMes (string): A data do feriado no formato dia/mês (ex: "25/12")
• DiaSemana (string): O dia da semana (ex: "Quarta-feira")
• NomeFeriado (string): O nome do feriado (ex: "Natal")

Exemplos de Uso

Integração com ASP.NET Core

// Startup.cs ou Program.cs
services.AddHttpClient();
services.AddMemoryCache();
services.AddTransient<ConsultaFeriados>();
services.AddLogging();

// No seu Controller
[ApiController]
[Route("api/[controller]")]
public class HolidaysController : ControllerBase
{
    private readonly ConsultaFeriados _consultaFeriados;

    public HolidaysController(ConsultaFeriados consultaFeriados)
    {
        _consultaFeriados = consultaFeriados;
    }

    [HttpGet("{year}")]
    public async Task<ActionResult<List<Feriado>>> GetHolidays(int year)
    {
        try
        {
            var holidays = await _consultaFeriados.ObterFeriados(year);
            return Ok(holidays);
        }
        catch (ArgumentOutOfRangeException ex)
        {
            return BadRequest(ex.Message);
        }
    }

    [HttpPost("check")]
    public async Task<ActionResult<bool>> CheckHoliday([FromBody] DateTime date)
    {
        var isHoliday = await _consultaFeriados.IsFeriado(date);
        return Ok(isHoliday);
    }
}

Dependências

• Microsoft.Extensions.Caching.Memory (10.0.10) - Caching em memória
• Microsoft.Extensions.Http (10.0.8) - Factory para HttpClient
• Microsoft.Extensions.Logging - Suporte a logging estruturado

Dependências de Teste

• xUnit - Framework de testes
• Moq - Biblioteca para criação de Mocks
• FluentAssertions - Assertivas com sintaxe fluente

Fonte de Dados

A biblioteca consulta informações de feriados bancários brasileiros a partir de uma API externa. Os dados incluem:

• Feriados fixos (Ano Novo, Independência do Brasil, Natal, etc.)
• Feriados móveis (Carnaval, Sexta-feira Santa, Corpus Christi, etc.)
• Intervalo de anos suportado: 2001 até o ano atual

Tratamento de Erros

A biblioteca realiza validação do ano informado para garantir consultas em intervalos válidos:

try
{
    var feriados = await consultaFeriados.ObterFeriados(1999);
}
catch (ArgumentOutOfRangeException ex)
{
    Console.WriteLine($"Erro: {ex.Message}");
    // Saída: "O ano deve estar entre 2001 e ano atual"
}

Logging

Habilite o logging para rastrear as operações da biblioteca:

services.AddLogging(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Information);
});

A biblioteca gera logs para:

• Início e conclusão de consultas de feriados
• Verificações de feriado para datas específicas
• Resultados e estatísticas das consultas

Caching

A biblioteca armazena automaticamente os dados de feriados em cache utilizando a interface IMemoryCache. Isso garante que:

• A primeira consulta para um determinado ano fará uma requisição à API
• Consultas subsequentes para o mesmo ano utilizarão os dados armazenados em cache
• O uso de cache reduz chamadas de rede e melhora a performance geral

Histórico de Alterações (Changelog)

Versão 0.1.0

• Lançamento inicial
• Consulta de feriados para qualquer ano válido
• Verificação de feriados por data
• Suporte a cache em memória (In-memory caching)
• Logging estruturado
• Cobertura completa com testes unitários

Feito com ❤️ para a comunidade .NET