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:
2.1.1. O ponto de entrada: Program.cs
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
- 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:
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:

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

O arquivo [Controllers/FirstController.cs]:
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:
Para enviar uma requisição POST, use a opção [-X POST] do [curl]:
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:
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].
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.

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]:
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:
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):
Em um navegador, a diferença entre [text/plain] e [text/html] é visível:


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]:
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:
Com a opção [-L], o [curl] segue o redirecionamento, exatamente como um navegador. Vemos então as duas respostas sucessivas:
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:

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]:
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:
(A opção [-A] do [curl] define o cabeçalho [User-Agent], que identifica o navegador)
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:
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:
2.6.1. O Product
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
- 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
- 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
- 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
- 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]:
- 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]:
- 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
O estudo de caso é estruturado exatamente assim: controllers enxutos que delegam a serviços injetados, descritos por interfaces e registrados em [Program.cs].