How-To: Define Routing Parameters on Blazor Page

As with Blazor components, we can also define parameters on a page. These parameters have slightly different meaning and are usually referred to as routing parameters. The Blazor routing engine will map segments of a URL to matching parameters on that page object. If no matching routes exist, then the “Not Found” message is displayed instead.

To investigate routing parameters, we must have a Blazor page. Either open an existing Blazor project, or please follow the steps in the How-To: Create New Page in Blazor article to get setup. For this article, we called the project: Blazor.HowTo and the page: PageWithParameters.

Define Page Parameters

We start by defining new parameters on our page (PageWithParameters.razor in the Blazor.HowTo and Pages folder):

<h3>Page With Parameter</h3>
<h5>Parameter Values:</h5>
<p>Type: @Type</p>
<p>Id: @Id</p>

@code {
    [Parameter]
    public string Type { get; set; }

    [Parameter]
    public int? Id { get; set; }
}

Routing parameters are just public properties on our page. They must have a getter and setter. And, they must be adorned with the [Parameter] attribute. For this article, we define two parameters:

• Type is a string value (lines #7-8). This parameter is required in the route.
• Id is a nullable int value (lines #10-11). This parameter is optional in the route. And when no value is defined, it will default to null.

Properties with the [Parameter] attribute are used by the routing engine to match URL segments. And as we can see parameters can be strings or other simple types (like int, Guid, etc). Note: they cannot be enum values, but could be represented as the integer equivalent of an enum value.

And, we also use simple one-way binding to display our property values (lines #3-4) on the page for easy validation that the routing parameters work as we expect. (Note: for details on one-way binding, please read the How-To: Add Blazor Component Interactivity with One Way Binding article).

Define Page Routes

Next, to enable routing to this new page, we need to provide one or more routes. Let’s review the same page with the @page routes added.

@page "/page-params/{Type}/{Id:int}"
@page "/page-params/{Type}"

<h3>Page With Parameter</h3>
<h5>Parameter Values:</h5>
<p>Type: @Type</p>
<p>Id: @Id</p>

@code {
    [Parameter]
    public string Type { get; set; }

    [Parameter]
    public int? Id { get; set; }
}

First, we define the required route: @page "/page-params/{Type}/{Id:int}" (line #1).

• As we can see, a route parameter is defined in the URL by wrapping its name in a pair of { braces } when adding the @page declaration.
• The route parameter name must match the page’s property name.
• {Type} maps to the Type property. Since the property is a string, there is nothing further required.
• {Id:int} maps to the Id property. Because the property is an int, we need to constrain this routing parameter to only resolve for integer values.
• To define a constraint for a parameter it is suffixed with a colon and then the constraint type (like :int above).
• If another type is provided for the {Id} segment, then the route will fail.

With this first route definition, the URL must have both {Type} and {Id} segments for the route to resolve as we expect.

Next, we define a second route that is more permissive: @page "/page-params/{Type}" (line #2).

• With both of these routes defined, the {Id} route parameter becomes optional.
  • If the URL has an {Id} segment, then the first route is taken.
  • If the URL does not have an {Id} segment, then this route is taken.
• When the {Id} segment is missing, the Id property defaults to null.

Validate Routing Parameters

With our page complete and the routes defined, let’s build and run (Ctrl + F5) our project. We will try a few different variations to see how our routing parameters work.

1. Fully defined URL – https://localhost:44381/page-params/test/125 (note: this URL’s host id will be different for your local app).

As expected, the {Type} and {Id} segments are mapped to the properties and displayed on the page.

2. URL without optional {Id} – https://localhost:44381/page-params/test.

The Id parameter property is not set by the routing engine, so it is null. And nothing is shown for it on the page for that value.

3. URL with invalid {Id} type – https://localhost:44381/page-params/test/foo-bar.

Because the {Id} segment cannot be converted to an int, then none of our defined routes satisfy this URL. Therefore, the routing engine navigates to the “Not Found” message for our application.

4. URL without {Type} segment – https://localhost:44381/page-params/.

Because the {Type} segment is required in our routes and missing from our URL, Blazor displays the “Not Found” message for our application .

In conclusion, we learned how to define routing parameters for Blazor pages, which includes:

• Defining the page properties with the [Parameter] attribute.
• Defining the required route segments.
• Defining type constrained route segments for simple types (like :int).
• Providing multiple routes to enable optional route segments in our URLs.