ASP.NET Core 的 Razor 语法参考

Razor 是一种标记语法，用于将基于服务器的代码嵌入网页中。 Razor 语法由 Razor 标记、C# 和 HTML 组成。包含 Razor 的文件通常具有 .cshtml 文件扩展名。在 Razor 组件文件 (.razor) 中也可以找到 Razor 。

呈现 HTML

默认 Razor 语言为 HTML。从 Razor 标记呈现 HTML 与从 HTML 文件呈现 HTML 并没有什么不同。服务器会按原样呈现 .cshtml Razor 文件中的 HTML 标记。

Razor 语法

Razor 支持 C#，并使用 @ 符号从 HTML 转换为 C#。 Razor 计算 C# 表达式，并将它们呈现在 HTML 输出中。

当 @ 符号后跟 Razor 保留关键字时，它会转换为 Razor 特定标记。否则会转换为纯 C#。

若要对 Razor 标记中的 @ 符号进行转义，请使用另一个 @ 符号：

CSHTML复制

@@Username

该代码在 HTML 中使用单个 @ 符号呈现：

HTML复制

@Username

包含电子邮件地址的 HTML 属性和内容不将 @ 符号视为转换字符。 Razor 分析不会处理以下示例中的电子邮件地址：

CSHTML复制

[email protected]

隐式 Razor 表达式

隐式 Razor 表达式以 @ 开头，后跟 C# 代码：

CSHTML复制

@DateTime.Now
@DateTime.IsLeapYear(2016)

隐式表达式不能包含空格，但 C# await 关键字除外。如果该 C# 语句具有明确的结束标记，则可以混用空格：

CSHTML复制

@await DoSomething("hello", "world")

隐式表达式不能包含 C# 泛型，因为括号 (<>) 内的字符会被解释为 HTML 标记。以下代码无效：

CSHTML复制

@GenericMethod()

上述代码生成与以下错误之一类似的编译器错误：

