VAGAS DE EMPREGO

balta.io balta.io
  • Cursos
  • Carreiras
  • Para sua Empresa
  • Livros
    • Background Services
    • Blazor com .NET 8
    • Segurança em APIs
    • Futuro do C# 12
    • Nullable Types
    • Clean Code
  • Blog

Seja Premium
balta.io

  • Cursos
  • Carreiras
  • Para sua Empresa
  • Agenda
  • Livros
    • Background Services
    • Blazor com .NET 8
    • Segurança em APIs
    • Futuro do C# 12
    • Nullable Types
    • Clean Code
  • Blog
  • Player
Seja Premium

Entre ou Cadastre-se

  • Home
  • Artigos
  • Fluent API


👉 Temos uma versão mais atualizada deste artigo no nosso novo Blog

Fluent API

Neste artigo vamos entender o que são e como podemos criar Fluent APIs no .NET com C#!

O que são Fluent APIs

Fluent APIs ou APIs fluentes é uma forma que temos de compor nosso código de forma a facilitar o uso do mesmo.

Vamos supor que queremos fazer uma composição de código, para execução de algumas tarefas, e que estas precisam ser executadas em uma determinada ordem. Neste caso, os Fluent APIs se encaixam perfeitamente.

Não podemos confundir Fluent APIs com Fluent Mapping, utilizado no Entity Framework, embora o Fluent Mapping faça uso da técnica Fluent API.

Também não devemos confundir Fluent APIs com APIs Web ou Web APIs, que criamos no ASP.NET por exemplo.

Exemplo de uso

Vamos tomar como base um exemplo que trabalhei há tempo atrás, onde havia a necessidade de gerar um arquivo yml a ser utilizado pelo GitHub Actions para deployment da aplicação.

Um arquivo yml é basicamente um texto, que deve ser escrito em uma ordem, utilizando determinados parâmetros e respeitando espaçamento.

name: Build and deploy package

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@main

    - name: Set up .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '5.0.x'    

    - name: Build with dotnet
      run: dotnet build --configuration Release

    - name: Test
      run: dotnet test

    - name: Create the Package
      run: dotnet pack --configuration Release

    - name: Publish
      run: dotnet nuget push "./Gravatar/bin/Release/Gravatar.1.1.0.nupkg" -k ${{ secrets.NUGET_TOKEN }} -s https://api.nuget.org/v3/index.json

O problema é que um simples espaço fora de lugar e boom, deployment quebrado. Desta forma, criamos uma espécie de gerador de yml onde podemos validar via código, com testes de unidade.

Desta forma, chegamos ao uso das Fluent APIs para estruturar o código de uma maneira limpa e previnir possíveis erros.

var workflow = GitHubActionBuilder
    .Configure()
    .WithName("My workflow name")
    .OnBranch("main")
    .WithJob("Build and deploy", x =>
    {
        x.Key = "MyEnvVar";
        x.Value = "MyValue";
    })
    .RunsOn("ubuntu-latest")
    .AddStep("Setup .NET", "actions/setup-dotnet@v1")
        .With(x =>
        {
            x.Key = "dotnet-version";
            x.Value = "5.0.x";
        })
    .AddStep("Add GitHub Packages Source", "dotnet nuget add source ...")
    .AddStep("Build with dotnet", "dotnet build ...")
    .Build("main-workflow.yml");

Iniciando uma Fluent API

A primeira coisa que precisamos para iniciar uma Fluent API é criar uma classe que contém um construtor. Normalmente mantemos este contrutor privado, já que não vamos precisar dele futuramente.

public class GitHubActionBuilder 
{
    private GitHubActionBuilder()
    {
    }
}

Adicionando ações

Com a Fluent API iniciada, o próximo passo é criar algumas ações, e aqui normalmente começamos com um método que não tem muito significado externamente ou que realiza apenas uma configuração.

public static GitHubActionBuilder Configure()
{
    return new GitHubActionBuilder();
}

Entretanto, todos os métodos de uma Fluent API precisam retornar ela mesma, seja utilizando um new GitHubActionBuilder() (Nome da nossa classe) ou this.

