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
| Parte | Valoare | Rol |
|---|---|---|
| calea | /cauta | alege ruta (endpoint-ul) |
| ? | începutul query string-ului | |
| termen=laptop | cheia termen, valoarea laptop | primul parametru |
| & | separă parametrii | |
| pagina=2, sortare=pret | alț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=mouseGET /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=2GET /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.
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=tabletaGET /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
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ște | Când | Exemplu |
|---|---|---|
| parametru de rută | valoarea identifică resursa; fără ea adresa n-are sens | /produse/15, /clienti/7/comenzi |
| query string | valoarea 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.
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.
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(); 