Skip to content

2. Controladores, acciones, enrutamiento

Este capítulo examina el camino que sigue una solicitud, desde el navegador hasta la acción que la procesa, y la respuesta que esa acción devuelve. Las vistas no se introducirán hasta el capítulo 4: aquí, las acciones devuelven texto o JSON directamente.

2.1. Ejemplo 01: La estructura de una aplicación ASP.NET Core MVC

El primer ejemplo es la aplicación [ASP.NET Core MVC] más pequeña posible. Además de los archivos [Example01.csproj] y [appsettings.json] presentados en la introducción, tiene dos archivos:

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

2.1.1. El punto de entrada: Program.cs

// el "builder" de la aplicación: configuración, registro de logs, servicios...
var builder = WebApplication.CreateBuilder(args);

// registrar los servicios que MVC necesita para encontrar y ejecutar los controladores
builder.Services.AddControllers();

// construir la aplicación
var app = builder.Build();

// se habilitan las rutas declaradas por los controladores ([HttpGet("/")]...)
app.MapControllers();

// iniciar el servidor HTTP (http://localhost:5000 por defecto); Ctrl-C lo detiene
app.Run();

Analicemos este código:

  • Línea 2: [WebApplication.CreateBuilder] crea el “constructor” de la aplicación. Lee la configuración (el archivo [appsettings.json], las variables de entorno, etc.), configura el registro y prepara la lista de servicios de la aplicación, [builder.Services]. El parámetro [args] contiene los argumentos de la línea de comandos;
  • línea 5: se agregan a la lista los servicios que [MVC] necesita para localizar los controladores de la aplicación y ejecutar sus acciones;
  • línea 8: se construye la aplicación. Después de esta línea, la lista de servicios ya no se puede modificar;
  • línea 11: se habilitan las rutas declaradas por los controladores (los atributos [[HttpGet]], [[Route]]..., de los que hablaremos): sin esta línea, no se invocaría ninguna acción;
  • línea 14: inicia el servidor web [Kestrel] y espera solicitudes hasta que se detenga la aplicación ([Ctrl-C]). Salvo que se indique otra cosa, el servidor escucha en el puerto 5000.