No Flunt por exemplo, o primeiro método chama-se Requires e não tem nada nele, é apenas um Syntax Sugar.

Desta forma, já podemos iniciar nosso código, utilizando a chamada ao GitHubActionBuilder.Configure() como mostrado abaixo.

var workflow = GitHubActionBuilder
    .Configure();

Problemas neste código

Por mais que este código funcione, há um problema nele. Vamos adicionar mais um método na classe GitHubActionBuilder para analisar.

public class GitHubActionBuilder 
{
    private GitHubActionBuilder()
    {
    }

    public static GitHubActionBuilder Configure()
    {
        return new GitHubActionBuilder();
    }
    
    public static GitHubActionBuilder WithName()
    {
        return new GitHubActionBuilder();
    }
}

Mesmo com um novo método adicionado, não conseguimos encadar as chamadas, não conseguimos por exemplo fazer uma chamada como abaixo.

var workflow = GitHubActionBuilder
    .WithName()
    .Configure();

Pior ainda, e se houver a necessidade explícita do método WithName vir somente depois do Configure? Como resolvemos isto?

Interfaces

A solução são as interfaces! Sim, com elas podemos limitar os retornos e permitir que o GitHubActionBuilder faça uso de várias delas.

É importante lembrar que nas novas versões do C# (9+) podemos ter implementações nas interfaces, o que provê herança múltipla aqui.

Criando as interfaces

Vamos criar duas interfaces para entender o processo, mas este se repete quantas vezes você precisar, então não vamos fazer todo código aqui.

public interface IWorkflow
{
    public IWorkflowName WithName(string name);
}

public interface IWorkflowName
{
}

Como podemos notar, temos duas interfaces, IWorkFlow e IWorkFlowName onde a primeira interface tem um método chamado WithName e retorna a segunda interface.

Aqui está o segredo, uma interface retorna ela mesma ou alguma outra interface. Assim conseguimos restringir o uso delas na ordem que seus retornos de métodos dizem.

Movendo adiante, vamos adicionar as duas interfaces a classe principal, separadas por vírgula e precedidas por :.

