Skip to content

2. Controllers, actions, roteamento

Este capítulo examina o caminho percorrido por uma requisição, do navegador até a action que a processa, e a resposta que essa action devolve. As views só serão apresentadas no Capítulo 4: aqui, as actions devolvem texto ou JSON diretamente.

2.1. Exemplo 01: A estrutura de uma aplicação ASP.NET Core MVC

O primeiro exemplo é a menor aplicação [ASP.NET Core MVC] possível. Além dos arquivos [Example01.csproj] e [appsettings.json] apresentados na introdução, ele tem dois arquivos:

1
2
3
4
5
6
01-structure/
├── Controllers/
│   └── HomeController.cs
├── appsettings.json
├── Example01.csproj
└── Program.cs

2.1.1. O ponto de entrada: Program.cs

// o "builder" da aplicação: configuração, logging, serviços...
var builder = WebApplication.CreateBuilder(args);

// registra os serviços de que o MVC precisa para encontrar e executar os controllers
builder.Services.AddControllers();

// constrói a aplicação
var app = builder.Build();

// as rotas declaradas pelos controllers ([HttpGet("/")]...) são ativadas
app.MapControllers();

// inicia o servidor HTTP (http://localhost:5000 por padrão); Ctrl-C o encerra
app.Run();

Vamos analisar este código:

  • Linha 2: [WebApplication.CreateBuilder] cria o “construtor” da aplicação. Ele lê a configuração (o arquivo [appsettings.json], as variáveis de ambiente etc.), configura o log e prepara a lista de serviços da aplicação, [builder.Services]. O parâmetro [args] contém os argumentos da linha de comando;
  • linha 5: os serviços de que o [MVC] precisa para localizar os controllers da aplicação e executar suas actions são adicionados à lista;
  • linha 8: a aplicação é construída. Depois desta linha, a lista de serviços não pode mais ser modificada;
  • linha 11: as rotas declaradas pelos controllers (os atributos [[HttpGet]], [[Route]]..., sobre os quais falaremos) são habilitadas: sem esta linha, nenhuma action seria chamada;
  • linha 14: inicia o servidor web [Kestrel] e aguarda requisições até que a aplicação seja encerrada ([Ctrl-C]). Salvo indicação em contrário, o servidor escuta na porta 5000.

