sharpessentials.functions 1.2.22

SharpEssentials: A Biblioteca de Utilitários C# Definitiva

SharpEssentials é uma biblioteca C# moderna e poderosa, projetada para acelerar seu desenvolvimento .NET. Ela oferece uma coleção curada de extensões, padrões de projeto e helpers que eliminam código repetitivo, impõem boas práticas e otimizam tarefas comuns, permitindo que você foque em construir aplicações robustas, e não em reinventar a roda.

➤ Autor

Este projeto é mantido com dedicação por Anderson V. B. Costa.

• GitHub: @avbctr
• LinkedIn: Anderson V. B. Costa

➤ Por que usar SharpEssentials?

• Produtividade Acelerada: Reduza linhas de código com extensões e helpers para tarefas diárias.
• Código Limpo e Legível: Implemente padrões como Result e Fluent Builder para um código mais expressivo e de fácil manutenção.
• Segurança e Resiliência: Crie clientes HTTP resilientes com políticas de Retry e Circuit Breaker, e utilize helpers de criptografia.
• Foco no Desenvolvedor Brasileiro: Um conjunto de ferramentas de alta qualidade para lidar com as complexidades do Brasil: NF-e, Validação de Documentos e Certificados Digitais.
• Boas Práticas Embarcadas: O AsyncToolkit promove o uso correto de ConfigureAwait(false) para evitar deadlocks em suas aplicações.

➤ Instalação

.NET CLI:

dotnet add package sharpessentials.functions

Package Manager Console:

Install-Package sharpessentials.functions

➤ Catálogo de Funcionalidades e Exemplos

Aqui está uma visão geral das principais funcionalidades e como usá-las.

🏛️ Padrões de Projeto (Design Patterns)

Result Pattern

Evite exceções para controle de fluxo e trate sucessos e falhas de forma explícita.

public Result<User> GetUserById(int id)
{
    var user = _userRepository.Find(id);

    if (user == null)
        return Result<User>.Failure(Error.NotFound($"Usuário com ID {id} não encontrado."));

    return Result<User>.Success(user);
}

// Como usar:
var userResult = GetUserById(101);

userResult.Match(
    onSuccess: user => Console.WriteLine($"Bem-vindo, {user.Name}!"),
    onFailure: errors => errors.ForEach(e => Console.WriteLine($"Erro: {e.Code} - {e.Message}"))
);

Fluent Builder (SQL & HTTP)

Construa objetos complexos com uma API fluente e legível.

SQL Query Builder:

var query = SqlQueryBuilder.Create()
    .Select("Id", "Nome", "Email")
    .From("Usuarios", "u")
    .Join("Departamentos", "d", "u.DepartamentoId = d.Id")
    .Where("d.Nome", "=", "Engenharia")
    .And("u.Ativo", "=", 1)
    .OrderBy("u.Nome")
    .OffsetFetch(0, 50);

string sql = query.Build();
var parameters = query.Parameters;
// Use 'sql' e 'parameters' com Dapper, ADO.NET, etc.

HTTP Client Builder (com Polly):

var httpClient = new HttpClientBuilder()
    .WithBaseAddress("https://api.example.com")
    .WithBearerToken("seu_token_jwt")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .WithRetryPolicy(3, TimeSpan.FromSeconds(2)) // 3 tentativas com 2s de espera
    .WithCircuitBreaker(5, TimeSpan.FromMinutes(1)) // Abre o circuito por 1 min após 5 falhas
    .Build();

var response = await httpClient.GetAsync("/data");

Smart Enum

Crie enums mais inteligentes e poderosos que podem conter comportamento.

public class StatusPedido : SmartEnum<StatusPedido, int>
{
    public static readonly StatusPedido Aguardando = new(1, "Aguardando Pagamento");
    public static readonly StatusPedido Pago = new(2, "Pagamento Aprovado");
    public static readonly StatusPedido Enviado = new(3, "Enviado");
    public static readonly StatusPedido Cancelado = new(4, "Cancelado");

    private StatusPedido(int value, string name) : base(value, name) { }
}

// Como usar:
var status = StatusPedido.FromValue(2);
Console.WriteLine(status.Name); // "Pagamento Aprovado"

⚡ Kit de Ferramentas Assíncrono (Async Toolkit)

Escreva código assíncrono mais seguro e legível.

// Evite deadlocks em bibliotecas com SafeAwait
public async Task ProcessDataAsync()
{
    var data = await _apiClient.GetDataAsync().SafeAwait();
    // ... processa os dados
}

// Execute tarefas em background sem travar a thread principal
_loggingService.LogAsync("Iniciando operação...").FireAndForgetSafe(
    onError: ex => Console.WriteLine($"Erro no log: {ex.Message}")
);