Este archivo no contiene ninguna clase ni ningún método llamado [Main]: es un programa de instrucciones de nivel superior. El propio compilador de [C#] envuelve estas instrucciones en un método llamado [Main], que sirve como punto de entrada del programa. Observe también la ausencia de directivas [using]: [WebApplication] pertenece al espacio de nombres [Microsoft.AspNetCore.Builder], que se importa automáticamente (véase [ImplicitUsings] en la introducción).

2.1.2. El controlador: Controllers/HomeController.cs

using Microsoft.AspNetCore.Mvc;

namespace Example01.Controllers;

// un controlador es una clase que hereda de Controller
public class HomeController : Controller
{
    // una acción: el método invocado para la solicitud GET /
    [HttpGet("/")]
    public string Index()
    {
        // el valor devuelto por la acción es la respuesta enviada al navegador
        return "Hello from ASP.NET Core MVC!";
    }
}
  • Línea 1: el espacio de nombres que contiene la clase [Controller] y los atributos de [MVC];
  • línea 3: el espacio de nombres de las clases de este archivo. Por convención, incluye el nombre del proyecto ([Example01]) y el directorio del archivo ([Controllers]). La forma [namespace X;] (sin llaves) se aplica a todo el archivo;
  • línea 6: Un controlador es una clase public que hereda de la clase [Controller]. Por convención, su nombre termina en [Controller]. [ASP.NET Core] encuentra automáticamente los controladores de la aplicación: no es necesario declararlos;
  • línea 9: el atributo [[HttpGet("/")]] asocia el método [Index] con las solicitudes [GET /]. Un método asociado de este modo a una ruta es una acción. Un atributo de [C#] se escribe entre corchetes, inmediatamente antes de lo que describe: agrega información al método, que el framework lee al iniciar;
  • Línea 13: El valor devuelto por la acción es la respuesta enviada al navegador.

2.1.3. Ejecución

En una ventana de terminal abierta en el directorio [01-structure], escriba [dotnet run]. Después de la compilación, el servidor se inicia:

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

Los mensajes de inicio indican la dirección de escucha ([http://localhost:5000]) y el entorno de ejecución: [Production], el entorno predeterminado. Veremos que ciertos comportamientos de [ASP.NET Core] dependen del entorno ([Development] o [Production]). Solicitemos la URL [http://localhost:5000/] con un navegador:

Image

y luego con [curl]. La opción [-i] muestra también los encabezados HTTP de la respuesta (aquí solo mostramos algunos):

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!

Una cadena devuelta por una acción se envía con el encabezado [Content-Type: text/plain]: el navegador la muestra como texto sin formato, sin interpretarla. Esto difiere de [NestJS], que la enviaba como HTML ([text/html]). El ejemplo 03 mostrará cómo enviar HTML.

2.2. Ejemplo 02: Enrutamiento

El enrutamiento asocia una URL y un método HTTP (GET, POST...) con una acción. El ejemplo 02 tiene dos controladores:

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

El archivo [Program.cs] es idéntico al del ejemplo 01: esto es así para todos los ejemplos de este capítulo, salvo el último. El archivo [Controllers/HomeController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example02.Controllers;

public class HomeController : Controller
{
    // GET /: una página HTML con enlaces a las demás acciones
    [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): una respuesta cuyo tipo elegimos (aquí HTML)
        return Content(html, "text/html; charset=utf-8");
    }
}
  • línea 9: la acción ya no devuelve una cadena, sino un [ContentResult]: una respuesta cuyo contenido y tipo se especifican;
  • líneas 11–22: una cadena sin formato de [C#] ([raw string literal]), delimitada por tres comillas. Puede abarcar varias líneas y contener comillas sin necesidad de escaparlas. Los espacios que preceden a las ["""] de cierre se eliminan de cada línea;
  • línea 24: el método [Content(text, type)] de la clase [Controller] genera un [ContentResult]. El tipo [text/html] indica al navegador que interprete el texto como HTML.

La acción [Index] devuelve así una página HTML que contiene enlaces a las acciones del otro controlador:

Image

El archivo [Controllers/FirstController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example02.Controllers;

// prefijo compartido por todas las rutas del controlador
[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: misma ruta, otro método HTTP
    [HttpPost("action01")]
    public string Action01Post()
    {
        return "Action [Action01Post] of the [First] controller, POST request";
    }

    // GET /first/products/17: {id} es un parámetro de ruta, ":int" una restricción
    [HttpGet("products/{id:int}")]
    public string Product(int id)
    {
        return $"Product no. {id}";
    }

    // GET /first/products/17/reviews/3: dos parámetros de ruta
    [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} acepta cualquier final de ruta
    [HttpGet("files/{**path}")]
    public string File(string path)
    {
        return $"Requested file: {path}";
    }
}

Analicemos este código:

  • línea 6: el atributo [[Route("first")]], aplicado a la clase, establece el prefijo común a todas las rutas del controlador: sus acciones procesan las rutas de URL que comienzan con [/first];
  • líneas 10–11: [[HttpGet("")]]: la acción [Index] procesa [GET /first]. La URL de una acción es la concatenación del prefijo del controlador y la ruta de la acción;
  • líneas 17–18: la acción [Action01] procesa [GET /first/action01];
  • líneas 24–25: la misma ruta, pero para el método POST: [[HttpPost]] reemplaza a [[HttpGet]]. También existen [[HttpPut]], [[HttpDelete]], [[HttpPatch]]... El nombre del método [C#] ([Action01Post]) es arbitrario: para el enrutamiento solo importan los atributos. Además, dentro de una misma clase, dos métodos no pueden tener el mismo nombre con los mismos parámetros;
  • líneas 31–32: [{id}] es un parámetro de ruta: este segmento de la URL puede tomar múltiples valores. [:int] es una restricción: el segmento debe ser un entero; de lo contrario, la ruta no coincide. El valor del segmento se pasa al parámetro de la acción del mismo nombre, [id], que ya ha sido convertido a [int]: para [/first/products/17], [id] es igual al número 17. Este es el enlace de modelos ([model binding]), que el próximo capítulo examinará en detalle;
  • líneas 38–39: dos parámetros de ruta, pasados a dos parámetros de la acción;
  • líneas 44–46: [{**path}] es un parámetro "catch-all" ([catch-all]): acepta cualquier final de la URL, incluido [/].

Estos son los resultados de algunas solicitudes:

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 una solicitud POST, use la opción [-X POST] de [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

Un método HTTP que no es procesado por ninguna acción para esta ruta produce un error 405 ([Method Not Allowed]). El encabezado [Allow] enumera los métodos aceptados:

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 último, una URL que ninguna ruta procesa produce un error 404. Esto ocurre también con un identificador que no cumple la restricción [:int]: ninguna ruta coincide con [/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

La respuesta 404 de [ASP.NET Core] no tiene contenido ([Content-Length: 0]): el navegador muestra su propia página de error.

Image

El capítulo 7 mostrará cómo reemplazar esta respuesta vacía por una página HTML.

2.3. Ejemplo 03: Respuestas de una acción

Lo que devuelve una acción determina la respuesta HTTP. El ejemplo 03 repasa los casos principales. El archivo [Controllers/ResponsesController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example03.Controllers;

[Route("responses")]
public class ResponsesController : Controller
{
    // una cadena: se envía tal cual, con el tipo [text/plain]
    [HttpGet("text")]
    public string Text()
    {
        return "<h1>Action [Text]</h1>";
    }

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

    // un objeto: se serializa a JSON, con el tipo [application/json]
    [HttpGet("json")]
    public object Json()
    {
        return new { lastName = "Martin", firstName = "Jean", age = 42 };
    }

    // un arreglo: también se serializa a JSON
    [HttpGet("array")]
    public string[] Array()
    {
        return ["Mme", "Melle", "Mr"];
    }

    // IActionResult: la acción elige la respuesta completa (código, contenido)
    // StatusCode(201, ...): el código 201 (Created) en lugar de 200 (OK)
    [HttpGet("created")]
    public IActionResult ResourceCreated()
    {
        return StatusCode(201, new { message = "resource created" });
    }

    // sin respuesta: el código 204 (No Content) significa "nada que mostrar"
    [HttpGet("empty")]
    public IActionResult EmptyResponse()
    {
        return NoContent();
    }

    // una acción asíncrona: ASP.NET espera el fin de la tarea (Task)
    [HttpGet("task")]
    public async Task<object> AsyncTask()
    {
        var start = DateTime.Now;
        await Task.Delay(500); // una espera de 500 ms, sin bloquear el servidor
        return new { wait = $"{(DateTime.Now - start).TotalMilliseconds:0} ms" };
    }

    // un error "esperado": NotFound(...) produce una respuesta 404
    [HttpGet("not-found")]
    public IActionResult NotFoundError()
    {
        return NotFound(new { message = "This resource does not exist" });
    }

    // un error "inesperado": una excepción no controlada produce una respuesta 500
    [HttpGet("exception")]
    public string Exception()
    {
        throw new InvalidOperationException("An unexpected error");
    }
}

Analicemos este código:

  • líneas 9–12: una cadena se envía tal cual, con el encabezado [Content-Type: text/plain; charset=utf-8];
  • líneas 16–19: la misma cadena, declarada como HTML (véase el ejemplo 02): el navegador la interpreta;
  • líneas 23–26: un objeto se serializa como JSON, con el encabezado [Content-Type: application/json]. [new { lastName = ..., firstName = ... }] crea un objeto de un tipo anónimo: un tipo sin nombre generado por el compilador, útil para datos que se usan una sola vez. Los nombres de las propiedades de JSON se escriben en “camelCase” (primera letra en minúscula), siguiendo la convención de [JavaScript];
  • líneas 30–33: un arreglo también se serializa como JSON. [["Mme", "Melle", "Mr"]] es una expresión de colección ([C#] 12), que aquí crea un arreglo de cadenas;
  • líneas 39–41: cuando la acción necesita elegir el código de estado, devuelve un [IActionResult]: un objeto que describe la respuesta completa. Los métodos de la clase [Controller] generan muchos de ellos: [StatusCode(201, object)] produce una respuesta con código 201 ([Created]) cuyo contenido es el objeto serializado en JSON;
  • líneas 46–48: [NoContent()] devuelve un código de estado 204 ([No Content]): “sin contenido”;
  • líneas 53–57: una acción puede ser asíncrona ([async]): entonces devuelve una tarea ([Task<T>]), el equivalente de una promesa ([JavaScript]), y [ASP.NET Core] espera a que la tarea termine antes de responder. [await Task.Delay(500)] espera 500 ms sin bloquear el servidor: durante la espera, el hilo que ejecutaba la acción se devuelve al servidor, que puede usarlo para procesar otras solicitudes. Así se escriben todas las acciones que consultan una base de datos;
  • líneas 62–64: un error previsto por el programa: [NotFound(object)] devuelve una respuesta 404 con contenido JSON. De igual manera, existen [BadRequest(...)] (400), [Unauthorized()] (401), [Forbid()] (403), [Ok(...)] (200)...;
  • líneas 69–71: un error inesperado: la acción lanza una excepción que no maneja. [ASP.NET Core] responde entonces con un error 500 ([Internal Server Error]).

Respuestas recibidas:

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

En este caso de excepción, la respuesta no proporciona ninguna información sobre el error: los detalles podrían ayudar a un atacante. Se registran en la consola del servidor (aquí solo reproducimos el comienzo):

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
         ...

En un navegador, la diferencia entre [text/plain] y [text/html] es visible:

Image

Image

2.4. Ejemplo 04: Redirecciones

Una acción puede responder con una redirección: un código de estado 301 o 302 y un encabezado [Location] que indica al navegador qué URL solicitar a continuación. El navegador la solicita de inmediato, sin intervención del usuario. Las redirecciones son omnipresentes en una aplicación web: después de enviar un formulario con éxito, después de iniciar sesión, después de cambiar el idioma...

El archivo [Controllers/RedirectsController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example04.Controllers;

public class RedirectsController : Controller
{
    // redirección permanente (301): la página cambió de dirección de forma definitiva
    [HttpGet("old")]
    public IActionResult OldPage()
    {
        return RedirectPermanent("/new");
    }

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

    // redirección temporal (302), a una dirección calculada
    [HttpGet("go/{destination}")]
    public IActionResult Go(string destination)
    {
        return Redirect($"/page/{destination}");
    }

    // redirección a una ACCIÓN: ASP.NET construye la URL por sí mismo
    [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";
    }

    // redirección a otro sitio
    [HttpGet("documentation")]
    public IActionResult Documentation()
    {
        return Redirect("https://learn.microsoft.com/aspnet/core");
    }
}

Analicemos este código:

  • líneas 9–11: [RedirectPermanent(url)] genera una redirección permanente (código de estado 301, [Moved Permanently]): la dirección de la página ha cambiado de forma definitiva. Los navegadores y los motores de búsqueda pueden almacenar en caché la nueva dirección;
  • líneas 22–24: [Redirect(url)] genera una redirección temporal (código de estado 302, [Found]), en este caso hacia una dirección calculada. [$"/page/{destination}"] es una cadena interpolada: la expresión entre llaves se reemplaza por su valor;
  • líneas 29–31: [RedirectToAction(action, values)] redirige a una acción, no a una URL: [ASP.NET Core] genera por sí mismo la URL de la acción [Page] a partir de su ruta ([page/{name}]) y de los valores proporcionados ([name = destination]). Si la ruta de la acción llegara a cambiar, la redirección la sigue. [nameof(Page)] devuelve el nombre del método (["Page"]): un error tipográfico provocaría un error de compilación, lo que no ocurre con una cadena escrita a mano;
  • líneas 42–44: se puede redirigir a otro sitio.

[curl] muestra la redirección sin seguirla:

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

Con la opción [-L], [curl] sigue la redirección, igual que lo haría un navegador. Vemos entonces las dos respuestas sucesivas:

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

Ambas acciones producen la misma redirección: una con una URL escrita a mano, la otra con una URL generada por [ASP.NET Core]. En el navegador solo se ve la página final; la barra de direcciones muestra la nueva 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. Ejemplo 05: Los objetos de solicitud y respuesta

Cada solicitud está representada por un objeto [HttpContext], que contiene la solicitud ([Request]) y la respuesta que se está generando ([Response]). Una acción accede a ellos directamente mediante las propiedades [HttpContext], [Request] y [Response] de la clase [Controller]. A veces es necesario, y lo haremos en el caso de estudio (por ejemplo, para leer o establecer una cookie), pero hay que saber lo que se hace.

El archivo [Controllers/HttpController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example05.Controllers;

[Route("http")]
public class HttpController : Controller
{
    // la solicitud: método, ruta, parámetros, encabezados...
    [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(),
        };
    }

    // la respuesta: le agregamos un encabezado y luego la acción devuelve su valor normalmente
    [HttpGet("header")]
    public string Header()
    {
        Response.Headers["X-Example"] = "05-httpcontext";
        return "Response with an added header";
    }

    // la respuesta escrita "a mano": código, tipo y luego el cuerpo
    [HttpGet("response")]
    public async Task ResponseByHand()
    {
        Response.StatusCode = 200;
        Response.ContentType = "text/plain; charset=utf-8";
        await Response.WriteAsync("Response written by [Response.WriteAsync]");
    }

    // ERROR que no se debe cometer: escribir la respuesta Y LUEGO devolver un resultado
    [HttpGet("double")]
    public async Task<IActionResult> Double()
    {
        await Response.WriteAsync("Start of the response... ");
        // la respuesta ya salió: su código y sus encabezados ya no pueden cambiar
        return NotFound();
    }
}

Analicemos este código:

  • líneas 10–18: la solicitud: el método HTTP ([Request.Method]), la ruta ([Request.Path]), los parámetros de la URL ([Request.QueryString]), los encabezados ([Request.Headers]) y, mediante [HttpContext.Connection], la dirección (IP) del cliente. [?.] es el operador “condicional nulo”: si [RemoteIpAddress] es igual a [null], la expresión se evalúa como [null] en lugar de provocar un error;
  • líneas 24–27: la acción agrega un encabezado a la respuesta y luego devuelve su valor normalmente, que [ASP.NET Core] envía. Este es el uso más habitual de [Response];
  • líneas 32–36: la acción escribe ella misma la respuesta —código de estado, tipo y luego el cuerpo— mediante [Response.WriteAsync]. No devuelve nada ([Task], no [Task<T>]);
  • líneas 41–45: el error que se debe evitar: escribir una parte de la respuesta y luego devolver un resultado. Una vez que los primeros bytes del cuerpo se han enviado al navegador, el código de estado y los encabezados —que se enviaron antes del cuerpo— ya no se pueden modificar.

Las respuestas obtenidas:

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"}

(La opción [-A] de [curl] establece el encabezado [User-Agent], que identifica al 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... 

En la última acción, el navegador recibe un código de estado 200 y el comienzo de la respuesta, en lugar del 404 solicitado. La consola del servidor informa del error:

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.
      ...

En el resto del documento, las acciones casi siempre devolverán un resultado ([IActionResult]) y dejarán que [ASP.NET Core] escriba la respuesta. [Request] y [Response] solo se usarán para leer la solicitud y establecer cookies.

2.6. Ejemplo 06: Servicios e inyección de dependencias

Los controladores no deben contener lógica de aplicación; la delegan en servicios. Un servicio es un objeto común que [ASP.NET Core] crea y proporciona a las clases que lo necesitan: esto es la inyección de dependencias. El ejemplo 06 divide una pequeña aplicación en dos partes: productos y 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. El producto

1
2
3
4
namespace Example06.Products;

// un "record": una clase de datos cuyas propiedades se asignan en el constructor
public record Product(int Id, string Name, decimal Price);

Un record: una clase de datos declarada en una sola línea. El compilador crea las propiedades [Id], [Name] y [Price], un constructor que las inicializa y métodos de utilidad (comparación, visualización). El tipo [decimal] representa importes sin errores de redondeo.

2.6.2. El contrato del servicio: IProductsService

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

// el CONTRATO del servicio: lo que puede hacer, sin decir cómo
public interface IProductsService
{
    IReadOnlyList<Product> FindAll();
    Product? FindById(int id);
}
  • Línea 4: una interfaz describe lo que puede hacer el servicio, sin especificar cómo. Las clases que usan el servicio solo conocerán esta interfaz;
  • línea 6: [IReadOnlyList<Product>]: una lista que el llamador puede leer pero no modificar;
  • línea 7: [Product?]: un producto, o [null] si ningún producto tiene este identificador (véase [Nullable] en la introducción).

2.6.3. La implementación: ProductsService

namespace Example06.Products;

// una IMPLEMENTACIÓN del contrato: aquí, datos en memoria
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);
}
  • línea 4: la clase implementa la interfaz: debe proporcionar todos sus métodos;
  • líneas 6–11: los datos, aquí en memoria, en una lista inicializada mediante una expresión de colección;
  • líneas 13–15: los dos métodos, escritos con la sintaxis [=>] (un método cuyo cuerpo es una sola expresión). [FirstOrDefault] ([LINQ]) devuelve el primer resultado que cumple la condición, o [null] si no hay ninguno.

2.6.4. El controlador ProductsController

using Microsoft.AspNetCore.Mvc;

namespace Example06.Products;

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

    // inyección de dependencias: ASP.NET proporciona la implementación 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);
    }
}
  • Líneas 11–13: inyección de dependencias. El controlador declara, en su constructor, que necesita un [IProductsService]; [ASP.NET Core] le proporciona el objeto registrado para ese tipo (véase más adelante). El controlador nunca llama a [new ProductsService()]: ni siquiera conoce esta clase, solo la interfaz. La implementación podría reemplazarse (por una versión que lea una base de datos, o por una versión de prueba) sin modificar el controlador;
  • líneas 17–19: la acción delega en el servicio. La lista se serializa en JSON;
  • líneas 23–30: [{id:int}] convierte el identificador; un producto inexistente devuelve una respuesta 404. [Ok(object)] devuelve una respuesta 200 cuyo contenido es el objeto serializado en JSON. [is null] comprueba si un valor es nulo.

2.6.5. El controlador ClientsController

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

namespace Example06.Clients;

// "constructor primario" (C# 12): el parámetro del constructor se escribe
// justo después del nombre de la clase y se puede usar en toda la clase
[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) };
    }
}
  • línea 9: un constructor primario ([C#] 12): el parámetro del constructor se escribe directamente después del nombre de la clase. Se puede usar en toda la clase: no es necesario copiarlo en un campo. Esta es la forma más compacta de inyección de dependencias; se usará en el resto de este documento. [ClientsController] recibe el mismo servicio que [ProductsController];
  • líneas 12–15: lo usa para calcular el total de un carrito de compras. [Sum] ([LINQ]) suma los precios.

2.6.6. Registro de servicios

[ASP.NET Core] solo puede proporcionar un servicio si lo conoce: cada servicio se registra en [builder.Services], junto con su ciclo de vida. El archivo [Products/ProductsExtensions.cs]:

namespace Example06.Products;

// un "método de extensión": se invoca como si fuera parte de
// IServiceCollection (builder.Services.AddProducts()). Agrupa los
// registros de la parte "productos" de la aplicación.
public static class ProductsExtensions
{
    public static IServiceCollection AddProducts(this IServiceCollection services)
    {
        // "cuando se solicite un IProductsService, proporcionar un ProductsService";
        // Singleton: una única instancia, compartida por todas las solicitudes
        services.AddSingleton<IProductsService, ProductsService>();
        return services;
    }
}
  • línea 6: una clase estática, que contiene solo métodos estáticos;
  • línea 8: un método de extensión. La palabra clave [this] antes del primer parámetro permite llamarlo como si formara parte del tipo de ese parámetro: [builder.Services.AddProducts()]. Así es como las bibliotecas de [ASP.NET Core] agregan sus servicios ([AddControllers], [AddAuthentication]...), y es una buena manera de agrupar los registros de una parte específica de la aplicación;
  • línea 12: “Cuando una clase solicite un [IProductsService], proporciónele un [ProductsService].” [Singleton] es el ciclo de vida del servicio: una sola instancia, creada en la primera solicitud y compartida por todas las solicitudes. Existen otros dos ciclos de vida: [Scoped] (una instancia por solicitud) y [Transient] (una nueva instancia cada vez que se solicita). El capítulo 6 retomará este tema;
  • línea 13: el método devuelve la lista de servicios para que las llamadas puedan encadenarse.

El archivo [Program.cs]:

using Example06.Products;

var builder = WebApplication.CreateBuilder(args);

// los servicios de MVC
builder.Services.AddControllers();
// los servicios de la parte "productos" (ver Products/ProductsExtensions.cs)
builder.Services.AddProducts();

var app = builder.Build();
app.MapControllers();
app.Run();
  • línea 1: el espacio de nombres del método de extensión;
  • línea 8: el registro del servicio de productos.

Los controladores, en cambio, no se registran individualmente: [AddControllers] los encuentra todos, y [ASP.NET Core] crea un nuevo objeto controlador para cada solicitud, inyectándole los servicios que solicita.

2.6.7. Ejecución

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}

El caso de estudio está estructurado exactamente así: controladores ligeros que delegan en servicios inyectados, descritos mediante interfaces y registrados en [Program.cs].