Form Tag Helper in ASP.NET Core

The Form Tag Helper generates the HTML <form> element based on the various attributes like asp-controller, asp-action etc. In this tutorial, We will look at how to use Form Tag Helper in ASP.NET Core forms.

Form Tag Helper

The Form Tag Helper targets the HTML <form> element and generates the action URL & action method attributes. It uses the various server-side attributes like asp-controller, asp-action, asp-route- etc to generate the <form> element in the view. It does the following.

1. Generates URL for the action attribute and method attribute using the asp-controller, asp-action & asp-area.
2. Generates the Route Parameters, Query strings & URL Fragments using the attributes like asp-route-{value}, asp-all-route-data & asp-fragment etc.
3. Generates a hidden ValidateAntiForgeryToken to prevent cross-site request forgery.

Attributes of Form Tag Helper

The Form Tag Helpers provide several server-side attributes which help us to manipulate the generated URL. The following is the list of available attributes.

1. asp-controller
2. asp-action
3. asp-route
4. asp-all-route-data
5. asp-route-{value}
6. asp-area
7. asp-fragment
8. asp-page
9. asp-page-handler
10. asp-host
11. asp-protocol
12. asp-antiforgery

Adding Controller Action method in URL

asp-controller

The asp-controller attribute is the name of the MVC controller to use while generating the URL.

Example

<form asp-controller="Home">

The above code translates into

<form method="post" action="/Home/Create">

Note that the current method is used as the action method.

asp-action

The asp-action is the name of the MVC Controller action method to use while generating the URL.

Example

<form asp-controller="Home" asp-action="Create">

The above code translates into

<form method="post" action="/Home/Create">

Adding Areas in Route

asp-area

The asp-action attribute sets the area name to use while generating the URL

Example

<form asp-area=”Profile” asp-controller="Home" asp-action="Create">

The above code translated into

<form method="post" action="/Profile/Home/Create">

For, Areas to work correctly, the route must have area specified as shown below.

{area:exists}/{controller=Home}/{action=Index}

You can read more about Areas from here.

Adding Route Parameters / Query String & Fragments

Most of the times, you need to add parameters to the controller action method. The additional parameters may be in the form of URL Parameter, Query string or URL Fragments. The asp-route-{value}, asp-all-route-data & asp-fragment are the attributes for this task.

Asp-route-{value}

The asp-route-{value} attribute sets the value for a single route parameter represented by the {Value}. It the {value} is not matched to any route parameter, then it is appended as the query string.

Consider the following route.

For example in the following route

{controller}/{action}/{id?}

To include id parameter in the URL we use asp-route-{value} attribute, where {value} is replaced by the id.

Example

<form asp-controller="Home" asp-action="Create" asp-route-id=”12”>

Would translate as

<form method="post" action="/Home/Create/12">

Multiple parameters.

{controller}/{action}/{id?}/{val?}

<form asp-controller="Home" asp-action="Create" asp-route-id=”12” asp-route-val=”whatever”>

Would translate as

<form method="post" action="/Home/Create/12/whatever">

What if the id parameter is not available in the route?

If no matching route parameter is found, then the asp-route-{value} included in the URL as the query string.

For Example: if our route is

{controller}/{action}

Then this tag helper,

<form asp-controller="Home" asp-action="Create" asp-route-id=”12”>

Translates into

<form method="post" action="/Home/Create?id=12">

Note that

The asp-route-{value} attribute needed to be specified for each URL Parameter and query string. 

asp-all-route-data

The asp-all-route-data attribute sets either the URL Parameter or Query string or both using dictionary of key-value pairs.

Example

To use this attribute you should first create a dictionary key-value pair as shown below. The key is the parameter name, and the value is the parameter value.

@{
    var data= new Dictionary<string, string>
    {
        { "Id", "12" },
        { "test", "anything" }
    };
}

For the Route below

{controller=Home}/{action=Index}/{id?}

The following asp-all-route-data tag attribute

<form asp-controller="Home" asp-action="Create" asp-all-route-data=”data”>

Translates into

<form method="post" action="/Home/Index/12?test=anything">

asp-fragment

The asp-fragment attribute sets the URL fragment that needs to be appended to the URL. The URL fragment is added at the end of the URL after the hash character (#).

Example

<form asp-controller="Home" asp-action="Create" asp-route-id=”12” asp-fragment=”test”>

is translated to

<form method="post" action="/Home/Index/12#test">

Using Named Route

asp-route

The asp-route attribute sets the “named route” to use while generating the URL.

The routes can be given name while adding them to the routes collection. 

app.UseMvc(
    Routes.maproute (
        Roues => {
            “Default”,
            “{controller=Home}/{action=Index}/{id?}”);
        }
});

In the above route, “Default” is the name of the route. 

Hence

<Form asp-route="default">

Translates into

<form method="post" action="/Home/Index">

Notes

Razor pages (do not confuse with Razor views) doesn’t support named routes. This parameter will only be used for MVC routes.

Do not use asp-controller or asp-action along with the the asp-route attribute. This most probably results in a route conflict.

Routing to Razor Pages

asp-page

The asp-page attribute is used with Razor Pages. The Razor page name must be provided without the file extension

<form asp-page="/profile">

This translates into

<form action="/?page=%2Fprofile" method="post">

If no page name is specified, the tag helper will generate a link to the current page.

<form asp-page=""></form>

<form action="/user" method="post">

asp-page-handler

The asp-page-handler attribute is used with Razor Pages. It’s intended for linking to specific page handlers.

Consider the following page handler:

<form asp-page="/profile" asp-page-handler="create"></form>

The generated HTML:

<form action="/?page=%2Fprofile&amp;handler=create" method="post">

The asp-page & asp-page-handler attributes are applicable only to Razor pages and must not be mixed with the asp-route, asp-controller, and asp-action attributes.

However, asp-route-{value} , asp-all-route-data , asp-fragment can be used with asp-page attribute 

Specifying the HTTP protocol & Host

asp-protocol

The asp-protocol attribute sets the protocol to be used in the URL (such as https).

For Example :

<form asp-protocol="https" asp-controller="Home" asp-action="Create">

The generated HTML:

<form href="https://localhost/Home/Create">Create</form>

asp-host

The asp-host attribute sets the hostname in the generated URL

For Example:

<form asp-protocol="https" asp-host="microsoft.com"
   asp-controller="Home" asp-action="About">

The generated HTML:

<form href="https://microsoft.com/Home/About">

Anti Forgery Tokens

asp-antiforgery

The form Tag Helper automatically generates a hidden Antiforgery taken called as “Request Verification Token” to prevent the Cross-site request forgery (also known as XSRF) attack.

Example

<form asp-controller="Home" asp-action="Create">

or

<form asp-controller="Home" asp-action="Create" asp-antiforgery=”true”>

The above code translated into

<form method="post" action="/Home/Create">
    <input name="__RequestVerificationToken" type="hidden" 
    value="CfDJ8PlIso5McDBOjgPkVg9O4mnNiAE8U0HkVlA9e-Mtc76u7fSjCnoy909Co49eGlbyJxpp-nYphF_XkOrPo0tTGdygc2H8nCtZCcGURMZ9Uf01fPOg5jRARxTHXnb8N6yYADtdQSnJItXtYsir8GCWqZM" />
</form>

If you wish to disable, then setting the asp-antiforgery to false.

<form asp-controller="Home" asp-action="Create" asp-antiforgery=”false”>

Which gets translates into

<form method="post" action="/Home/Create">
</form>

Summary

In this tutorial, we looked at the <Form> Tag helper in ASP.NET Core.