Route Values and the Query String

Values reach an action from the route (/products/7) or the query string (?page=2). Choose which with the address's meaning, give optional values defaults, and use [FromRoute] and [FromQuery] to be explicit.

Journeyman · ASP.NET Core · C# · Updated

By

After this lesson you can

  • Read values from the route and the query string, with defaults for optional ones
  • Choose between a route value and a query string value for a piece of information

Key takeaways

  • A route value such as {id:int} fills the parameter with the same name and is required unless marked with ?; other parameters come from the query string.
  • Give a query string parameter a default, such as int page = 1, and it's optional.
  • [FromQuery(Name = "q")] reads ?q=sauce into a parameter with a clearer C# name; [FromRoute] and [FromForm] name the other sources.
  • If leaving a value out makes no sense, it belongs in the route (/products/7); if it means "the default", it belongs in the query string (?page=2).

An action's parameters are filled from the request. Two parts of the address carry values:

/products/7               the route:        id = 7
/products?page=2          the query string: page = 2
/products/search?q=tofu   the query string: q = tofu

From the route

A value in the route template, such as {id:int}, fills the parameter with the same name:

[HttpGet("{id:int}")]
public IActionResult Details(int id)

/products/7 calls Details(7). The route can't match without it, so a route value is required (unless it's marked optional with ?).

From the query string

Any other parameter is looked for in the query string, the part after ?. Give it a default value, and it's optional:

[HttpGet("")]
public IActionResult Index(int page = 1)
{
    int pageCount = (productDao.Count() + PageSize - 1) / PageSize;
    if (page < 1 || page > pageCount)
    {
        return NotFound();
    }

    ViewData["Page"] = page;
    ViewData["PageCount"] = pageCount;
    return View(productDao.GetPage(page, PageSize));
}
Address page
/products 1, the default
/products?page=2 2
/products?page=8 8, which is past the last of 7 pages, so Not Found
/products?page=abc 1: abc isn't an int, so the default stays, and ModelState records the problem

Tag helpers write query strings for you: asp-action="Index" asp-route-page="2" gives href="/products?page=2", because page isn't part of the route.

Saying where a value comes from

Usually the name is enough. When you want to be explicit, or the name in the address differs from the parameter's, use [FromRoute] and [FromQuery]:

[HttpGet("search")]
public IActionResult Search([FromQuery(Name = "q")] string? text)

Now /products/search?q=sauce fills text with sauce. A short q is the usual name for a search box; the parameter keeps its clear C# name. And ?text=sauce fills nothing: with [FromQuery(Name = "q")], only q counts.

Attribute Takes the value from
[FromRoute] The route template, such as {id}
[FromQuery] The query string
[FromForm] A posted form's fields
(none) Wherever binding finds the name: form, route, then query string

Route or query string?

Use the route for Use the query string for
Which thing the page is about: /products/7, /customers/ALFKI How to show it: ?page=2, ?sort=price, ?q=sauce
Values the page can't do without Optional values, with defaults
Addresses people bookmark and share as "the page for X" Filters and settings that change the same page's view

A rule of thumb: if leaving the value out makes no sense, it belongs in the route; if leaving it out means "the default", it belongs in the query string.

Do it: choose the page from the query string

The product list shows 12 products a page. Its page comes from the query string and is optional, with a default of 1. Write the steps model binding and the Index action take together, as one plain method.

The method gets two values:

  • pageText: the page value from the query string, as text: "2" for /products?page=2. It's null when the address has no page at all, as in /products.
  • pageCount: how many pages of products there are, an int (7).

It works in two steps:

  1. Binding: turn pageText into a whole number. When it's null, or isn't a whole number (such as "abc"), the page is the default, 1.
  2. The action's check: a page less than 1, or more than pageCount, doesn't exist.

For example, /products?page=2 with 7 pages:

Step Here
pageText "2"
Binding "2" is a whole number, so the page is 2
The check 2 is from 1 to 7, so the page exists
The answer "Page 2"

So ShowPage("2", 7) returns "Page 2".

Your job: write the method ShowPage(string? pageText, int pageCount) so it returns a string.

  • Return "Page " and the page number when the page exists, such as "Page 2".
  • Return "Not Found" when the page is less than 1 or more than pageCount.
  • When pageText is null, the page is 1.
  • When pageText isn't a whole number, the page is 1.

Practiced live on the lesson page: write the C# right there and check it.

Check yourself

2 questions to try on the lesson page.

So what

The route says what the page is about; the query string says how to show it. Choose by meaning, give optional values defaults, and your addresses explain themselves.

Key terms

Cheat sheets