What a tag helper is
A tag helper is a C# class that the compiler matches to an HTML element or attribute by name. In the text of a view it is plain HTML: the element or attribute is written as usual, and the compiler rewrites it into calls of the helper. Nothing in the markup syntax marks it; which elements are tag helpers depends on the helpers that have been added to the file and on the attributes the elements have. The parser therefore reads a tag helper's tag as ordinary markup, with one change: in a tag that is bound to a helper, the attribute values are C# expressions rather than text (asp-for="Email" names the model member Email).
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
<form asp-controller="Account" asp-action="Login" method="post">
<label asp-for="Email"></label>
<input asp-for="Email" class="form-control" />
<span asp-validation-for="Email" class="text-danger"></span>
<a asp-page="/Index" asp-route-id="@Model.Id">Home</a>
</form>
<partial name="_Footer" />
<environment include="Development"><script src="debug.js"></script></environment>
Directives for scope
| Directive | Value | Effect |
|---|---|---|
@addTagHelper | *, Assembly; Namespace.Type, Assembly; wildcards at the end of the type name (Namespace.Email*, Assembly) | Makes the helpers available in this file and, in an import file, in every file below it. |
@removeTagHelper | The same two parts | Removes helpers added by a file further out. |
@tagHelperPrefix | A prefix such as th: | Only elements that start with the prefix (<th:label>) can be helpers; it also makes their use visible in the text. Once per file. |
These three read the rest of the line as their value; double quotes around it are optional, but a quote that is opened must be closed. The lookup text is checked by the compiler for the shape type, assembly ("Invalid tag helper directive look up text"); the viewer reports only unbalanced quotes and a missing value.
Directives in _ViewImports.cshtml apply to every view in its folder and below; an empty _ViewImports.cshtml in a subfolder adds nothing and removes nothing, since the files are combined rather than replaced.
Syntax inside a helper's tag
- Opt-out. A
!after the<turns the helper off for that element:<!span asp-validation-for="Email"></!span>. It must be on both the start and the end tag. The!is removed from the output. (<!DOCTYPEis not an opt-out.) - Self-closing. A helper that does not allow content may be written
<input asp-for="X" />. A helper declared with a structure of "without end tag" cannot have an end tag; one declared as "normal or self-closing" accepts either. - C# in the tag declaration. Razor expressions are allowed in attribute values, but not in the tag name or the attribute names of a tag that a helper binds:
<input @(cond ? "disabled" : "") asp-for="X" />is an error ("Tag helpers cannot have C# in an element's attribute declaration area"). Conditional C# goes in a value, or the attribute is set in the helper. - Attribute names. A helper attribute name has the shape
asp-for(lower case, hyphens). A dictionary-valued attribute uses a prefix and a key:asp-route-id="5",asp-route-page="x",asp-all-route-data. An indexer attribute name with a prefix but no key is an error.
Built-in tag helpers the viewer recognises
The text alone cannot show which helpers a project has, since they come from compiled assemblies. The viewer lists as tag helper uses: every attribute whose name starts with asp- (the attributes of the form, input, label, select, textarea, validation, link, script, image, anchor and cache helpers), and the elements <partial>, <component>, <environment>, <cache>, <distributed-cache> and <persist-component-state>. Helpers of other packages and your own are not recognised.
Tag helpers and components
Blazor components are not tag helpers, and the two are not mixed in one file kind: a .razor file uses components and directive attributes, a .cshtml file uses tag helpers (and can render a Blazor component through the <component> element or the component tag helper). The tag helper directives are parsed in both kinds of file, since they belong to the shared parser.