Two families of parser
- System.Web.Razor (the .NET Framework): the original parser, in three versions that shipped with ASP.NET Web Pages and ASP.NET MVC. Written for C# and Visual Basic; the file has no
@code, no components and no tag helpers. Directives:@inherits @functions @section @helper @layout @sessionstate(C#),@model(MVC), and for Visual Basic@Code @Functions @Section @Helper @Layout @SessionState @Imports @Inherits @Option @ModelType. The keywordnamespaceandclassare reserved. - Microsoft.AspNetCore.Razor.Language (ASP.NET Core and Blazor): rewritten for C# only, with extensible directives (each directive is described by a data record: its tokens, its shape and how often it may occur), tag helpers, components and language versions. Its parser is also the one behind the Razor editors in Visual Studio and Visual Studio Code. The compiler now lives in the roslyn repository.
Versions
| Version | Host | What it brought |
|---|---|---|
| Razor 1 | ASP.NET Web Pages 1.0, ASP.NET MVC 3 | The syntax itself: @ expressions and blocks, @:, <text>, @* *@, sections and layouts, @helper, .cshtml and .vbhtml. |
| Razor 2 and 3 | Web Pages 2 and 3, MVC 4 and 5 | The same syntax refined; the parser source of these versions is System.Web.Razor. |
| Language version 1.0, 1.1 | ASP.NET Core 1.0, 1.1 | New compiler. Tag helpers (@addTagHelper, @removeTagHelper, @tagHelperPrefix), @inject, @model, import files _ViewImports.cshtml. |
| 2.0 | ASP.NET Core 2.0 | Razor Pages: @page. |
| 2.1 | ASP.NET Core 2.1 | @namespace. |
| 3.0 | ASP.NET Core 3.0 | Components (.razor): @code, @layout, @typeparam, @attribute, @implements, _Imports.razor and directive attributes. |
| 5.0 | .NET 5 | @preservewhitespace. |
| 6.0 to 9.0 | .NET 6 to 9 | 6.0: generic type constraints on @typeparam. 8.0: @rendermode and @formname. The versions in between and 9.0 changed behaviour of the parser and the generated code, not the syntax listed here. |
| 10.0 | (not shipped) | The compiler has a version 10.0 that no release used. |
| 11.0 | the current release | The default (latest) language version of the compiler. |
| 12.0 | preview | @documentation { ... }, XML documentation for the generated class. In lower versions @documentation is read as an expression, with a warning. |
The compiler accepts the language version in the project (the RazorLangVersion property of the SDK: 1.0 to 12.0, latest, preview). The scanner here reads the syntax of the newest versions: it does not change its rules by version.
How a file becomes a class
- Parse: the text becomes a syntax tree of markup, code, directives, comments and transitions (the rules of the previous pages).
- Tag helper and component binding: elements are matched with tag helpers (views) or components (
.razor); directive attributes are lowered to calls. - Directives: directive nodes set the base class, namespace, route, model, injected members and attributes; import files are applied first.
- Lowering and code generation: an intermediate tree is written as a C# class:
ExecuteAsyncfor a view,BuildRenderTreefor a component.
In the SDK build the generated files are not kept unless EmitCompilerGeneratedFiles is set to true; then they are under obj/Debug/<framework>/generated/. The compiler runs as a Roslyn source generator. Nothing of this is evaluated by the viewer.
Tools that read Razor
- Visual Studio and Visual Studio Code with the C# Dev Kit: editors with formatting, completion and diagnostics from the real parser.
- TextMate grammars: the Razor language extension carries
aspnetcorerazor.tmLanguage.jsonwith embedded HTML, CSS, JavaScript and C# grammars; these colour text by regular-expression rules and do not report problems. - The test suites of the compiler hold hundreds of small
.cshtmland.razorfiles, many damaged on purpose (missing braces, unterminated comments and strings, helpers, malformed directives). They are the corpus of the viewer's tests.
The viewer's scanner
The scanner (formats/shared/razor.js) is a single pass over the text with the states of the real parser: markup, code, expression, directive, comment, transition. It reads markup with its own tag, attribute, comment and script rules, and cuts the text into segments: markup, code, comment, directive word, escape, directive attribute, <text> tag. Markup segments are coloured by the HTML colouring (with the code blanked out so tags and attributes read across it) and code segments by the C# or Visual Basic colouring. Every byte of the file belongs to exactly one segment. Nesting is limited to 150 levels and a failed bracket search is limited in total, so no input takes more than a few seconds per megabyte; text that the scanner cannot place is left as markup or code, never dropped.