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

Parametri din query string

Când cauți „laptop” pe un site, adresa devine ceva de felul /cauta?termen=laptop&pagina=2. Partea de după semnul întrebării este query string-ul: perechi cheie=valoare folosite pentru căutări, filtre, sortare și paginare. În lecția aceasta înveți să le citești în endpoint, cu valori implicite și parametri opționali.

Anatomia unei adrese cu query string

/cauta?termen=laptop&pagina=2&sortare=pret
ParteValoareRol
calea/cautaalege ruta (endpoint-ul)
?începutul query string-ului
termen=laptopcheia termen, valoarea laptopprimul parametru
&separă parametrii
pagina=2, sortare=pretalți parametri

Query string-ul nu face parte din potrivirea rutei: /cauta?termen=laptop și /cauta?termen=mouse ajung la același endpoint, /cauta. De aceea este locul potrivit pentru informații opționale, care nu identifică o resursă, ci spun cum o vrei (filtrată, sortată, pagina 2).

Parametrii care nu sunt în rută vin din query

Regula de binding este simplă: un parametru de tip simplu (string, int, bool...) al lambda-ului care nu apare în ruta dintre acolade este căutat în query string, după nume.

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

app.MapGet("/cauta", (string termen, int pagina) => $"Caut {termen}, pagina {pagina}");

app.Run();

// GET /cauta?termen=laptop&pagina=2
// GET /cauta?pagina=3&termen=mouse
GET /cauta?termen=laptop&pagina=2 → 200 OK
Caut laptop, pagina 2
GET /cauta?pagina=3&termen=mouse → 200 OK
Caut mouse, pagina 3
  • termen și pagina nu sunt în rută, deci vin din query;
  • ordinea din query nu contează: legătura se face după nume;
  • pagina este convertit la int automat, ca la parametrii de rută.

Valori implicite și parametri opționali

Utilizatorul nu trimite mereu toți parametrii. Ai două unelte ca să faci un parametru opțional:

  • o valoare implicită: int pagina = 1 înseamnă „dacă lipsește din query, folosește 1”;
  • un tip nullabil: string? sortare înseamnă „poate lipsi”; dacă lipsește, valoarea este null.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/produse", (int pagina = 1, string? sortare = null) =>
    $"Pagina {pagina}, sortare: {sortare ?? "implicită"}");

app.Run();

// GET /produse
// GET /produse?pagina=4
// GET /produse?sortare=pret&pagina=2
GET /produse → 200 OK
Pagina 1, sortare: implicită
GET /produse?pagina=4 → 200 OK
Pagina 4, sortare: implicită
GET /produse?sortare=pret&pagina=2 → 200 OK
Pagina 2, sortare: pret

Operatorul ?? din cursul de C# înlocuiește null cu un text implicit. Fără parametri, /produse folosește pagina 1 și nicio sortare.

Nullable reference types

Proiectele ASP.NET Core noi au activată opțiunea nullable. De aceea contează semnul întrebării: string termen înseamnă „obligatoriu”, iar string? termen înseamnă „opțional”. ASP.NET Core citește această informație și decide singur dacă parametrul poate lipsi.

Parametru obligatoriu lipsă: 400

Dacă un parametru este obligatoriu (string termen, int pagina fără valoare implicită) și lipsește din query, endpoint-ul nu rulează:

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

app.MapGet("/cauta", (string termen) => $"Caut {termen}");

app.Run();

// GET /cauta
// GET /cauta?termen=
// GET /cauta?termen=tableta
GET /cauta → 400 Bad Request
Microsoft.AspNetCore.Http.BadHttpRequestException: Required parameter "string termen" was not provided from query string.
GET /cauta?termen= → 200 OK
Caut
GET /cauta?termen=tableta → 200 OK
Caut tableta
1
/cauta fără termen: 400 Bad Request. Mesajul înseamnă „parametrul obligatoriu string termen nu a fost găsit în query string”.
2
/cauta?termen= are cheia, cu o valoare goală: parametrul există, deci endpoint-ul rulează cu termen = "" și răspunde Caut urmat de nimic. Binding-ul verifică doar că parametrul a fost trimis; dacă un text gol e acceptabil este o regulă a aplicației tale, pe care o vei verifica în cod mai târziu.
3
/cauta?termen=tableta merge normal.

Același lucru se întâmplă cu o valoare care nu se poate converti, de exemplu ?pagina=abc pentru int pagina: 400 cu mesajul Failed to bind parameter.

Rută sau query?

FoloseșteCândExemplu
parametru de rutăvaloarea identifică resursa; fără ea adresa n-are sens/produse/15, /clienti/7/comenzi
query stringvaloarea filtrează, sortează, paginează; e de obicei opțională/produse?categorie=laptopuri&pagina=2

O întrebare bună de pus: „dacă scot valoarea, mai am o adresă validă?”. /produse fără ?pagina=2 este tot lista de produse, deci pagina merge în query. /produse/ fără 15 nu mai este produsul 15, deci id-ul merge în rută.

Greșeli frecvente

  • **Pui query-ul în ruta din MapGet**: MapGet("/cauta?termen={termen}", ...) nu funcționează. Ruta conține doar calea; parametrii din query apar doar în lambda.
  • **Uiți ? la tipul string**: fără el, parametrul e obligatoriu și cererile fără el primesc 400.
  • **Separi cu ? de două ori**: /cauta?termen=a?pagina=2 e greșit; al doilea parametru se separă cu &.
  • Nume diferite: ?Termen=laptop funcționează (literele mari nu contează), dar ?q=laptop nu ajunge în parametrul termen.
Exercițiul tău

Construiește motorul de căutare al magazinului: GET /cauta primește din query termen (obligatoriu) și pagina (opțional, implicit 1) și răspunde cu Caut „{termen}” pe pagina {pagina}. Laboratorul trimite /cauta?termen=mouse, /cauta?termen=laptop&pagina=3 și /cauta (fără termen, trebuie să dea 400).

  • Adaugă ruta GET /cauta cu parametrii string termen și int pagina = 1.
  • Întoarce textul Caut „{termen}” pe pagina {pagina} (cu ghilimelele românești „ și ”).
  • Nu face termen opțional: o căutare fără termen trebuie să primească 400.
Ruta rămâne doar "/cauta"; parametrii din query apar numai în lambda: (string termen, int pagina = 1) => ....

Soluția exercițiului

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

app.MapGet("/cauta", (string termen, int pagina = 1) => $"Caut „{termen}” pe pagina {pagina}");

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 8 · Parametri din query string
Progres 0% 0 din 22
Lecția curentă 8 / 20 Rute