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

Constrângeri de rută: {id:int}

În lecția trecută, /produse/abc a ajuns la endpoint și a primit 400, pentru că textul nu se putea converti în număr. Cu o constrângere de rută îi spui lui ASP.NET Core dinainte ce fel de valoare acceptă un segment: doar numere, doar litere, doar valori între 1 și 100. Cererile care nu respectă regula nici nu se potrivesc cu ruta.

Ce este o constrângere

O constrângere se scrie după numele parametrului, separată prin două puncte: {id:int}. Ea face parte din potrivirea rutei: dacă valoarea din cale nu respectă constrângerea, ruta este considerată pur și simplu „altă adresă”.

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

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

app.Run();

// GET /produse/15
// GET /produse/abc
GET /produse/15 → 200 OK
Produsul 15
GET /produse/abc → 404 Not Found

Compară cu lecția trecută: fără constrângere, /produse/abc dădea 400; acum dă 404. Diferența are sens: ruta spune „aici sunt doar produse cu id numeric”, iar abc nu este o adresă care există.

RutaCererea /produse/abcDe ce
/produse/{id} + int id400 Bad Requestruta se potrivește, conversia la int eșuează
/produse/{id:int} + int id404 Not Foundconstrângerea nu se potrivește, deci ruta nu există pentru această cale

Constrângerile cele mai folosite

ConstrângereAcceptăExemplu acceptatExemplu respins
intnumăr întreg15, -3abc, 1.5
booltrue sau falsetrueda
guidun Guid0f8fad5b-d9cb-469f-a165-70867728950e123
alphadoar litere (a–z, A–Z)laptoplaptop2
min(1)număr cel puțin 11, 5000
max(100)număr cel mult 10099101
range(1,10)număr între 1 și 10, inclusiv711
minlength(3)text de cel puțin 3 caractereAnaAl

Poți combina mai multe constrângeri, separate tot prin două puncte: {id:int:min(1)} înseamnă „un număr întreg, cel puțin 1”. Toate trebuie respectate.

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

app.MapGet("/note/{nota:int:range(1,10)}", (int nota) => $"Ai primit nota {nota}");
app.MapGet("/utilizatori/{nume:minlength(3)}", (string nume) => $"Profilul lui {nume}");

app.Run();

// GET /note/9
// GET /note/11
// GET /utilizatori/Ana
// GET /utilizatori/Al
GET /note/9 → 200 OK
Ai primit nota 9
GET /note/11 → 404 Not Found
GET /utilizatori/Ana → 200 OK
Profilul lui Ana
GET /utilizatori/Al → 404 Not Found

Două rute pe aceeași cale

Constrângerile îți permit să ai două rute care arată la fel, dar acceptă valori diferite. Un magazin poate accepta atât /produse/15 (după id), cât și /produse/laptop (după un nume scurt, numit slug):

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

app.MapGet("/produse/{id:int}", (int id) => $"Caut după id: {id}");
app.MapGet("/produse/{slug:alpha}", (string slug) => $"Caut după slug: {slug}");

app.Run();

// GET /produse/15
// GET /produse/laptop
// GET /produse/laptop15
GET /produse/15 → 200 OK
Caut după id: 15
GET /produse/laptop → 200 OK
Caut după slug: laptop
GET /produse/laptop15 → 404 Not Found
1
15 respectă int, nu respectă alpha: se alege prima rută.
2
laptop respectă alpha, nu respectă int: se alege a doua rută.
3
laptop15 nu respectă niciuna dintre constrângeri: 404.
Fără constrângeri ar fi fost conflict

Dacă ai scrie /produse/{id} și /produse/{slug}, ambele rute s-ar potrivi cu orice valoare și ai primi AmbiguousMatchException (500), ca în lecția despre rute duplicate.

Constrângerile nu sunt validare

Constrângerile servesc la alegerea rutei, nu la verificarea regulilor de business. Documentația ASP.NET Core recomandă explicit să nu le folosești pentru validarea datelor introduse de utilizator, pentru că răspunsul este un 404 fără nicio explicație.

  • potrivit pentru constrângeri: tipul segmentului (int, guid), ca să deosebești rute sau să eviți conversii eșuate;
  • nu e potrivit: „nota trebuie să fie între 1 și 10” pentru un formular. Acolo vrei 400 cu un mesaj clar („Nota trebuie să fie între 1 și 10”), pe care îl vei scrie în cod în lecțiile despre coduri de status și validare.

Greșeli frecvente

  • Spații în constrângere: {id: int} nu este valid; scrie {id:int} lipit.
  • Tipul lambda diferit de constrângere: {id:int} cu (string id) funcționează, dar pierzi conversia; păstrează tipurile la fel.
  • Te aștepți la 400 când constrângerea nu se potrivește: răspunsul este 404, pentru că ruta nu există pentru acea valoare.
  • **alpha cu diacritice**: alpha acceptă doar literele englezești a–z, deci /produse/căști nu se potrivește.

Pe scurt

ScriiÎnseamnă
{id}orice valoare; conversia la tipul parametrului poate da 400
{id:int}doar numere întregi; altfel 404
{id:int:min(1)}numere întregi de la 1 în sus
{slug:alpha}doar litere
Exercițiul tău

Magazinul acceptă produse atât după id, cât și după slug. GET /produse/{id} acceptă doar numere întregi de cel puțin 1 și întoarce Produsul {id}. GET /produse/{slug} acceptă doar litere și întoarce Produsul cu slug {slug}. Laboratorul trimite /produse/5, /produse/laptop, /produse/0 și /produse/12abc; ultimele două trebuie să dea 404.

  • Adaugă ruta /produse/{id:int:min(1)} cu parametrul int id și textul Produsul {id}.
  • Adaugă ruta /produse/{slug:alpha} cu parametrul string slug și textul Produsul cu slug {slug}.
  • Nu trata separat 0 sau 12abc: constrângerile le resping singure.
Constrângerile se combină cu două puncte: {id:int:min(1)}.

Soluția exercițiului

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

app.MapGet("/produse/{id:int:min(1)}", (int id) => $"Produsul {id}");
app.MapGet("/produse/{slug:alpha}", (string slug) => $"Produsul cu slug {slug}");

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 7 · Constrângeri de rută: {id:int}
Progres 0% 0 din 22
Lecția curentă 7 / 20 Rute