What a directive is
A directive is an @ and a reserved word that the compiler acts on rather than writes: it names the base class, the namespaces, the route, the model type or the members of the generated class. The word is matched exactly and case-sensitively (@Page is not @page); a word that is not a directive of the file kind is an implicit expression (@code in a .cshtml file is the expression code). The set depends on the kind of file; the table below says which.
Each directive is one of three shapes:
- Single line. The keyword, then its tokens separated by spaces or tabs, then an optional
;, then the end of the line. Nothing may follow on the line (the error is "Unexpected literal ... following the directive. Expected newline"). - Code block. The keyword, white space (new lines and comments allowed), then
{C# members}.@codeand@functionsare this shape; so is@documentation, whose body is XML. - Razor block. The keyword, a name, then
{markup}. Only@section.
A directive must be the first thing on its line (only white space may come before it on the line); otherwise the error is "The directive must appear at the start of the line". A directive that may occur once (singly occurring) and is written twice is an error ("may only occur once per document"). Tokens must be separated by white space; a missing token is "Directive must have a value" (or an error that names the kind of token expected).
@page "/orders/{id:int}"
@using Shop.Models
@inject IOrderService Orders
@layout MainLayout
@typeparam TItem where TItem : class
@attribute [Authorize(Roles = "admin")]
@code {
[Parameter] public int Id { get; set; }
}
Token kinds
| Token | What is accepted | Error when it is not |
|---|---|---|
| type | A C# type name: dotted and global:: names, generic argument lists, ?, array brackets, pointers, tuples. | expects a type name |
| member | One identifier. | expects an identifier |
| namespace | Identifiers separated by dots. | expects a namespace name |
| string | A double-quoted C# string literal (a verbatim @"..." too). | expects a string surrounded by double quotes |
| attribute | A C# attribute list in square brackets, balanced. | expects a C# attribute enclosed within [ and ] |
| boolean | true or false. | expects a boolean literal |
| identifier or expression | A dotted name, or @(...). | expects an identifier or an explicit expression |
| generic constraint | The word where, the same type parameter name as the preceding member token, and the constraint list to the end of the line. | "is not valid in this position. Valid options are where", and a mismatch error for a different parameter name |
The tag helper directives (@addTagHelper, @removeTagHelper, @tagHelperPrefix) read the rest of the line instead: its text, optionally in double quotes (a missing closing quote is an error), is the value.
The directives
| Directive | Shape and tokens | .razor | .cshtml | Occurs | Effect |
|---|---|---|---|---|---|
@addTagHelper | single line: lookup text (*, Assembly or Type, Assembly, wildcards allowed) | yes | yes | many | Makes tag helpers available. Tag helpers. |
@attribute | single line: attribute | yes | yes | many | Adds a C# attribute to the generated class, e.g. [Authorize] or [Route(...)]. |
@code | code block | yes | no | many | Adds members to the component class. An alias of @functions for components. |
@documentation | code block with XML inside | yes | yes | once | XML documentation for the generated class. Language version 12 (preview): in older versions it is an ordinary expression, and a warning says the meaning will change. |
@functions | code block | yes | yes | many | Adds members (fields, properties, methods) to the generated class. |
@implements | single line: type | yes | yes | many | The generated class implements the interface. |
@inherits | single line: type | yes | yes | once | The base class of the generated class. |
@inject | single line: type, member | yes | yes | many | A property of that type, filled from the service container. |
@layout | single line: type | yes | no | once | The layout component of a component (a LayoutAttribute). Older Web Pages hosts also had a @layout that took a path: see versions. |
@model | single line: type | no | yes | once | The type of Model: the base class becomes RazorPage<T>. Without it Model is dynamic. |
@namespace | single line: namespace | yes | yes | once | The namespace of the generated class, and the root for files below an import file. |
@page | single line: string (optional in views) | yes (required) | yes (optional) | once in views; a component may have several | In a view: this file is a Razor Page, the string is its route template. In a component: it is routable at that URL. |
@preservewhitespace | single line: boolean | yes | no | once | Keep (true) or trim (false, the default) white space in the rendered markup of the component. |
@removeTagHelper | single line: lookup text | yes | yes | many | Removes tag helpers added earlier. |
@rendermode | single line: identifier or expression | yes (not in imports) | no | once | The render mode of the component: InteractiveServer, InteractiveWebAssembly, InteractiveAuto or an instance. |
@section | Razor block: name, { markup } | no | yes | many | Content for a section of the layout. Sections cannot nest. |
@tagHelperPrefix | single line: prefix | yes | yes | once | Elements must start with the prefix to use tag helpers. |
@typeparam | single line: member, optional generic constraint | yes | no | many | A generic type parameter of the component class. |
@using | single line: namespace, static Type, or an alias | yes | yes | many | A C# using directive; in a component it also puts that namespace's components in scope. With a parenthesis it is a C# using statement instead. |
Words that look like directives but are not: @helper (the older helper syntax; ASP.NET Core reports "The helper directive is not supported"), @class (reserved: "is a reserved word and cannot be used in implicit expressions"), and in components @model and @section. In older ASP.NET hosts there were also @layout (a path) and @sessionstate.
Where each directive may appear
- In an import file (
_Imports.razor,_ViewImports.cshtml) the useful ones are@using,@inject,@layout,@namespace,@addTagHelper,@removeTagHelper,@tagHelperPrefix,@typeparam,@preservewhitespace,@attribute,@implementsand@inherits. The component directives@code,@functionsand@rendermodedo not apply to a component import file. - The directive sets above are those registered by the compiler for the kinds component, component import and legacy (view).
@using in detail
@using System.Linq
@using static System.Math
@using Json = System.Text.Json
@using (Html.BeginForm()) { <p>in a form</p> }
After @using, a parenthesis means a statement; an identifier, static or global means a directive that runs to the end of the line (an optional ; is allowed). Namespace imports and aliases cannot be written inside a code block: inside a block, using var x = ...; is a C# using declaration, and a using directive there is the error "Namespace imports and type aliases cannot be placed within code blocks".