ASP .NET Core 6 - Criando Minimal APIs - I

Hoje veremos o novo recurso para criação de Minimal APIs disponível a partir do .NET 6.0 para projetos ASP .NET Core 6.

O novo recurso do .NET 6.0 - Minimal APIs - para a ASP .NET Core 6 permite, criar APIs com o mínimo de dependência do framework WebAPI e o mínimo de código e arquivos necessários para o desenvolvimento minimalista de APIs.

Agora a ASP .NET Core segue outras tecnologias como GO, Python e Node.js que já permitiam a criação de APIs com o mínimo de código e dependências.

Como principais objetivos as Minimals APIs da plataforma .NET permitem :

Não há nenhum template ASP.NET Core específico para construir uma API mínima, para isso você pode simplesmente usar o template “ASP.NET Core Empty” para criar seu projeto no VS 2022:

Ou emitir o comando :   dotnet new web -o MinApi  na ferramenta de linha de comando .NET CLI.

Criando o projeto no VS 2022, a seguir basta informar o nome do projeto :

Selecionar o Framework .NET 6.0 (que atualmente esta em RC1) e clicar em Create :

E a solução será criada com a seguinte estrutura :

Observe que temos apenas o arquivo appsettings.json e o arquivo Program e a pasta Properties.

Abrindo o arquivo Program temos um código simplificado usando o recurso do Top Level Statements do C# 9.0.

Na verdade podemos simplificar ainda mais o código criando uma API com apenas 3 linhas de código:

var a = WebApplication.Create(args);
a.MapGet("/", () => "Bem-Vindo a Minimal APIs");
a.Run();
 

A inicialização ficou mais simples graças ao novo tipo - Microsoft.AspNetCore.Builder.WebApplication - cujo objetivo é configurar de forma simples e objetiva um aplicativo web, e podemos usar este recursos para fazer quase tudo que você precisa para uma Web API :  configuração de acesso, configurar o contêiner de injeção de dependência, configurar o pipeline do aplicativo registrando componentes de middleware e para iniciar o ouvinte HTTP.

Assim, WebApplication unifica os recursos de IApplicationBuilder, IHost e IEndpointRouteBuilder ao mesmo tempo e, junto com seus próprios recursos, tem acesso a todos os métodos de extensão integrados e de terceiros para essas interfaces.

Graças às instruções de nível superior, podemos executar um programa sem usar uma declaração de namespace, uma declaração de classe ou mesmo um método Main(string [] args). Só com isso temos uma economia de nove linhas de código. Mesmo sem o método Main, ainda podemos inferir argumentos - o compilador cuida disso para você.

Observe que não existem declarações using, e, isso ocorre porque, por padrão no .NET 6, o ASP.NET Core esta usando o novo recurso do Global Usings - uma nova maneira de declarar seus usings em um único arquivo, evitando a necessidade de declará-los em arquivos de origem individuais.

O uso do recurso Global Using do  C# 10, permite que os usings sejam controlados por meio do MSBuild  do projeto SDK e o usings implícitos para o projeto Web SDK são:

System.Net.Http.Json
Microsoft.AspNetCore.Builder
Microsoft.AspNetCore.Hosting
Microsoft.AspNetCore.Http
Microsoft.AspNetCore.Routing
Microsoft.Extensions.Configuration
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.Hosting
Microsoft.Extensions.Logging
 

Assim todos os namespaces abaixo não precisam ser importados manualmente e código pode usá-los de forma implícita:

System
System.Collections.Generic
System.IO
System.Linq
System.Net.Http
System.Threading
System.Threading.Tasks
 

Se examinarmos o arquivo de projeto MinApi.csproj teremos o seguinte:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

No arquivo de projeto vemos a propriedade ImplicitUsings definida como enable e assim as diretivas Global Usings são adicionadas. (A partir das próximas versões este recurso não será implicitamente ativado para evitar problemas de compatibilidade com versões anteriores)

O código também usa os métodos de extensão auxiliares Map{verb} para configurar os endpoints. Este recurso estava presente no .NET 5, mas agora eles dão suporte ao model binding, a integração com a injeção de dependência e acessam facilmente os dados da rota, o que torna a sua utilização mais completa.

Além disso o uso dos novos recursos das expressões lambdas no C# 10 que agora podem:

Resolvem muitos problemas encontrados anteriormente no uso das expressões lambdas para definir endpoints em uma API HTTP e permite simplificar bastante o código.

Executando o projeto teremos o resultado abaixo:

O arquivo Startup.cs desapareceu, apenas o arquivo Program.cs e os arquivos appsettings.json permanecem.

Assim temos que as APIs mínimas são uma mistura simplificada entre:

- Recursos do Top Level Statements do C# 9;
- O recurso Route-to-code disponível a partir da ASP.NET Core 3;
- E onde a configuração do aplicativo ASP.NET Core foi movida do arquivo Startup.cs para o arquivo Program.cs;

Esta é uma API .NET totalmente desenvolvida, sem DI, sem objetos de configuração e tudo em um único arquivo.

E isso fornece um ponto de partida muito mais leve para qualquer API que precise fazer apenas uma coisa, e é este realmente o objetivo dessas APIs : simplicidade e objetividade.

Naturalmente, podemos adicionar terminais adicionais, adicionar lógica, retornar tipos complexos (que serão convertidos para JSON como é padrão).

Veremos a seguir como incluir alguns recursos no projeto MinApi criado no VS 2022.

Habilitando o Swagger

A título de exemplo vamos incluir habilitar o Swagger nesta API incluindo no projeto uma referência ao pacote : Swashbuckle.AspNetCore

A seguir vamos alterar o código do arquivo Program para:

Executando novamente o projeto e navegando para o endpoint  /swagger teremos:

Trabalhando com Models

Vamos agora usar outro novo recurso disponível com C# 9.0 , o recurso Record.

Com apenas uma linha de código adicional, podemos trabalhar com um Record de Cliente. Lembrando que Record são tipos de referência que usam igualdade baseada em valor e ajudam a impor a imutabilidade. Com parâmetros posicionais, você pode declarar um modelo em apenas uma linha de código.

Executando o projeto e acionando o endpoint /swagger teremos:

Usando HttpClient

Agora veremos como usar o recurso HttpClient para consumir APIs por conta própria.

Como exemplo vamos usar o JSONPlaceholder que é um serviço REST on-line gratuito que você pode usar sempre que precisar de alguns dados para exibir em suas aplicações. É ótimo para ser usado em tutoriais e simula um servidor, compartilhando exemplos de código.

Você pode simular requisições HTTP com GET, POST, PUT e DELETE e não precisa registro.

Assim vamos usar o HttpClient para acessar os dados do serviço REST em https://jsonplaceholder.typicode.com/ no formato JSON.

Temos os seguintes recursos disponíveis :

Eu vou acessar o endpoint albums.

Vamos alterar o código no arquivo Program para:

Executando o projeto e acionando o endpoint /swagger teremos o resultado:

Na outra parte do artigo veremos como usar outros recursos nas APIs mínimas.

Pegue o projeto exemplo aqui:  MinApi.zip (sem as referências)

"Bendito o Deus e Pai de nosso Senhor Jesus Cristo, o qual nos abençoou com todas as bênçãos espirituais nos lugares celestiais em Cristo;  Como também nos elegeu nele antes da fundação do mundo, para que fôssemos santos e irrepreensíveis diante dele em amor;"
Efésios 1:3,4

Referências:

José Carlos Macoratti