Este arquivo não contém nenhuma classe nem nenhum método chamado [Main]: é um programa de instruções de nível superior. O próprio compilador [C#] envolve essas instruções em um método chamado [Main], que serve de ponto de entrada do programa. Observe também a ausência de diretivas [using]: [WebApplication] pertence ao namespace [Microsoft.AspNetCore.Builder], que é importado automaticamente (veja [ImplicitUsings] na introdução).

2.1.2. O controller: Controllers/HomeController.cs

using Microsoft.AspNetCore.Mvc;

namespace Example01.Controllers;

// um controller é uma classe que herda de Controller
public class HomeController : Controller
{
    // uma action: o método chamado para a requisição GET /
    [HttpGet("/")]
    public string Index()
    {
        // o valor retornado pela action é a resposta enviada ao navegador
        return "Hello from ASP.NET Core MVC!";
    }
}
  • Linha 1: o namespace que contém a classe [Controller] e os atributos do [MVC];
  • linha 3: o namespace das classes deste arquivo. Por convenção, ele inclui o nome do projeto ([Example01]) e o diretório do arquivo ([Controllers]). A forma [namespace X;] (sem chaves) vale para o arquivo inteiro;
  • linha 6: um controller é uma classe public que herda da classe [Controller]. Por convenção, seu nome termina com [Controller]. O [ASP.NET Core] encontra automaticamente os controllers da aplicação — não é preciso declará-los;
  • linha 9: o atributo [[HttpGet("/")]] associa o método [Index] às requisições [GET /]. Um método associado dessa forma a uma rota é uma action. Um atributo [C#] é escrito entre colchetes, imediatamente antes do elemento que descreve: ele adiciona informações ao método, que o framework lê na inicialização;
  • Linha 13: o valor devolvido pela action é a resposta enviada ao navegador.

2.1.3. Execução

Em uma janela de terminal aberta no diretório [01-structure], digite [dotnet run]. Após a compilação, o servidor é iniciado:

1
2
3
4
5
6
7
8
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\course\examples\01-structure

As mensagens de inicialização indicam o endereço de escuta ([http://localhost:5000]) e o ambiente de execução: [Production], o ambiente padrão. Veremos que certos comportamentos do [ASP.NET Core] dependem do ambiente ([Development] ou [Production]). Vamos solicitar a URL [http://localhost:5000/] usando um navegador:

Image

e depois com o [curl]. A opção [-i] também exibe os cabeçalhos HTTP da resposta (mostramos aqui apenas alguns deles):

curl -i http://localhost:5000/
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Hello from ASP.NET Core MVC!

Uma string devolvida por uma action é enviada com o cabeçalho [Content-Type: text/plain]: o navegador a exibe como texto simples, sem interpretá-la. Isso difere do [NestJS], que a enviava como HTML ([text/html]). O Exemplo 03 mostrará como enviar HTML.

2.2. Exemplo 02: Roteamento

O roteamento associa uma URL e um método HTTP (GET, POST...) a uma action. O Exemplo 02 tem dois controllers:

1
2
3
4
5
6
7
02-routing/
├── Controllers/
│   ├── FirstController.cs
│   └── HomeController.cs
├── appsettings.json
├── Example02.csproj
└── Program.cs

O arquivo [Program.cs] é idêntico ao do Exemplo 01: isso vale para todos os exemplos deste capítulo, exceto o último. O arquivo [Controllers/HomeController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example02.Controllers;

public class HomeController : Controller
{
    // GET /: uma página HTML contendo links para as outras actions
    [HttpGet("/")]
    public ContentResult Index()
    {
        const string html = """
            <h2>Example 02 - routing</h2>
            <ul>
              <li><a href="/first">/first</a></li>
              <li><a href="/first/action01">/first/action01</a></li>
              <li><a href="/first/products/17">/first/products/17</a></li>
              <li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
              <li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
              <li><a href="/first/products/abc">/first/products/abc</a></li>
              <li><a href="/unknown">/unknown</a></li>
            </ul>
            """;
        // Content(text, type): uma resposta cujo tipo nós escolhemos (aqui, HTML)
        return Content(html, "text/html; charset=utf-8");
    }
}
  • linha 9: a action não devolve mais uma string, e sim um [ContentResult]: uma resposta cujo conteúdo e tipo são especificados;
  • linhas 11–22: uma string bruta [C#] ([raw string literal]), delimitada por três aspas. Ela pode se estender por várias linhas e conter aspas sem precisar escapá-las. Os espaços que precedem o ["""] de fechamento são removidos de cada linha;
  • linha 24: o método [Content(text, type)] da classe [Controller] gera um [ContentResult]. O tipo [text/html] instrui o navegador a interpretar o texto como HTML.

A action [Index] devolve, portanto, uma página HTML que contém links para as actions do outro controller:

Image

O arquivo [Controllers/FirstController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example02.Controllers;

// prefixo compartilhado por todas as rotas do controller
[Route("first")]
public class FirstController : Controller
{
    // GET /first
    [HttpGet("")]
    public string Index()
    {
        return "Action [Index] of the [First] controller";
    }

    // GET /first/action01
    [HttpGet("action01")]
    public string Action01()
    {
        return "Action [Action01] of the [First] controller, GET request";
    }

    // POST /first/action01: mesmo caminho, outro método HTTP
    [HttpPost("action01")]
    public string Action01Post()
    {
        return "Action [Action01Post] of the [First] controller, POST request";
    }

    // GET /first/products/17: {id} é um parâmetro de rota, ":int" uma restrição
    [HttpGet("products/{id:int}")]
    public string Product(int id)
    {
        return $"Product no. {id}";
    }

    // GET /first/products/17/reviews/3: dois parâmetros de rota
    [HttpGet("products/{id:int}/reviews/{number:int}")]
    public string Review(int id, int number)
    {
        return $"Review no. {number} of product no. {id}";
    }

    // GET /first/files/...: {**path} aceita qualquer final de caminho
    [HttpGet("files/{**path}")]
    public string File(string path)
    {
        return $"Requested file: {path}";
    }
}

Vamos analisar este código:

  • linha 6: o atributo [[Route("first")]], aplicado à classe, define o prefixo comum a todas as rotas do controller: suas actions tratam as rotas de URL que começam com [/first];
  • linhas 10–11: [[HttpGet("")]]: a action [Index] trata [GET /first]. A URL de uma action é a concatenação do prefixo do controller com o caminho da action;
  • linhas 17–18: a action [Action01] processa [GET /first/action01];
  • linhas 24–25: o mesmo caminho, mas para o método POST: [[HttpPost]] substitui [[HttpGet]]. Existem também [[HttpPut]], [[HttpDelete]], [[HttpPatch]]... O nome do método [C#] ([Action01Post]) é arbitrário: para o roteamento, só importam os atributos. Além disso, dentro da mesma classe, dois métodos não podem ter o mesmo nome com os mesmos parâmetros;
  • linhas 31–32: [{id}] é um parâmetro de rota: esse segmento da URL pode assumir vários valores. [:int] é uma restrição: o segmento deve ser um número inteiro; caso contrário, a rota não corresponde. O valor do segmento é passado ao parâmetro de mesmo nome da action, [id], já convertido para [int]: para [/first/products/17], [id] é igual ao número 17. Esse é o model binding ([model binding]), que o próximo capítulo examinará em detalhes;
  • linhas 38–39: dois parâmetros de rota, passados a dois parâmetros da action;
  • linhas 44–46: [{**path}] é um parâmetro "catch-all" ([catch-all]): aceita qualquer final de URL, inclusive [/].

Eis os resultados de algumas requisições:

curl -i http://localhost:5000/first
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Action [Index] of the [First] controller
curl -i http://localhost:5000/first/action01
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Action [Action01] of the [First] controller, GET request
curl -i http://localhost:5000/first/products/17
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Product no. 17
curl -i http://localhost:5000/first/products/17/reviews/3
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Review no. 3 of product no. 17
curl -i http://localhost:5000/first/files/images/logo.png
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Requested file: images/logo.png

Para enviar uma requisição POST, use a opção [-X POST] do [curl]:

curl -i -X POST http://localhost:5000/first/action01
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Action [Action01Post] of the [First] controller, POST request

Um método HTTP que não é tratado por nenhuma action para esse caminho resulta em um erro 405 ([Method Not Allowed]). O cabeçalho [Allow] lista os métodos aceitos:

curl -i -X PUT http://localhost:5000/first/action01
1
2
3
HTTP/1.1 405 Method Not Allowed
Content-Length: 0
Allow: GET, POST

Por fim, uma URL que nenhuma rota trata resulta em um erro 404. É também o caso de um identificador que não atende à restrição [:int]: nenhuma rota corresponde a [/first/products/abc].

curl -i http://localhost:5000/first/products/abc
HTTP/1.1 404 Not Found
Content-Length: 0
curl -i http://localhost:5000/unknown
HTTP/1.1 404 Not Found
Content-Length: 0

A resposta 404 do [ASP.NET Core] não tem conteúdo ([Content-Length: 0]): o navegador exibe a própria página de erro.

Image

O Capítulo 7 mostrará como substituir essa resposta vazia por uma página HTML.

2.3. Exemplo 03: Respostas de uma action

O que uma action devolve determina a resposta HTTP. O Exemplo 03 revê os principais casos. O arquivo [Controllers/ResponsesController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example03.Controllers;

[Route("responses")]
public class ResponsesController : Controller
{
    // uma string: enviada como está, com o tipo [text/plain]
    [HttpGet("text")]
    public string Text()
    {
        return "<h1>Action [Text]</h1>";
    }

    // a mesma string, anunciada como HTML: o navegador a interpreta
    [HttpGet("html")]
    public ContentResult Html()
    {
        return Content("<h1>Action [Html]</h1>", "text/html; charset=utf-8");
    }

    // um objeto: serializado em JSON, com o tipo [application/json]
    [HttpGet("json")]
    public object Json()
    {
        return new { lastName = "Martin", firstName = "Jean", age = 42 };
    }

    // um array: também serializado em JSON
    [HttpGet("array")]
    public string[] Array()
    {
        return ["Mme", "Melle", "Mr"];
    }

    // IActionResult: a action escolhe a resposta completa (código, conteúdo)
    // StatusCode(201, ...): o código 201 (Created) em vez de 200 (OK)
    [HttpGet("created")]
    public IActionResult ResourceCreated()
    {
        return StatusCode(201, new { message = "resource created" });
    }

    // sem resposta: o código 204 (No Content) significa "nada a exibir"
    [HttpGet("empty")]
    public IActionResult EmptyResponse()
    {
        return NoContent();
    }

    // uma action assíncrona: o ASP.NET espera o fim da tarefa (Task)
    [HttpGet("task")]
    public async Task<object> AsyncTask()
    {
        var start = DateTime.Now;
        await Task.Delay(500); // uma espera de 500 ms, sem bloquear o servidor
        return new { wait = $"{(DateTime.Now - start).TotalMilliseconds:0} ms" };
    }

    // um erro "esperado": NotFound(...) produz uma resposta 404
    [HttpGet("not-found")]
    public IActionResult NotFoundError()
    {
        return NotFound(new { message = "This resource does not exist" });
    }

    // um erro "inesperado": uma exceção não tratada produz uma resposta 500
    [HttpGet("exception")]
    public string Exception()
    {
        throw new InvalidOperationException("An unexpected error");
    }
}

Vamos analisar este código:

  • linhas 9–12: uma string é enviada como está, com o cabeçalho [Content-Type: text/plain; charset=utf-8];
  • linhas 16–19: a mesma string, declarada como HTML (veja o Exemplo 02): o navegador a interpreta;
  • linhas 23–26: um objeto é serializado como JSON, com o cabeçalho [Content-Type: application/json]. [new { lastName = ..., firstName = ... }] cria um objeto de um tipo anônimo: um tipo sem nome gerado pelo compilador, útil para dados usados uma única vez. Os nomes das propriedades do JSON são escritos em “camelCase” (primeira letra minúscula), seguindo a convenção do [JavaScript];
  • linhas 30–33: um array também é serializado como JSON. [["Mme", "Melle", "Mr"]] é uma expressão de coleção ([C#] 12), que aqui cria um array de strings;
  • linhas 39–41: quando a action precisa escolher o código de status, ela devolve um [IActionResult]: um objeto que descreve a resposta completa. Os métodos da classe [Controller] geram muitos deles: [StatusCode(201, object)] produz uma resposta de código 201 ([Created]) cujo conteúdo é o objeto serializado em JSON;
  • linhas 46–48: [NoContent()] devolve o código de status 204 ([No Content]): “sem conteúdo”;
  • linhas 53–57: uma action pode ser assíncrona ([async]): ela então devolve uma tarefa ([Task<T>]), o equivalente a uma promise ([JavaScript]), e o [ASP.NET Core] espera a conclusão da tarefa antes de responder. [await Task.Delay(500)] espera 500 ms sem bloquear o servidor: durante a espera, a thread que executava a action é devolvida ao servidor, que pode usá-la para processar outras requisições. É assim que se escrevem todas as actions que consultam um banco de dados;
  • linhas 62–64: um erro previsto pelo programa: [NotFound(object)] devolve uma resposta 404 com conteúdo JSON. Da mesma forma, existem [BadRequest(...)] (400), [Unauthorized()] (401), [Forbid()] (403), [Ok(...)] (200)...;
  • linhas 69–71: um erro inesperado: a action lança uma exceção, que ela não trata. O [ASP.NET Core] responde então com um erro 500 ([Internal Server Error]).

Respostas recebidas:

curl -i http://localhost:5000/responses/text
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

<h1>Action [Text]</h1>
curl -i http://localhost:5000/responses/html
1
2
3
4
5
HTTP/1.1 200 OK
Content-Length: 22
Content-Type: text/html; charset=utf-8

<h1>Action [Html]</h1>
curl -i http://localhost:5000/responses/json
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"lastName":"Martin","firstName":"Jean","age":42}
curl -i http://localhost:5000/responses/array
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

["Mme","Melle","Mr"]
curl -i http://localhost:5000/responses/created
1
2
3
4
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{"message":"resource created"}
curl -i http://localhost:5000/responses/empty
HTTP/1.1 204 No Content
curl -i http://localhost:5000/responses/task
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"wait":"514 ms"}
curl -i http://localhost:5000/responses/not-found
1
2
3
4
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"message":"This resource does not exist"}
curl -i http://localhost:5000/responses/exception
HTTP/1.1 500 Internal Server Error
Content-Length: 0

Nesse caso de exceção, a resposta não fornece nenhuma informação sobre o erro: os detalhes poderiam ajudar um invasor. Eles são registrados no console do servidor (reproduzimos aqui apenas o início):

1
2
3
4
5
fail: Microsoft.AspNetCore.Server.Kestrel[13]
      Connection id "0HNP6TN0D56ES", Request id "0HNP6TN0D56ES:00000001": An unhandled exception was thrown by the application.
      System.InvalidOperationException: An unexpected error
         at Example03.Controllers.ResponsesController.Exception() in ...\03-responses\Controllers\ResponsesController.cs:line 71
         ...

Em um navegador, a diferença entre [text/plain] e [text/html] é visível:

Image

Image

2.4. Exemplo 04: Redirecionamentos

Uma action pode responder com um redirecionamento: um código de status 301 ou 302 e um cabeçalho [Location] que informa ao navegador qual URL solicitar em seguida. O navegador a solicita imediatamente, sem nenhuma intervenção do usuário. Os redirecionamentos são onipresentes em uma aplicação web: após o envio bem-sucedido de um formulário, após o login, após a troca de idioma...

O arquivo [Controllers/RedirectsController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example04.Controllers;

public class RedirectsController : Controller
{
    // redirecionamento permanente (301): a página mudou de endereço definitivamente
    [HttpGet("old")]
    public IActionResult OldPage()
    {
        return RedirectPermanent("/new");
    }

    [HttpGet("new")]
    public string NewPage()
    {
        return "You are on the [new] page";
    }

    // redirecionamento temporário (302), para um endereço calculado
    [HttpGet("go/{destination}")]
    public IActionResult Go(string destination)
    {
        return Redirect($"/page/{destination}");
    }

    // redirecionamento para uma ACTION: o ASP.NET constrói a URL por conta própria
    [HttpGet("to-action/{destination}")]
    public IActionResult ToAction(string destination)
    {
        return RedirectToAction(nameof(Page), new { name = destination });
    }

    [HttpGet("page/{name}")]
    public string Page(string name)
    {
        return $"You are on the [{name}] page";
    }

    // redirecionamento para outro site
    [HttpGet("documentation")]
    public IActionResult Documentation()
    {
        return Redirect("https://learn.microsoft.com/aspnet/core");
    }
}

Vamos analisar este código:

  • linhas 9–11: [RedirectPermanent(url)] gera um redirecionamento permanente (código de status 301, [Moved Permanently]): o endereço da página mudou definitivamente. Navegadores e mecanismos de busca podem armazenar o novo endereço em cache;
  • linhas 22–24: [Redirect(url)] gera um redirecionamento temporário (código de status 302, [Found]), neste caso para um endereço calculado. [$"/page/{destination}"] é uma string interpolada: a expressão entre chaves é substituída pelo seu valor;
  • linhas 29–31: [RedirectToAction(action, values)] redireciona para uma action, não para uma URL: o [ASP.NET Core] mesmo gera a URL da action [Page] com base em sua rota ([page/{name}]) e nos valores fornecidos ([name = destination]). Se o caminho da action mudar um dia, o redirecionamento o acompanha. [nameof(Page)] devolve o nome do método (["Page"]): um erro de digitação causaria um erro de compilação, o que não acontece com uma string escrita à mão;
  • linhas 42–44: é possível redirecionar para outro site.

O [curl] mostra o redirecionamento sem segui-lo:

curl -i http://localhost:5000/old
1
2
3
HTTP/1.1 301 Moved Permanently
Content-Length: 0
Location: /new

Com a opção [-L], o [curl] segue o redirecionamento, exatamente como um navegador. Vemos então as duas respostas sucessivas:

curl -i -L http://localhost:5000/old
1
2
3
4
5
6
7
8
HTTP/1.1 301 Moved Permanently
Content-Length: 0
Location: /new

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

You are on the [new] page
curl -i http://localhost:5000/go/contact
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: /page/contact
curl -i http://localhost:5000/to-action/contact
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: /page/contact

As duas actions resultam no mesmo redirecionamento: uma com uma URL escrita à mão, a outra com uma URL gerada pelo [ASP.NET Core]. No navegador, só a página final é visível; a barra de endereços exibe a nova URL:

Image

curl -i http://localhost:5000/documentation
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: https://learn.microsoft.com/aspnet/core

2.5. Exemplo 05: Os objetos de requisição e de resposta

Cada requisição é representada por um objeto [HttpContext], que contém a requisição ([Request]) e a resposta que está sendo gerada ([Response]). Uma action acessa esse objeto diretamente pelas propriedades [HttpContext], [Request] e [Response] da classe [Controller]. Isso às vezes é necessário, e o faremos no estudo de caso (para ler ou definir um cookie, por exemplo), mas é preciso saber o que se está fazendo.

O arquivo [Controllers/HttpController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example05.Controllers;

[Route("http")]
public class HttpController : Controller
{
    // a requisição: método, caminho, parâmetros, cabeçalhos...
    [HttpGet("request")]
    public object RequestInfo()
    {
        return new
        {
            method = Request.Method,
            path = Request.Path.Value,
            parameters = Request.QueryString.Value,
            browser = Request.Headers.UserAgent.ToString(),
            ip = HttpContext.Connection.RemoteIpAddress?.ToString(),
        };
    }

    // a resposta: adicionamos um cabeçalho a ela e depois a action retorna seu valor normalmente
    [HttpGet("header")]
    public string Header()
    {
        Response.Headers["X-Example"] = "05-httpcontext";
        return "Response with an added header";
    }

    // a resposta escrita "à mão": código, tipo e depois o corpo
    [HttpGet("response")]
    public async Task ResponseByHand()
    {
        Response.StatusCode = 200;
        Response.ContentType = "text/plain; charset=utf-8";
        await Response.WriteAsync("Response written by [Response.WriteAsync]");
    }

    // ERRO a não cometer: escrever a resposta E DEPOIS retornar um resultado
    [HttpGet("double")]
    public async Task<IActionResult> Double()
    {
        await Response.WriteAsync("Start of the response... ");
        // a resposta já saiu: seu código e seus cabeçalhos não podem mais mudar
        return NotFound();
    }
}

Vamos analisar este código:

  • linhas 10–18: a requisição: o método HTTP ([Request.Method]), o caminho ([Request.Path]), os parâmetros da URL ([Request.QueryString]), os cabeçalhos ([Request.Headers]) e, por meio de [HttpContext.Connection], o endereço (IP) do cliente. [?.] é o operador “condicional nulo”: se [RemoteIpAddress] for igual a [null], a expressão é avaliada como [null] em vez de causar um erro;
  • linhas 24–27: a action adiciona um cabeçalho à resposta e depois devolve normalmente o valor dela, que o [ASP.NET Core] envia. É o uso mais comum de [Response];
  • linhas 32–36: a action escreve a resposta por conta própria — código de status, tipo e, em seguida, o corpo — usando [Response.WriteAsync]. Ela não devolve nada ([Task], e não [Task<T>]);
  • linhas 41–45: o erro a evitar: escrever parte da resposta e depois devolver um resultado. Depois que os primeiros bytes do corpo foram enviados ao navegador, o código de status e os cabeçalhos — que foram enviados antes do corpo — não podem mais ser alterados.

As respostas obtidas:

curl -i -A "Mozilla/5.0 (example)" "http://localhost:5000/http/request?name=martin"
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"method":"GET","path":"/http/request","parameters":"?name=martin","browser":"Mozilla/5.0 (example)","ip":"127.0.0.1"}

(A opção [-A] do [curl] define o cabeçalho [User-Agent], que identifica o navegador)

curl -i http://localhost:5000/http/header
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-Example: 05-httpcontext

Response with an added header
curl -i http://localhost:5000/http/response
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Response written by [Response.WriteAsync]
curl -i http://localhost:5000/http/double
1
2
3
HTTP/1.1 200 OK

Start of the response... 

Na última action, o navegador recebe o código de status 200 e o início da resposta, em vez do 404 solicitado. O console do servidor registra o erro:

1
2
3
4
fail: Microsoft.AspNetCore.Server.Kestrel[13]
      Connection id "0HNP6TN1VG5OL", Request id "0HNP6TN1VG5OL:00000001": An unhandled exception was thrown by the application.
      System.InvalidOperationException: StatusCode cannot be set because the response has already started.
      ...

No restante do documento, as actions quase sempre devolverão um resultado ([IActionResult]) e deixarão que o [ASP.NET Core] escreva a resposta. [Request] e [Response] só serão usados para ler a requisição e definir cookies.

2.6. Exemplo 06: Serviços e injeção de dependência

Os controllers não devem conter lógica de aplicação; eles a delegam a serviços. Um serviço é um objeto comum que o [ASP.NET Core] cria e fornece às classes que precisam dele: é a injeção de dependência. O Exemplo 06 divide uma pequena aplicação em duas partes: produtos e clientes:

06-services/
├── Clients/
│   └── ClientsController.cs
├── Products/
│   ├── IProductsService.cs
│   ├── Product.cs
│   ├── ProductsController.cs
│   ├── ProductsExtensions.cs
│   └── ProductsService.cs
├── appsettings.json
├── Example06.csproj
└── Program.cs

2.6.1. O Product

1
2
3
4
namespace Example06.Products;

// um "record": uma classe de dados cujas propriedades são definidas pelo construtor
public record Product(int Id, string Name, decimal Price);

Um record: uma classe de dados declarada em uma única linha. O compilador cria as propriedades [Id], [Name] e [Price], um construtor que as inicializa e métodos utilitários (comparação, exibição). O tipo [decimal] representa valores monetários sem erros de arredondamento.

2.6.2. O contrato do serviço: IProductsService

1
2
3
4
5
6
7
8
namespace Example06.Products;

// o CONTRATO do serviço: o que ele sabe fazer, sem dizer como
public interface IProductsService
{
    IReadOnlyList<Product> FindAll();
    Product? FindById(int id);
}
  • Linha 4: uma interface descreve o que o serviço pode fazer, sem especificar como. As classes que usam o serviço conhecerão apenas essa interface;
  • linha 6: [IReadOnlyList<Product>]: uma lista que o chamador pode ler, mas não modificar;
  • linha 7: [Product?]: um produto ou [null] se nenhum produto tiver esse identificador (veja [Nullable] na introdução).

2.6.3. A implementação: ProductsService

namespace Example06.Products;

// uma IMPLEMENTAÇÃO do contrato: aqui, dados em memória
public class ProductsService : IProductsService
{
    private readonly List<Product> products =
    [
        new Product(1, "pen", 1.5m),
        new Product(2, "notebook", 3.2m),
        new Product(3, "eraser", 0.8m),
    ];

    public IReadOnlyList<Product> FindAll() => products;

    public Product? FindById(int id) => products.FirstOrDefault(p => p.Id == id);
}
  • linha 4: a classe implementa a interface: ela deve fornecer todos os métodos dela;
  • linhas 6–11: os dados, aqui em memória, em uma lista inicializada por uma expressão de coleção;
  • linhas 13–15: os dois métodos, escritos com a sintaxe [=>] (um método cujo corpo é uma única expressão). [FirstOrDefault] ([LINQ]) devolve o primeiro resultado que satisfaz a condição ou [null] se não houver nenhum.

2.6.4. O controller ProductsController

using Microsoft.AspNetCore.Mvc;

namespace Example06.Products;

[Route("products")]
public class ProductsController : Controller
{
    private readonly IProductsService productsService;

    // injeção de dependência: o ASP.NET fornece a implementação de IProductsService
    public ProductsController(IProductsService productsService)
    {
        this.productsService = productsService;
    }

    [HttpGet("")]
    public IReadOnlyList<Product> List()
    {
        return productsService.FindAll();
    }

    [HttpGet("{id:int}")]
    public IActionResult OneProduct(int id)
    {
        var product = productsService.FindById(id);
        if (product is null)
        {
            return NotFound(new { message = $"Product no. {id} not found" });
        }
        return Ok(product);
    }
}
  • linhas 11–13: injeção de dependência. O controller declara, em seu construtor, que precisa de um [IProductsService]; o [ASP.NET Core] fornece a ele o objeto registrado para esse tipo (veja abaixo). O controller nunca chama [new ProductsService()]: ele nem sequer conhece essa classe, apenas a interface. A implementação poderia ser substituída (por uma versão que lê um banco de dados ou por uma versão de teste) sem modificar o controller;
  • linhas 17–19: a action delega ao serviço. A lista é serializada em JSON;
  • linhas 23–30: [{id:int}] converte o identificador; um produto inexistente devolve uma resposta 404. [Ok(object)] devolve uma resposta 200 cujo conteúdo é o objeto serializado em JSON. [is null] verifica se um valor é nulo.

2.6.5. O controller ClientsController

using Example06.Products;
using Microsoft.AspNetCore.Mvc;

namespace Example06.Clients;

// "construtor primário" (C# 12): o parâmetro do construtor é escrito
// logo após o nome da classe e pode ser usado em toda a classe
[Route("clients")]
public class ClientsController(IProductsService productsService) : Controller
{
    [HttpGet("cart")]
    public object Cart()
    {
        var products = productsService.FindAll();
        return new { client = "Jean Martin", items = products.Count, total = products.Sum(p => p.Price) };
    }
}
  • linha 9: um construtor primário ([C#] 12): o parâmetro do construtor é escrito logo após o nome da classe. Ele pode ser usado em toda a classe: não é preciso copiá-lo para um campo. É a forma mais compacta de injeção de dependência; ela será usada no restante deste documento. O [ClientsController] recebe o mesmo serviço que o [ProductsController];
  • linhas 12–15: ele o usa para calcular o total de um carrinho de compras. [Sum] ([LINQ]) soma os preços.

2.6.6. Registro dos serviços

O [ASP.NET Core] só pode fornecer um serviço se o conhecer: cada serviço é registrado em [builder.Services], junto com seu tempo de vida. O arquivo [Products/ProductsExtensions.cs]:

namespace Example06.Products;

// um "método de extensão": é chamado como se fizesse parte de
// IServiceCollection (builder.Services.AddProducts()). Ele agrupa os
// registros da parte "produtos" da aplicação.
public static class ProductsExtensions
{
    public static IServiceCollection AddProducts(this IServiceCollection services)
    {
        // "quando um IProductsService for solicitado, forneça um ProductsService";
        // Singleton: uma única instância, compartilhada por todas as requisições
        services.AddSingleton<IProductsService, ProductsService>();
        return services;
    }
}
  • linha 6: uma classe estática, que contém apenas métodos estáticos;
  • linha 8: um método de extensão. A palavra-chave [this] antes do primeiro parâmetro permite chamá-lo como se fizesse parte do tipo desse parâmetro: [builder.Services.AddProducts()]. É assim que as bibliotecas do [ASP.NET Core] adicionam seus serviços ([AddControllers], [AddAuthentication]...), e é uma boa maneira de agrupar os registros de uma parte específica da aplicação;
  • linha 12: “quando uma classe solicitar um [IProductsService], forneça a ela um [ProductsService].” [Singleton] é o tempo de vida do serviço: uma única instância, criada na primeira requisição e compartilhada por todas as requisições. Existem outros dois tempos de vida: [Scoped] (uma instância por requisição) e [Transient] (uma nova instância a cada solicitação). O Capítulo 6 voltará a este assunto;
  • linha 13: o método devolve a lista de serviços para que as chamadas possam ser encadeadas.

O arquivo [Program.cs]:

using Example06.Products;

var builder = WebApplication.CreateBuilder(args);

// os serviços do MVC
builder.Services.AddControllers();
// os serviços da parte "produtos" (veja Products/ProductsExtensions.cs)
builder.Services.AddProducts();

var app = builder.Build();
app.MapControllers();
app.Run();
  • linha 1: o namespace do método de extensão;
  • linha 8: o registro do serviço de produtos.

Os controllers, por sua vez, não são registrados individualmente: [AddControllers] os encontra todos, e o [ASP.NET Core] cria um novo objeto controller a cada requisição, injetando nele os serviços que ele solicita.

2.6.7. Execução

curl -i http://localhost:5000/products
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[{"id":1,"name":"pen","price":1.5},{"id":2,"name":"notebook","price":3.2},{"id":3,"name":"eraser","price":0.8}]
curl -i http://localhost:5000/products/2
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":2,"name":"notebook","price":3.2}
curl -i http://localhost:5000/products/9
1
2
3
4
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"message":"Product no. 9 not found"}
curl -i http://localhost:5000/clients/cart
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"client":"Jean Martin","items":3,"total":5.5}

O estudo de caso é estruturado exatamente assim: controllers enxutos que delegam a serviços injetados, descritos por interfaces e registrados em [Program.cs].