Ler parâmetros da URL (query string) é uma tarefa fundamental no desenvolvimento web com ASP.NET. Este artigo abrange todas as abordagens modernas e clássicas, desde Web Forms até ASP.NET Core e Minimal API.

O que é uma query string?

Uma query string é a parte de uma URL que vem após o sinal ?. Contém pares de chave-valor separados por &:

https://exemplo.com.br/buscar?termo=asp.net&pagina=2&ordem=data

Neste exemplo:

  • termo = asp.net
  • pagina = 2
  • ordem = data

ASP.NET Web Forms (clássico)

Request.QueryString

// URL: https://exemplo.com.br/pagina.aspx?id=42&nome=produto

// Obter um único parâmetro
string id = Request.QueryString["id"];      // "42"
string nome = Request.QueryString["nome"];  // "produto"

// Verificar existência antes de usar
if (!string.IsNullOrEmpty(Request.QueryString["id"]))
{
    int produtoId = int.Parse(Request.QueryString["id"]);
    // Usar o ID...
}

Uso em Page_Load

protected void Page_Load(object sender, EventArgs e)
{
    string categoria = Request.QueryString["cat"];
    
    if (!string.IsNullOrEmpty(categoria))
    {
        lblCategoria.Text = Server.HtmlEncode(categoria);
        CarregarProdutos(categoria);
    }
}

Segurança: Sempre use Server.HtmlEncode() ao exibir valores de query string na página para prevenir ataques XSS (Cross-Site Scripting).

ASP.NET MVC

Vinculação de modelo automática

No MVC, o framework vincula automaticamente os parâmetros da URL aos parâmetros do método de ação:

// URL: /Produtos/Buscar?termo=laptop&pagina=1
public ActionResult Buscar(string termo, int pagina = 1)
{
    // 'termo' = "laptop", 'pagina' = 1
    var resultados = _servico.Buscar(termo, pagina);
    return View(resultados);
}

Acesso direto à QueryString

public ActionResult Detalhe()
{
    string id = Request.QueryString["id"];
    // Ou no MVC, preferencialmente:
    string id2 = Request["id"];
    
    return View();
}

ASP.NET Core

Atributo [FromQuery]

// URL: /api/produtos?categoria=eletronica&precoMin=100&precoMax=500

[HttpGet]
public IActionResult ListarProdutos(
    [FromQuery] string categoria,
    [FromQuery] decimal? precoMin,
    [FromQuery] decimal? precoMax)
{
    // Os parâmetros são vinculados automaticamente da query string
    var produtos = _repo.Filtrar(categoria, precoMin, precoMax);
    return Ok(produtos);
}

Vinculação com objeto de consulta

Para múltiplos parâmetros, use uma classe:

public class FiltroProduto
{
    public string Categoria { get; set; }
    public decimal? PrecoMin { get; set; }
    public decimal? PrecoMax { get; set; }
    public int Pagina { get; set; } = 1;
    public int TamanhoPagina { get; set; } = 20;
}

[HttpGet]
public IActionResult Listar([FromQuery] FiltroProduto filtro)
{
    // Todos os parâmetros da URL são mapeados para as propriedades do objeto
    var resultados = _repo.Filtrar(filtro);
    return Ok(resultados);
}

Acesso direto ao HttpContext

public IActionResult Index()
{
    // Acesso direto sem vinculação de modelo
    string valor = HttpContext.Request.Query["parametro"];
    
    // Verificar existência
    if (HttpContext.Request.Query.ContainsKey("modo"))
    {
        string modo = HttpContext.Request.Query["modo"];
    }
    
    return View();
}

Minimal API (ASP.NET Core 6+)

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

// Os parâmetros da URL são vinculados automaticamente
app.MapGet("/buscar", (string termo, int pagina = 1) =>
{
    return Results.Ok(new { Termo = termo, Pagina = pagina });
});

// Com [FromQuery] explícito
app.MapGet("/filtrar", ([FromQuery] string categoria, [FromQuery] int? limite) =>
{
    return Results.Ok(new { Categoria = categoria, Limite = limite ?? 10 });
});

app.Run();

Padrão ReturnUrl (redirecionamento pós-login)

Um caso de uso muito comum é a URL de retorno após o login:

// URL: /Conta/Login?ReturnUrl=%2Fpainel%2Fconfiguracoes

[HttpPost]
public IActionResult Login(LoginViewModel modelo, string returnUrl = null)
{
    if (ModelState.IsValid && AutenticarUsuario(modelo))
    {
        // IMPORTANTE: Validar que a URL é local
        if (!string.IsNullOrEmpty(returnUrl) && Url.IsLocalUrl(returnUrl))
        {
            return Redirect(returnUrl);
        }
        
        return RedirectToAction("Index", "Painel");
    }
    
    return View(modelo);
}

Prevenção de redirecionamentos abertos

Nunca faça isso:

// PERIGOSO — vulnerável a redirecionamento aberto
return Redirect(Request.QueryString["ReturnUrl"]);

Sempre valide antes de redirecionar:

// SEGURO — valida que a URL é local
string returnUrl = Request.Query["ReturnUrl"];
if (Url.IsLocalUrl(returnUrl))
{
    return Redirect(returnUrl);
}
return RedirectToAction("Index", "Home");

Um atacante poderia usar ?ReturnUrl=https://site-malicioso.com para direcionar os usuários a um site de phishing.

Leitura com JavaScript

Para ler parâmetros da URL no lado do cliente:

URLSearchParams (moderno)

// URL: https://exemplo.com.br/pagina?termo=busca&lang=pt

const params = new URLSearchParams(window.location.search);

// Obter um parâmetro
const termo = params.get('termo');  // "busca"
const lang = params.get('lang');    // "pt"

// Verificar existência
if (params.has('termo')) {
    console.log('Buscando:', params.get('termo'));
}

// Percorrer todos os parâmetros
for (const [chave, valor] of params) {
    console.log(`${chave} = ${valor}`);
}

Construir URLs com parâmetros

const url = new URL('https://exemplo.com.br/api/produtos');
url.searchParams.set('categoria', 'eletronica');
url.searchParams.set('pagina', '1');
console.log(url.toString());
// "https://exemplo.com.br/api/produtos?categoria=eletronica&pagina=1"

Boas práticas

  1. Sempre valide os parâmetros de entrada antes de usá-los
  2. Codifique a saída com HtmlEncode ao exibir valores em HTML
  3. Use tipos fortemente tipados em vez de strings quando possível
  4. Forneça valores padrão para parâmetros opcionais
  5. Verifique nulos antes de conversões de tipo
  6. Nunca confie em valores da URL para operações sensíveis sem validação

Solução de problemas

O parâmetro é sempre null

  • Verifique se o nome do parâmetro corresponde exatamente (diferencia maiúsculas/minúsculas)
  • Certifique-se de que o ? está presente na URL
  • Confirme que não há erro de codificação em caracteres especiais

Caracteres especiais não são lidos corretamente

Use Uri.UnescapeDataString() para decodificar:

string valor = Uri.UnescapeDataString(Request.Query["texto"]);

Artigos relacionados