...
← Curs ASP.NET Core: toate lecțiile
Lecția 6 · Rute

Parametri de rută: {id}

Un magazin cu 5.000 de produse nu poate avea 5.000 de MapGet-uri. Are o singură rută, /produse/{id}, în care {id} este o parte variabilă a adresei. În lecția aceasta înveți să citești valori direct din cale și să le folosești în endpoint, inclusiv ca numere.

Segmente variabile în cale

Până acum toate segmentele căii au fost fixe: /magazin/program. Un segment scris între acolade, de exemplu {nume}, este un parametru de rută: se potrivește cu orice valoare din acea poziție, iar valoarea ajunge în funcția endpoint-ului.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/salut/{nume}", (string nume) => $"Salut, {nume}!");

app.Run();

// GET /salut/Ana
// GET /salut/Mihai
// GET /salut
GET /salut/Ana → 200 OK
Salut, Ana!
GET /salut/Mihai → 200 OK
Salut, Mihai!
GET /salut → 404 Not Found
1
Ruta /salut/{nume} are un segment fix (salut) și unul variabil ({nume}).
2
Lambda-ul are acum un parametru: (string nume). ASP.NET Core îl completează cu valoarea din cale, pentru că are același nume ca parametrul de rută.
3
/salut/Ana dă nume = "Ana", /salut/Mihai dă nume = "Mihai".
4
/salut nu are al doilea segment, deci nu se potrivește cu ruta: 404.

Procesul prin care ASP.NET Core ia valori din cerere și le pune în parametrii funcției se numește model binding sau parameter binding. Îl vei întâlni des în curs.

Conversia automată la int

Parametrul nu trebuie să fie string. Dacă îl declari int, ASP.NET Core convertește singur textul din cale într-un număr, iar tu poți face calcule cu el:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/produse/{id}", (int id) => $"Produsul cu numărul {id}, următorul este {id + 1}");

app.Run();

// GET /produse/15
// GET /produse/7
GET /produse/15 → 200 OK
Produsul cu numărul 15, următorul este 16
GET /produse/7 → 200 OK
Produsul cu numărul 7, următorul este 8

Textul "15" din cale devine int cu valoarea 15, deci id + 1 este 16, nu "151". Aceeași conversie funcționează și pentru long, decimal, double, bool sau Guid.

Mai mulți parametri în aceeași rută

O rută poate avea oricâți parametri, fiecare în segmentul lui. Ordinea parametrilor în lambda nu contează: legătura se face după nume.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/categorii/{categorie}/produse/{id}", (string categorie, int id) =>
    $"Categoria {categorie}, produsul {id}");

app.MapGet("/aduna/{a}/{b}", (int a, int b) => a + b);

app.Run();

// GET /categorii/laptopuri/produse/42
// GET /aduna/20/22
GET /categorii/laptopuri/produse/42 → 200 OK
Categoria laptopuri, produsul 42
GET /aduna/20/22 → 200 OK
42

Observă al doilea endpoint: întoarce un int, nu un string. Un număr întors din endpoint este serializat ca JSON, adică 42 cu Content-Type: application/json.

Ce se întâmplă cu /produse/abc

Dacă parametrul este int, dar în cale vine un text care nu e număr, conversia eșuează:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/produse/{id}", (int id) => $"Produsul {id}");

app.Run();

// GET /produse/abc
GET /produse/abc → 400 Bad Request
Microsoft.AspNetCore.Http.BadHttpRequestException: Failed to bind parameter "int id" from "abc".

Ruta s-a potrivit ({id} acceptă orice text), dar parametrul int id nu a putut fi completat. Rezultatul este 400 Bad Request. Mesajul înseamnă: „nu am putut lega parametrul int id de valoarea abc”. Codul tău nu a rulat deloc.

Development vs. producție

Textul excepției BadHttpRequestException apare în corp doar în mediul Development (cel implicit când lucrezi pe calculatorul tău și în laborator), ca să înțelegi repede problema. În producție, clientul primește doar 400 cu corp gol, ca să nu afle detalii despre server.

400 este corect aici: clientul a trimis o adresă greșită. În lecția următoare vei vedea cum faci ca /produse/abc să nici nu se potrivească cu ruta, cu ajutorul constrângerilor.

Greșeli frecvente

  • Nume diferite: ruta /salut/{nume} cu lambda-ul (string n) nu leagă valoarea din cale de n. Numele trebuie să fie identice (literele mari și mici nu contează).
  • Uiți acoladele: "/salut/nume" este un segment fix, care se potrivește doar cu textul nume.
  • **Folosești string când ai nevoie de număr**: "15" + 1 dă "151". Declară parametrul int.
  • Confunzi 404 cu 400: 404 = nicio rută nu se potrivește cu calea; 400 = ruta s-a potrivit, dar valoarea nu poate fi convertită.

Parametri de rută în aplicații reale

AplicațiaRutaExemplu de cerere
magazin online/produse/{id}GET /produse/15
bancă/conturi/{iban}/tranzactiiGET /conturi/RO49AAAA1B31007593840000/tranzactii
școală/clase/{clasa}/elevi/{nrMatricol}GET /clase/9B/elevi/127
livrări/comenzi/{id}/statusGET /comenzi/98431/status
Exercițiul tău

Adaugă două endpoint-uri cu parametri de rută. GET /salut/{nume} întoarce Salut, {nume}! (de exemplu Salut, Ana!). GET /dublu/{n} primește parametrul ca int și întoarce dublul lui (n * 2). Laboratorul trimite /salut/Ana, /salut/Mihai, /dublu/21 și /dublu/abc (ultima trebuie să dea 400).

  • Adaugă ruta /salut/{nume} cu un parametru string nume și întoarce $"Salut, {nume}!".
  • Adaugă ruta /dublu/{n} cu un parametru int n și întoarce n * 2.
  • Nu adăuga constrângeri: pentru /dublu/abc vrem 400 de la conversia eșuată.
Numele din acolade trebuie să fie același cu numele parametrului lambda: ("/dublu/{n}", (int n) => n * 2).

Soluția exercițiului

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/salut/{nume}", (string nume) => $"Salut, {nume}!");
app.MapGet("/dublu/{n}", (int n) => n * 2);

app.Run();
Excelent! Continuă cu lecția următoare →
Program.csASP.NET Core
ConsolăSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Rulează codul cu butonul de sus sau cu Ctrl + Enter / Cmd + Enter.
Parcursul tău Primul tău API cu ASP.NET Core Lecția 6 · Parametri de rută: {id}
Progres 0% 0 din 22
Lecția curentă 6 / 20 Rute