public class GitHubActionBuilder : 
    IWorkflow,
    IWorkflowName
{
    ...

Para finalizar, vamos implementar as interfaces, mantendo o mesmo método Configure anterior, com exceção do seu retorno que agora é um IWorkFlow.

public class GitHubActionBuilder : 
    IWorkflow,
    IWorkflowName
{
    private GitHubActionBuilder()
    {
    }

    public static IWorkflow Configure()
    {
        return new GitHubActionBuilder();
    }

    public IWorkflowName WithName()
    {
        return this;
    }
}

Note que adicionamos o método WithName que retorna this. Tanto o retorno do new GitHubActionBuilder() quanto this são possíveis aqui pois a classe implementa estas interfaces.

Consumindo a Fluent API

Agora podemos notar que ao tentar consumir nossa API, não conseguimos chamar o método WithName antes do Configure.

var workflow = GitHubActionBuilder
    .WithName("Build and Deploy")
    .Configure();

Somos obrigados a seguir a ordem correta de execução, conforme definimos nas interfaces previamente.

var workflow = GitHubActionBuilder
    .Configure()
    .WithName("Build and Deploy");

Conclusão

O C# é muito poderoso no quesito de organização e restrição de código. Podemos facilitar o consumo das nossas APIs já guiando os usuários para uma forma correta!

Populares

Priority Queue

Priority Queue ou fila prioritária é um tipo de lista inclusa no C# 10 que permite que seus itens...


Implicit Operators no C#

Implicit Operators permitem adicionar comportamentos de conversão a objetos Built In ou complexos...


ASP.NET 5 – Autenticação e Autorização com Bearer e JWT

Este artigo atualmente utiliza a versão 5.0.0-rc.1 do ASP.NET/.NET, o que significa que ainda não...


Clean Code - Guia e Exemplos

Saiba como manter seu código limpo (Clean Code) seguindo algumas práticas sugeridas pelo Robert C...


Git e GitHub - Instalação, Configuração e Primeiros Passos

Git é um sistema de controle de versões distribuídas, enquanto GitHub é uma plataforma que tem o ...


Compartilhe este artigo



Conheça o autor

André Baltieri

André Baltieri

Microsoft MVP

Me dedico ao desenvolvimento de software desde 2003, sendo minha maior especialidade o Desenvolvimento Web. Durante esta jornada pude trabalhar presencialmente aqui no Brasil e Estados Unidos, atender remotamente times da ?ndia, Inglaterra e Holanda, receber 8x Microsoft MVP e realizar diversas consultorias em empresas e projetos de todos os tamanhos.





3.133

Aulas disponíveis

292

horas de conteúdo

76.461

Alunos matriculados

53.012

Certificados emitidos





Comece de graça agora mesmo!

Temos mais de 21 cursos totalmente de graça e todos com certificado de conclusão.

Começar


Prefere algo mais Premium?

Conheça nossos planos



Premium anual

Compra única, parcelada em até
12x no cartão de crédito


12x R$

99

,79

=R$ 1.197,44
  • 1 ano de acesso
  • Acesso à todo conteúdo
  • Emissão de Certificado
  • Tira Dúvidas Online
  • 67 cursos disponíveis
  • 10 carreiras disponíveis
  • 161 temas de tecnologia
  • Conteúdo novo todo mês
  • Encontros Premium

Começar agora

Política de privacidade



Precisa de ajuda?

Dúvidas frequentes



  • Posso começar de graça?

    Sim! Basta criar sua conta gratuita no balta.io e começar seus estudos. Nós contamos com diversos cursos TOTALMENTE gratuitos e com certificado de conclusão.

  • Vou ter que pagar algo?

    Nós temos cursos gratuitos e pagos, porém você não precisa informar nenhum dado de pagamento para começar seus estudos gratuitamente conosco. Os cursos gratuitos são completos e com certificado de conclusão, você não paga nada por eles.

    Porém, caso queira algo mais Premium , você terá acesso à diversos benefícios que vão te ajudar ainda mais em sua carreira.

  • Por onde devo começar?

    Siga SEMPRE as nossas Carreiras , elas vão te orientar em todos os sentidos. Os cursos já estão organizados em categorias e carreiras para facilitar seu aprendizado.
    Nossa sugestão para aprendizado é começar pelo Backend e seguindo para Frontend e Mobile.

    • Backend
    • Frontend
    • Mobile

  • Os cursos ensinam tudo que preciso?

    Nenhum curso no mundo vai te ensinar tudo, desculpa ser sincero! Os cursos são uma base, eles fornecem por volta de 30% do que você precisa aprender, o resto é com você, com dedicação e MUITA prática.

  • O que eu devo estudar?

    Java ou .NET? Angular ou React? Xamarin ou Flutter? A resposta é simples e direta: "Você já sabe o básico?"

    Se você ainda não sabe BEM o básico, ou seja, os fundamentos, OOP, SOLID, Clean Code, está perdendo tempo estudando Frameworks ou até coisas mais avançadas como Docker. Foque nos seus objetivos primeiro.
    Agora se você está indeciso sobre qual Framework estudar, a boa notícia é que o mercado neste momento está bem aquecido e você tem várias oportunidade. Desta forma o que levaríamos em conta para tomar esta decisão seria:

    • Já sei o básico
    • O Framework/Tecnologia tem mercado onde eu estou (região)
    • O Framework/Tecnologia é utilizado em uma empresa onde quero atual
    • O Framework/Tecnologia resolve meu problema
    • Eu gosto de utilizar o Framework/Tecnologia

  • Estou pronto para estudar no balta.io?

    Com certeza! O primeiro passo é começar e você pode fazer isto agora mesmo!

    Começar de graça

Ainda tem dúvidas?





Assine nosso Newsletter

Receba em primeira mão todas as nossas novidades.

Cadastrar


balta.io

Sobre

  • Como funciona?
  • Seja Premium
  • Agenda
  • Blog
  • Todos os cursos

Cursos

  • Frontend
  • Backend
  • Mobile
  • Fullstack

Suporte

  • Termos de uso
  • Privacidade
  • Cancelamento
  • Central de ajuda

Redes Sociais

  • Telegram
  • Facebook
  • Instagram
  • YouTube
  • Twitch
  • LinkedIn
  • Discord