// Encademaneto fluente de Tasks
await GetUserAsync()
    .Then(user => ProcessUserAsync(user))
    .Then(result => Console.WriteLine("Finalizado!"));

🧩 Extensões de Tipos (Type Extensions)

String

Dezenas de helpers para manipulação de strings.

// Limpa e formata
string suja = "  (123)-456-7890  ";
string soNumeros = suja.ReturnOnlyNumericString(); // "1234567890"

string comAcentos = "Solução de caffè";
string semAcentos = comAcentos.LimparTexto(); // "Solucao de caffe"

// Cria uma URL amigável
string titulo = "Tudo sobre o .NET 8!";
string url = titulo.CreateStringUrl(); // "tudo-sobre-o-net-8"

DateTime

Funções poderosas para manipulação de datas e horas.

var hoje = DateTime.Now;

// Adiciona 5 dias úteis (ignorando fins de semana e feriados)
var dataEntrega = hoje.AddBusinessDays(5, listaDeFeriados);

// Converte para o fuso horário de São Paulo
var dataIso = "2023-10-26T22:00:00Z";
DateTime dataBrasilia = dataIso.ToBrazilLocalTime();

// Pega o primeiro e último dia do mês
var primeiroDia = hoje.GetFirstDayOfMonth();
var ultimoDia = hoje.GetLastDayOfMonth();

IEnumerable & JSON

// Itera sobre uma lista
minhaLista.ForEach(item => Console.WriteLine(item));

// Serializa e desserializa objetos
var user = new User { Id = 1, Name = "Anderson" };
string json = user.ToJson();
var userObj = json.FromJson<User>();

🇧🇷 Funcionalidades para Desenvolvedores no Brasil

Um conjunto de ferramentas de primeira classe para os desafios do desenvolvimento de software no Brasil.

Validação de Documentos

Valide documentos brasileiros de forma simples e eficaz.

string cnpj1 = "11.222.333/0001-44";
string cnpj2 = "11222333000144";

if (cnpj1.IsValidCNPJ())
{
    Console.WriteLine("CNPJ 1 é válido!");
}

if (cnpj2.IsValidCNPJ())
{
    Console.WriteLine("CNPJ 2 é válido!");
}

Manipulação de NF-e (Nota Fiscal Eletrônica)

Um conjunto completo de extensões para criar, assinar, validar e manipular o XML da NF-e.

// Exemplo conceitual de assinatura de um XML de evento
var xmlEvento = new XmlDocument();
xmlEvento.Load("evento.xml");

var certificado = CertificadoDigitalHelper.LoadCertWithKey(bytesDoPfx, "senha");
var xmlAssinado = Assinador.AssinarXml(xmlEvento, "infEvento", certificado);

// Serializa/Desserializa objetos de/para XML no padrão da NF-e
var nfeObj = NFeExtensions.DeserializarNFe<TNFe>(xmlString);
var xmlDoc = NFeExtensions.Serializar(nfeObj);

Certificados Digitais

Carregue certificados digitais (PFX/P12) de forma segura a partir de arquivos ou de uma base de dados criptografada.

// Carrega um certificado a partir de um array de bytes
byte[] pfxBytes = File.ReadAllBytes("meu_certificado.pfx");
string senha = "1234";
X509Certificate2 cert = pfxBytes.LoadCertWithKey(senha);

// Carrega um certificado criptografado do banco de dados
X509Certificate2 certDoBanco = CertificadoDigitalHelper.LoadCertificateFromDatabase(
    encryptedCertBytes,
    iv,
    encryptedPassword,
    "minha-chave-de-criptografia-do-sistema"
);

➤ Comunidade

Junte-se à nossa comunidade no Telegram para tirar dúvidas, compartilhar ideias e ficar por dentro das novidades!

• Comunidade SharpEssentials no Telegram

❤️ Apoie Meu Trabalho

Gostou do meu trabalho ou dos meus projetos free? Considere me apoiar! Sua contribuição me ajuda a continuar criando e compartilhando conteúdo de qualidade com a comunidade.

<p> <a href="https://go.avbc.dev/i9HwDKlQ" target="_blank"><img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee"></a> <a href="https://go.avbc.dev/8VLnyhHA" target="_blank"><img src="https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal"></a> <a href="https://avbc.dev/fIYqVEbt" target="_blank"> <img src="https://img.shields.io/badge/Binance-FCD535?style=for-the-badge&logo=binance&logoColor=black" alt="Binance"> </a> </p>

➤ Contribuição

Sua contribuição é muito bem-vinda! Por favor, siga estes passos:

1. Faça um Fork do repositório.
2. Crie uma nova branch (git checkout -b feature/MinhaFeature).
3. Faça o commit de suas mudanças (git commit -m 'Adiciona MinhaFeature').
4. Faça o push para a branch (git push origin feature/MinhaFeature).
5. Abra um Pull Request.

➤ Licença

Distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.