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.
Table of Contents
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.
- Generates URL for the action attribute and method attribute using the asp-controller, asp-action & asp-area.
- Generates the Route Parameters, Query strings & URL Fragments using the attributes like asp-route-{value}, asp-all-route-data & asp-fragment etc.
- 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.
- asp-controller
- asp-action
- asp-route
- asp-all-route-data
- asp-route-{value}
- asp-area
- asp-fragment
- asp-page
- asp-page-handler
- asp-host
- asp-protocol
- 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
1 2 3 | <form asp-controller="Home"> |
The above code translates into
1 2 3 | <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
1 2 3 | <form asp-controller="Home" asp-action="Create"> |
The above code translates into
1 2 3 | <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
1 2 3 | <form asp-area=”Profile” asp-controller="Home" asp-action="Create"> |
The above code translated into
1 2 3 | <form method="post" action="/Profile/Home/Create"> |
For, Areas to work correctly, the route must have area specified as shown below.
1 2 3 | {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
1 2 3 | {controller}/{action}/{id?} |
To include id parameter in the URL we use asp-route-{value} attribute, where {value} is replaced by the id.
Example
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-route-id=”12”> |
Would translate as
1 2 3 | <form method="post" action="/Home/Create/12"> |
Multiple parameters.
1 2 3 | {controller}/{action}/{id?}/{val?} |
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-route-id=”12” asp-route-val=”whatever”> |
Would translate as
1 2 3 | <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
1 2 3 | {controller}/{action} |
Then this tag helper,
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-route-id=”12”> |
Translates into
1 2 3 | <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.
1 2 3 4 5 6 7 8 9 | @{ var data= new Dictionary<string, string> { { "Id", "12" }, { "test", "anything" } }; } |
For the Route below
1 2 3 | {controller=Home}/{action=Index}/{id?} |
The following asp-all-route-data tag attribute
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-all-route-data=”data”> |
Translates into
1 2 3 | <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
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-route-id=”12” asp-fragment=”test”> |
is translated to
1 2 3 | <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.
1 2 3 4 5 6 7 8 9 | app.UseMvc( Routes.maproute ( Roues => { “Default”, “{controller=Home}/{action=Index}/{id?}”); } }); |
In the above route, “Default” is the name of the route.
Hence
1 2 3 | <Form asp-route="default"> |
Translates into
1 2 3 | <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
1 2 3 | <form asp-page="/profile"> |
This translates into
1 2 3 | <form action="/?page=%2Fprofile" method="post"> |
If no page name is specified, the tag helper will generate a link to the current page.
1 2 3 | <form asp-page=""></form> |
1 2 3 | <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:
1 2 3 | <form asp-page="/profile" asp-page-handler="create"></form> |
The generated HTML:
1 2 3 | <form action="/?page=%2Fprofile&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 :
1 2 3 | <form asp-protocol="https" asp-controller="Home" asp-action="Create"> |
The generated HTML:
1 2 3 | <form href="https://localhost/Home/Create">Create</form> |
asp-host
The asp-host attribute sets the hostname in the generated URL
For Example:
1 2 3 4 | <form asp-protocol="https" asp-host="microsoft.com" asp-controller="Home" asp-action="About"> |
The generated HTML:
1 2 3 | <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
1 2 3 | <form asp-controller="Home" asp-action="Create"> |
or
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-antiforgery=”true”> |
The above code translated into
1 2 3 4 5 6 | <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.
1 2 3 | <form asp-controller="Home" asp-action="Create" asp-antiforgery=”false”> |
Which gets translates into
1 2 3 4 | <form method="post" action="/Home/Create"> </form> |
Summary
In this tutorial, we looked at the <Form> Tag helper in ASP.NET Core.
Why is it better to use Form Tag Helpers than to specify the action directly?