"int" 元素未结束。所有元素都必须自结束或具有匹配的结束标记。
无法将方法组 "GenericMethod" 转换为非委托类型 "object"。是否希望调用此方法?`

泛型方法调用必须包装在显式 Razor 表达式或 Razor 代码块中。

显式 Razor 表达式

显式 Razor 表达式由 @ 符号和平衡圆括号组成。若要呈现上一周的时间，可使用以下 Razor 标记：

CSHTML复制

Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))

将计算 @() 括号中的所有内容，并将其呈现到输出中。

前面部分中所述的隐式表达式通常不能包含空格。在下面的代码中，不会从当前时间减去一周：

CSHTML复制

Last week: @DateTime.Now - TimeSpan.FromDays(7)

该代码呈现以下 HTML：

HTML复制

Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)

可以使用显式表达式将文本与表达式结果串联起来：

CSHTML复制

@{
    var joe = new Person("Joe", 33);
}

Age@(joe.Age)

如果不使用显式表达式，

[email protected]

会被视为电子邮件地址，因此会呈现 [email protected]。如果编写为显式表达式，则呈现 Age33。

显式表达式可用于从 .cshtml 文件中的泛型方法呈现输出。以下标记显示了如何更正之前出现的由 C# 泛型的括号引起的错误。此代码以显式表达式的形式编写：

CSHTML复制

@(GenericMethod())

表达式编码

计算结果为字符串的 C# 表达式采用 HTML 编码。计算结果为 IHtmlContent 的 C# 表达式直接通过 IHtmlContent.WriteTo 呈现。计算结果不为 IHtmlContent 的 C# 表达式通过 ToString 转换为字符串，并在呈现前进行编码。

CSHTML复制

@("Hello World")

该代码呈现以下 HTML：

HTML复制

<span>Hello World</span>

该 HTML 在浏览器中显示为：

复制

Hello World

HtmlHelper.Raw 输出不进行编码，但呈现为 HTML 标记。

警告

对未经审查的用户输入使用 HtmlHelper.Raw 会带来安全风险。用户输入可能包含恶意的 JavaScript 或其他攻击。审查用户输入比较困难。应避免对用户输入使用 HtmlHelper.Raw。

CSHTML复制

@Html.Raw("Hello World")

该代码呈现以下 HTML：

HTML复制

Hello World

Razor 代码块

Razor 代码块以 @ 开头，并括在 {} 中。代码块内的 C# 代码不会呈现，这点与表达式不同。一个视图中的代码块和表达式共享相同的作用域并按顺序进行定义：

CSHTML复制

@{
    var quote = "The future depends on what you do today. - Mahatma Gandhi";
}

@quote

@{
    quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.";
}

@quote

该代码呈现以下 HTML：

HTML复制

The future depends on what you do today. - Mahatma Gandhi
Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.

隐式转换

代码块中的默认语言为 C#，不过，Razor 页面可以转换回 HTML：

CSHTML复制

@{
    var inCSharp = true;
    Now in HTML, was in C# @inCSharp
}

带分隔符的显式转换

若要定义应呈现 HTML 的代码块子节，请使用 Razor 标记将要呈现的字符括起来：

CSHTML复制

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    Name: @person.Name
}

使用此方法可呈现未被 HTML 标记括起来的 HTML。如果没有 HTML 或 Razor 标记，会发生 Razor 运行时错误。

标记可用于在呈现内容时控制空格：

仅呈现标记之间的内容。
标记之前或之后的空格不会显示在 HTML 输出中。

使用 @: 的显式行转换

若要在代码块内以 HTML 的形式呈现整个行的其余内容，请使用 @: 语法：

CSHTML复制

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    @:Name: @person.Name
}

如果代码中没有 @:，会生成 Razor 运行时错误。

Razor 文件中多余的 @ 字符可能会导致代码块中后面的语句发生编译器错误。这些编译器错误可能难以理解，因为实际错误发生在报告的错误之前。将多个隐式/显式表达式合并到单个代码块以后，经常会发生此错误。

控制结构

控制结构是对代码块的扩展。代码块的各个方面（转换为标记、内联 C#）同样适用于以下结构：

条件语句 @、else if、else 和 @switch

@if 控制何时运行代码：

CSHTML复制

@if (value % 2 == 0)
{
    The value was even.
}

else 和 else if 不需要 @ 符号：

CSHTML复制

@if (value % 2 == 0)
{
    The value was even.
}
else if (value >= 1337)
{
    The value is large.
}
else
{
    The value is odd and small.
}

以下标记展示如何使用 switch 语句：

CSHTML复制

@switch (value)
{
    case 1:
        The value is 1!
        break;
    case 1337:
        Your number is 1337!
        break;
    default:
        Your number wasn't 1 or 1337.
        break;
}

循环语句 @for、@foreach、@while 和 @dowhile

可以使用循环控制语句呈现模板化 HTML。若要呈现一组人员：

CSHTML复制

@{
    var people = new Person[]
    {
          new Person("Weston", 33),
          new Person("Johnathon", 41),
          ...
    };
}

支持以下循环语句：

@for

CSHTML复制

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    Name: @person.Name
    Age: @person.Age
}

@foreach

CSHTML复制

@foreach (var person in people)
{
    Name: @person.Name
    Age: @person.Age
}

@while

CSHTML复制

@{ var i = 0; }
@while (i < people.Length)
{
    var person = people[i];
    Name: @person.Name
    Age: @person.Age

    i++;
}

@do while

CSHTML复制

@{ var i = 0; }
@do
{
    var person = people[i];
    Name: @person.Name
    Age: @person.Age

    i++;
} while (i < people.Length);

复合语句 @using

在 C# 中，using 语句用于确保释放对象。在 Razor 中，可使用相同的机制来创建包含附加内容的 HTML 帮助程序。在下面的代码中，HTML 帮助程序使用 @using 语句呈现

标记：

CSHTML复制

@using (Html.BeginForm())
{
    
        Email: 
        
    
}

@try、catch、finally

异常处理与 C# 类似：

CSHTML复制

@try
{
    throw new InvalidOperationException("You did something invalid.");
}
catch (Exception ex)
{
    The exception message: @ex.Message
}
finally
{
    The finally statement.
}

@lock

Razor 可以使用 lock 语句来保护关键节：

CSHTML复制

@lock (SomeLock)
{
    // Do critical section work
}

注释

Razor 支持 C# 和 HTML 注释：

CSHTML复制

@{
    /* C# comment */
    // Another C# comment
}

该代码呈现以下 HTML：

HTML复制

在呈现网页之前，服务器会删除 Razor 注释。 Razor 使用 @* *@ 来分隔注释。以下代码已被注释禁止，因此服务器不呈现任何标记：

CSHTML复制

@*
    @{
        /* C# comment */
        // Another C# comment
    }
    
*@

指令

Razor 指令由隐式表达式表示：@ 符号后跟保留关键字。指令通常用于更改视图分析方式或启用不同的功能。

通过了解 Razor 如何为视图生成代码，更易理解指令的工作原理。

CSHTML复制

@{
    var quote = "Getting old ain't for wimps! - Anonymous";
}

Quote of the Day: @quote

该代码生成与下面类似的类：

C#复制

public class _Views_Something_cshtml : RazorPage
{
    public override async Task ExecuteAsync()
    {
        var output = "Getting old ain't for wimps! - Anonymous";

        WriteLiteral("/r/nQuote of the Day: ");
        Write(output);
        WriteLiteral("");
    }
}

本文后面的检查为视图生成的 Razor C# 类部分说明了如何查看此生成的类。

@attribute

@attribute 指令将给定的属性添加到生成的页或视图的类中。以下示例添加 [Authorize] 属性：

CSHTML复制

@attribute [Authorize]

@functions

@functions 指令允许将 C# 成员（字段、属性和方法）添加到生成的类中：

CSHTML复制

@functions {
    // C# members (fields, properties, and methods)
}

例如:

CSHTML复制

@functions {
    public string GetHello()
    {
        return "Hello";
    }
}

From method: @GetHello()

该代码生成以下 HTML 标记：

HTML复制

From method: Hello

以下代码是生成的 Razor C# 类：

C#复制

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Razor;

public class _Views_Home_Test_cshtml : RazorPage
{
    // Functions placed between here 
    public string GetHello()
    {
        return "Hello";
    }
    // And here.
#pragma warning disable 1998
    public override async Task ExecuteAsync()
    {
        WriteLiteral("\r\nFrom method: ");
        Write(GetHello());
        WriteLiteral("\r\n");
    }
#pragma warning restore 1998

@inherits

@inherits 指令对视图继承的类提供完全控制：

CSHTML复制

@inherits TypeNameOfClassToInheritFrom

下面的代码是一种自定义 Razor 页面类型：

C#复制

using Microsoft.AspNetCore.Mvc.Razor;

public abstract class CustomRazorPage : RazorPage
{
    public string CustomText { get; } = 
        "Gardyloo! - A Scottish warning yelled from a window before dumping" +
        "a slop bucket on the street below.";
}

CustomText 显示在视图中：

CSHTML复制

@inherits CustomRazorPage

Custom text: @CustomText

该代码呈现以下 HTML：

HTML复制


    Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping
    a slop bucket on the street below.

@model 和 @inherits 可在同一视图中使用。 @inherits 可位于视图导入的 _ViewImports.cshtml 文件中：

CSHTML复制

@inherits CustomRazorPage

下面的代码是一种强类型视图：

CSHTML复制

@inherits CustomRazorPage

The Login Email: @Model.Email
Custom text: @CustomText

如果在模型中传递“[email protected]”，视图将生成以下 HTML 标记：

HTML复制

The Login Email: [email protected]

    Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping
    a slop bucket on the street below.

@inject

@inject 指令允许 Razor 页面将服务从服务容器注入到视图。有关详细信息，请参阅视图中的依赖关系注入。

@model

此方案仅适用于 MVC 视图和 Razor Pages (.cshtml)。

@model 指令指定传递到视图或页面的模型类型：

CSHTML复制

@model TypeNameOfModel

在使用个人用户帐户创建的 ASP.NET Core MVC 或 Razor Pages 应用中，Views/Account/Login.cshtml 包含以下模型声明：

CSHTML复制

@model LoginViewModel

生成的类继承自 RazorPage：

C#复制

public class _Views_Account_Login_cshtml : RazorPage

Razor 公开了 Model 属性，用于访问传递到视图的模型：

CSHTML复制

The Login Email: @Model.Email

@model 指令指定 Model 属性的类型。该指令将 RazorPage 中的 T 指定为生成的类，视图便派生自该类。如果未指定 @model 指令，则 Model 属性的类型为 dynamic。有关详细信息，请参阅强类型模型和 @model 关键字。

@namespace

@namespace 指令：

设置生成的 Razor 页面、MVC 视图或 Razor 组件的类的命名空间。
从目录树中最近的导入文件、_ViewImports.cshtml（视图或页面）或 _Imports.razor (Razor) 中设置页面、视图或组件类的根派生命名空间。

CSHTML复制

@namespace Your.Namespace.Here

对于下表中显示的 Razor Pages 示例：

每个页面都导入 Pages/_ViewImports.cshtml 。
Pages/_ViewImports.cshtml 包含 @namespace Hello.World 。
每个页面都有 Hello.World，作为其命名空间的根。

页面	命名空间
Pages/Index.cshtml	`Hello.World`
Pages/MorePages/Page.cshtml	`Hello.World.MorePages`
Pages/MorePages/EvenMorePages/Page.cshtml	`Hello.World.MorePages.EvenMorePages`

上述关系适用于与 MVC 视图和 Razor 组件一起使用的导入文件。

当多个导入文件具有 @namespace 指令时，最靠近目录树中的页面、视图或组件的文件将用于设置根命名空间。

如果前面示例中的 EvenMorePages 文件夹具有包含 @namespace Another.Planet 的导入文件（或 Pages/MorePages/EvenMorePages/Page.cshtml 文件包含 @namespace Another.Planet），则结果如下表所示。

页面	命名空间
Pages/Index.cshtml	`Hello.World`
Pages/MorePages/Page.cshtml	`Hello.World.MorePages`
Pages/MorePages/EvenMorePages/Page.cshtml	`Another.Planet`

@page

.cshtml 文件第一行上的 @page 指令表示该文件是 Razor Page 。有关详细信息，请参阅 ASP.NET Core 中的 Razor 页面介绍。

@section

此方案仅适用于 MVC 视图和 Razor Pages (.cshtml)。

@section 指令与 MVC 和 Razor Pages 布局结合使用，允许视图或页面将内容呈现在 HTML 页面的不同部分。有关详细信息，请参阅 ASP.NET Core 中的布局。

@using

@using 指令用于向生成的视图添加 C# using 指令：

CSHTML复制

@using System.IO
@{
    var dir = Directory.GetCurrentDirectory();
}
@dir

模板化 Razor 委托

通过 Razor 模板，可使用以下格式定义 UI 代码片段：

CSHTML复制

@...

下面的示例演示如何指定模板化 Razor 委托作为 Func。为委托封装的方法的参数指定动态类型。将对象类型指定为委托的返回值。该模板与 Pet（具有 Name 属性）的 List 一起使用。

C#复制

public class Pet
{
    public string Name { get; set; }
}

CSHTML复制

@{
    Func petTemplate = @You have a pet named @item.Name.;

    var pets = new List
    {
        new Pet { Name = "Rin Tin Tin" },
        new Pet { Name = "Mr. Bigglesworth" },
        new Pet { Name = "K-9" }
    };
}

使用 foreach 语句提供的 pets 呈现该模板：

CSHTML复制

@foreach (var pet in pets)
{
    @petTemplate(pet)
}

呈现的输出：

HTML复制

You have a pet named Rin Tin Tin.
You have a pet named Mr. Bigglesworth.
You have a pet named K-9.

还可以提供内联 Razor 模板作为方法的参数。如下示例中，Repeat 方法收到一个 Razor 模板。该方法使用模板生成 HTML 内容，其中包含列表中提供的重复项：

CSHTML复制

@using Microsoft.AspNetCore.Html

@functions {
    public static IHtmlContent Repeat(IEnumerable items, int times,
        Func template)
    {
        var html = new HtmlContentBuilder();

        foreach (var item in items)
        {
            for (var i = 0; i < times; i++)
            {
                html.AppendHtml(template(item));
            }
        }

        return html;
    }
}

使用前面示例中的 pets 列表，调用 Repeat 方法以及：

Pet 的 List。
每只宠物的重复次数。
用于无序列表的列表项的内联模板。

CSHTML复制


    @Repeat(pets, 3, @@item.Name)

呈现的输出：

HTML复制


    Rin Tin Tin
    Rin Tin Tin
    Rin Tin Tin
    Mr. Bigglesworth
    Mr. Bigglesworth
    Mr. Bigglesworth
    K-9
    K-9
    K-9

标记帮助程序

此方案仅适用于 MVC 视图和 Razor Pages (.cshtml)。

标记帮助程序有三个相关指令。

指令	函数
@addTagHelper	向视图提供标记帮助程序。
@removeTagHelper	从视图中删除以前添加的标记帮助程序。
@tagHelperPrefix	指定标记前缀，以启用标记帮助程序支持并阐明标记帮助程序的用法。

Razor 保留关键字

Razor 关键字

page（需要 ASP.NET Core 2.1 或更高版本）
namespace
functions
inherits
model
section
helper（ASP.NET Core 当前不支持）

Razor 关键字使用 @(Razor Keyword) 进行转义（例如，@(functions)）。

C# Razor 关键字

case
do
default
for
foreach
if
else
lock
switch
try
catch
finally
using
while

C# Razor 关键字必须使用 @(@C# Razor Keyword) 进行双转义（例如，@(@case)）。第一个 @ 对 Razor 分析器转义。第二个 @ 对 C# 分析器转义。

Razor 不使用的保留关键字

class

检查为视图生成的 Razor C# 类

在 .NET Core SDK 2.1 或更高版本中，Razor SDK 负责编译 Razor 文件。生成项目时，Razor SDK 在项目根目录中生成 obj///Razor 目录。 Razor 目录中的目录结构反映项目的目录结构。

在面向 .NET Core 2.1 的 ASP.NET Core 2.1 Razor Pages 项目中，请考虑以下目录结构：

Areas/
- Admin/
  - Pages/
    - Index.cshtml
    - Index.cshtml.cs
Pages/
- Shared/
  - _Layout.cshtml
- _ViewImports.cshtml
- _ViewStart.cshtml
- Index.cshtml
- Index.cshtml.cs

在 Debug 配置下生成项目将生成以下 obj 目录：

obj/
- Debug/
  - netcoreapp2.1/
    - Razor/
      - Areas/
        
        Admin/
        
        Pages/
        
        Index.g.cshtml.cs
      - Pages/
        
        Shared/
        
        _Layout.g.cshtml.cs
        
        _ViewImports.g.cshtml.cs
        
        _ViewStart.g.cshtml.cs
        
        Index.g.cshtml.cs

若要查看 Pages/Index.cshtml 的生成类，请打开 obj/Debug/netcoreapp2.1/Razor/Pages/Index.g.cshtml.cs 。

视图查找和区分大小写

Razor 视图引擎为视图执行区分大小写的查找。但是，实际查找取决于基础文件系统：

基于文件的源：
- 在使用不区分大小写的文件系统的操作系统（例如，Windows）上，物理文件提供程序查找不区分大小写。例如，return View("Test") 可匹配 /Views/Home/Test.cshtml、 /Views/home/test.cshtml 以及任何其他大小写变体。
- 在区分大小写的文件系统（例如，Linux、OSX 以及使用 EmbeddedFileProvider 构建的文件系统）上，查找区分大小写。例如，return View("Test") 专门匹配 /Views/Home/Test.cshtml。
预编译视图：在 ASP.NET Core 2.0 及更高版本中，预编译视图查找在所有操作系统上均不区分大小写。该行为与 Windows 上物理文件提供程序的行为相同。如果两个预编译视图仅大小写不同，则查找的结果具有不确定性。

建议开发人员将文件和目录名称的大小写与以下项的大小写匹配：

区域、控制器和操作名称。
Razor 页面。

匹配大小写可确保无论使用哪种基础文件系统，部署都能找到其视图。

ASP.NET Core 的 Razor 语法参考

呈现 HTML

Razor 语法

隐式 Razor 表达式

显式 Razor 表达式

表达式编码

Razor 代码块

隐式转换

带分隔符的显式转换

使用 @: 的显式行转换

控制结构

条件语句 @、else if、else 和 @switch

循环语句 @for、@foreach、@while 和 @dowhile

复合语句 @using

@try、catch、finally

@lock

注释

指令

@attribute

@functions

@inherits

@inject

@model

@namespace

@page

@section

@using

模板化 Razor 委托

标记帮助程序

Razor 保留关键字

Razor 关键字

C# Razor 关键字

Razor 不使用的保留关键字

检查为视图生成的 Razor C# 类

视图查找和区分大小写

你可能感兴趣的:(ASP.NET Core 的 Razor 语法参考)