1. O que é e para que serve

Carter é um framework leve e de alto desempenho para criar APIs HTTP na plataforma ASP.NET Core. Inspirado pelo popular framework NancyFX, ele oferece aos desenvolvedores uma abordagem declarativa e familiar para roteamento e tratamento de requisições. Diferente do MVC (Model-View-Controller) tradicional, o Carter permite definir endpoints diretamente no código, sem a necessidade de criar controllers separados ou configurar roteamentos complexos.

Por que usar o Carter? O principal motivo é a simplicidade e agilidade no desenvolvimento. Se você precisa criar rapidamente uma API mínima ou um microsserviço, o Carter oferece uma sintaxe concisa que reduz o código boilerplate. Ele é ideal para projetos que não exigem toda a potência do MVC, mas precisam de flexibilidade e facilidade para lidar com requisições e respostas. O Carter também se integra perfeitamente com o ASP.NET Core, utilizando seu container de injeção de dependência, middleware e outros recursos nativos.

Os principais recursos do Carter incluem: vinculação automática de parâmetros de rota e corpo da requisição (model binding), suporte nativo a validação, tratamento simplificado de erros e a possibilidade de testar endpoints facilmente. O framework é ativamente mantido pela comunidade e utilizado em produção por diversas empresas.

2. Instalação

Para instalar o Carter no seu projeto ASP.NET Core, use o gerenciador de pacotes NuGet. Execute um dos seguintes comandos no terminal:

dotnet add package Carter

ou pelo console do gerenciador de pacotes do Visual Studio:

Install-Package Carter

Após a instalação, é necessário registrar o Carter no seu arquivo Program.cs (ou Startup.cs em versões antigas):

using Carter;

var builder = WebApplication.CreateBuilder(args);

// Adiciona o Carter ao container de DI
builder.Services.AddCarter();

var app = builder.Build();

// Habilita o middleware do Carter
app.MapCarter();

app.Run();

Observação: nas versões modernas do .NET (6+), a API mínima é usada, mas o Carter ainda é relevante para lógicas mais complexas.

3. Início rápido — exemplo funcional mínimo

Crie um novo projeto ASP.NET Core (vazio ou Web API). Instale o Carter conforme descrito acima. Em seguida, crie uma classe que implemente a interface ICarterModule:

using Carter;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;

public class HomeModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        // Define um endpoint GET no caminho "/"
        app.MapGet("/", () => "Olá do Carter!");
        
        // Define um endpoint GET com parâmetro
        app.MapGet("/hello/{name}", (string name) => $"Olá, {name}!");
    }
}

Agora registre este módulo no Program.cs:

using Carter;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCarter();
var app = builder.Build();
app.MapCarter();
app.Run();

Execute a aplicação e acesse http://localhost:5000/hello/Mundo. Você verá a resposta: Olá, Mundo!.

4. Principais métodos/funções/classes

Vamos explorar os elementos-chave do Carter que você usará com mais frequência.

4.1. ICarterModule

ICarterModule é a interface principal que você implementa para definir seus endpoints. Cada módulo agrupa rotas relacionadas, mantendo o código organizado. O método AddRoutes recebe um IEndpointRouteBuilder, onde você mapeia seus endpoints usando métodos como MapGet, MapPost, MapPut, MapDelete, etc.