ASP.NET Core 的 Razor 语法参考

蔚落 2023-09-30 07:53 15阅读 0赞

作者：[Rick Anderson][]、[Taylor Mullen][] 和 [Dan Vicarel][]

Razor 是一种标记语法，用于将基于 .NET 的代码嵌入网页中。 Razor 语法由 Razor 标记、C\# 和 HTML 组成。 包含 Razor 的文件通常具有 `.cshtml` 文件扩展名。 Razor 也可在 [Razor component][] 文件 (`.razor`) 中找到。 Razor 语法类似于各种 JavaScript 单页应用程序 (SPA) 框架（如 Angular、React、VueJs 和 Svelte）的模板化引擎。 有关详细信息，请参阅[使用 JavaScript 服务在 ASP.NET Core 中创建单页应用程序][JavaScript _ ASP.NET Core]。

[Introduction to ASP.NET Web Programming Using the Razor Syntax][] 提供了许多使用 Razor 语法编程的示例。 尽管该主题是为 ASP.NET 而不是 ASP.NET Core 编写的，但大多数示例适用于 ASP.NET Core。

### 呈现 HTML ###

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

### Razor 语法 ###

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

当 `@` 符号后跟 [Razor reserved keyword][] 时，它会转换为 Razor 特定标记。 否则会转换为纯 HTML。

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

CSHTML复制

<p>@@Username</p>

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

HTML复制

<p>@Username</p>

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

CSHTML复制

<a href="mailto:Support@contoso.com">Support@contoso.com</a>

#### 可缩放的向量图形 (SVG) ####

支持 [SVG][][foreignObject][] 元素：

HTML复制

@{
        string message = "foreignObject example with Scalable Vector Graphics (SVG)";
    }
    
    <svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
        <rect x="0" y="0" rx="10" ry="10" width="200" height="200" stroke="black" 
            fill="none" />
        <foreignObject x="20" y="20" width="160" height="160">
            <p>@message</p>
        </foreignObject>
    </svg>

### 隐式 Razor 表达式 ###

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

CSHTML复制

<p>@DateTime.Now</p>
    <p>@DateTime.IsLeapYear(2016)</p>

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

CSHTML复制

<p>@await DoSomething("hello", "world")</p>

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

CSHTML复制

<p>@GenericMethod<int>()</p>

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

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

泛型方法调用必须包装在 [explicit Razor expression][] 或 [Razor code block][] 中。

### 显式 Razor 表达式 ###

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

CSHTML复制

<p>Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))</p>

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

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

CSHTML复制

<p>Last week: @DateTime.Now - TimeSpan.FromDays(7)</p>

该代码呈现以下 HTML：

HTML复制

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

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

CSHTML复制

@{
        var joe = new Person("Joe", 33);
    }
    
    <p>Age@(joe.Age)</p>

如果不使用显式表达式，`<p>Age@joe.Age</p>` 会被视为电子邮件地址，因此会呈现 `<p>Age@joe.Age</p>`。 如果编写为显式表达式，则呈现 `<p>Age33</p>`。

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

CSHTML复制

<p>@(GenericMethod<int>())</p>

### 表达式编码 ###

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

CSHTML复制

@("<span>Hello World</span>")

上述代码呈现以下 HTML：

HTML复制

<span>Hello World</span>

HTML 在浏览器中显示为纯文本：

<span>Hello World</span>

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

警告

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

CSHTML复制

@Html.Raw("<span>Hello World</span>")

该代码呈现以下 HTML：

HTML复制

<span>Hello World</span>

### Razor 代码块 ###

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

CSHTML复制

@{
        var quote = "The future depends on what you do today. - Mahatma Gandhi";
    }
    
    <p>@quote</p>
    
    @{
        quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.";
    }
    
    <p>@quote</p>

该代码呈现以下 HTML：

HTML复制

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

在代码块中，使用标记将[本地函数][Link 1]声明为用作模板化方法：

CSHTML复制

@{
        void RenderName(string name)
        {
            <p>Name: <strong>@name</strong></p>
        }
    
        RenderName("Mahatma Gandhi");
        RenderName("Martin Luther King, Jr.");
    }

该代码呈现以下 HTML：

HTML复制

<p>Name: <strong>Mahatma Gandhi</strong></p>
    <p>Name: <strong>Martin Luther King, Jr.</strong></p>

#### 隐式转换 ####

代码块中的默认语言是 C\#，但 Razor 页面可以转换回 HTML：

CSHTML复制

@{
        var inCSharp = true;
        <p>Now in HTML, was in C# @inCSharp</p>
    }

#### 带分隔符的显式转换 ####

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

CSHTML复制

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

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

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

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

#### 显式行转换 ####

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

CSHTML复制

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

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

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

### 控制结构 ###

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

#### 条件 `@if, else if, else, and @switch` ####

`@if` 控制何时运行代码：

CSHTML复制

@if (value % 2 == 0)
    {
        <p>The value was even.</p>
    }

`else` 和 `else if` 不需要 `@` 符号：

CSHTML复制

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

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

CSHTML复制

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

#### 循环 `@for, @foreach, @while, and @do while` ####

可以使用循环控制语句呈现模板化 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];
        <p>Name: @person.Name</p>
        <p>Age: @person.Age</p>
    }

`@foreach`

CSHTML复制

@foreach (var person in people)
    {
        <p>Name: @person.Name</p>
        <p>Age: @person.Age</p>
    }

`@while`

CSHTML复制

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

`@do while`

CSHTML复制

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

#### 复合语句 `@using` ####

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

CSHTML复制

@using (Html.BeginForm())
    {
        <div>
            Email: <input type="email" id="Email" value="">
            <button>Register</button>
        </div>
    }

#### `@try, catch, finally` ####

异常处理与 C\# 类似：

CSHTML复制

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

#### `@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";
    }
    
    <div>Quote of the Day: @quote</div>

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

C\#复制

public class _Views_Something_cshtml : RazorPage<dynamic>
    {
        public override async Task ExecuteAsync()
        {
            var output = "Getting old ain't for wimps! - Anonymous";
    
            WriteLiteral("/r/n<div>Quote of the Day: ");
            Write(output);
            WriteLiteral("</div>");
        }
    }

本文稍后部分 [Inspect the Razor C\# class generated for a view][Inspect the Razor C_ class generated for a view] 介绍如何查看此生成的类。

#### `@attribute` ####

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

CSHTML复制

@attribute [Authorize]

#### `@code` ####

*此方案仅适用于 组件 (`.razor`)。*

`@code` 块使 [Razor component][] 能够将 C\# 成员（字段、属性和方法）添加到组件：

razor复制

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

对于 Razor 组件，`@code` 是 [@functions][functions] 的别名，建议优先于 `@functions` 使用。 允许多个 `@code` 块。

#### `@functions` ####

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

CSHTML复制

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

在 [Razor components][Razor component] 中，请使用 `@code` 而不是 `@functions` 来添加 C\# 成员。

例如：

CSHTML复制

@functions {
        public string GetHello()
        {
            return "Hello";
        }
    }
    
    <div>From method: @GetHello()</div>

该代码生成以下 HTML 标记：

HTML复制

<div>From method: Hello</div>

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

C\#复制

using System.Threading.Tasks;
    using Microsoft.AspNetCore.Mvc.Razor;
    
    public class _Views_Home_Test_cshtml : RazorPage<dynamic>
    {
        // Functions placed between here 
        public string GetHello()
        {
            return "Hello";
        }
        // And here.
    #pragma warning disable 1998
        public override async Task ExecuteAsync()
        {
            WriteLiteral("\r\n<div>From method: ");
            Write(GetHello());
            WriteLiteral("</div>\r\n");
        }
    #pragma warning restore 1998

`@functions` 方法有标记时，会用作模板化方法：

CSHTML复制

@{
        RenderName("Mahatma Gandhi");
        RenderName("Martin Luther King, Jr.");
    }
    
    @functions {
        private void RenderName(string name)
        {
            <p>Name: <strong>@name</strong></p>
        }
    }

该代码呈现以下 HTML：

HTML复制

<p>Name: <strong>Mahatma Gandhi</strong></p>
    <p>Name: <strong>Martin Luther King, Jr.</strong></p>

#### `@implements` ####

`@implements` 指令为生成的类实现接口。

以下示例实现 [System.IDisposable][]，以便可以调用 [Dispose][] 方法：

CSHTML复制

@implements IDisposable
    
    <h1>Example</h1>
    
    @functions {
        private bool _isDisposed;
    
        ...
    
        public void Dispose() => _isDisposed = true;
    }

#### `@inherits` ####

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

CSHTML复制

@inherits TypeNameOfClassToInheritFrom

以下代码是自定义 Razor 页面类型：

C\#复制

using Microsoft.AspNetCore.Mvc.Razor;
    
    public abstract class CustomRazorPage<TModel> : RazorPage<TModel>
    {
        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<TModel>
    
    <div>Custom text: @CustomText</div>

该代码呈现以下 HTML：

HTML复制

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

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

CSHTML复制

@inherits CustomRazorPage<TModel>

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

CSHTML复制

@inherits CustomRazorPage<TModel>
    
    <div>The Login Email: @Model.Email</div>
    <div>Custom text: @CustomText</div>

如果在模型中传递“rick@contoso.com”，视图将生成以下 HTML 标记：

HTML复制

<div>The Login Email: rick@contoso.com</div>
    <div>
        Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping
        a slop bucket on the street below.
    </div>

#### `@inject` ####

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

#### `@layout` ####

*此方案仅适用于 组件 (`.razor`)。*

`@layout` 指令为具有 [@page][page] 指令的可路由 Razor 组件指定布局。 布局组件用于避免代码重复和不一致。 有关详细信息，请参阅 [ASP.NET Core Blazor layouts][]。

#### `@model` ####

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

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

CSHTML复制

@model TypeNameOfModel

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

CSHTML复制

@model LoginViewModel

生成的类继承自 `RazorPage<dynamic>`：

C\#复制

public class _Views_Account_Login_cshtml : RazorPage<LoginViewModel>

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

CSHTML复制

<div>The Login Email: @Model.Email</div>

`@model` 指令指定 `Model` 属性的类型。 该指令将 `RazorPage<T>` 中的 `T` 指定为生成的类，视图便派生自该类。 如果未指定 `@model` 指令，则 `Model` 属性的类型为 `dynamic`。 有关详细信息，请参阅 [Strongly typed models and the @model keyword][Strongly typed models and the _model keyword]。

#### `@namespace` ####

`@namespace` 指令：

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

CSHTML复制

@namespace Your.Namespace.Here

对于下表中所示的 Razor 页面示例：

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

<table>  表 1  
 <thead> 
  <tr> 
   <th>页</th> 
   <th>命名空间</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>Pages/Index.cshtml</code></td> 
   <td><code>Hello.World</code></td> 
  </tr> 
  <tr> 
   <td><code>Pages/MorePages/Page.cshtml</code></td> 
   <td><code>Hello.World.MorePages</code></td> 
  </tr> 
  <tr> 
   <td><code>Pages/MorePages/EvenMorePages/Page.cshtml</code></td> 
   <td><code>Hello.World.MorePages.EvenMorePages</code></td> 
  </tr> 
 </tbody> 
</table>

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

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

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

<table>  表 2  
 <thead> 
  <tr> 
   <th>页</th> 
   <th>命名空间</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>Pages/Index.cshtml</code></td> 
   <td><code>Hello.World</code></td> 
  </tr> 
  <tr> 
   <td><code>Pages/MorePages/Page.cshtml</code></td> 
   <td><code>Hello.World.MorePages</code></td> 
  </tr> 
  <tr> 
   <td><code>Pages/MorePages/EvenMorePages/Page.cshtml</code></td> 
   <td><code>Another.Planet</code></td> 
  </tr> 
 </tbody> 
</table>

#### `@page` ####

`@page` 指令具有不同的效果，具体取决于其所在文件的类型。 指令：

*  在 `.cshtml` 文件中表示该文件是 Razor 页面。 有关详细信息，请参阅[自定义路由][Link 3]和 。
 *  指定 Razor 组件应直接处理请求。 有关详细信息，请参阅 [ASP.NET Core Blazor routing and navigation][]。

#### `@preservewhitespace` ####

*此方案仅适用于 组件 (`.razor`)。*

设置为 `false`（默认值）时，如果出现以下情况，则会删除来自 Razor 组件 (`.razor`) 的呈现标记中的空格：

*  元素中的前导或尾随空白。
 *  `RenderFragment` 参数中的前导或尾随空白。 例如，传递到另一个组件的子内容。
 *  在 C\# 代码块（例如 `@if` 和 `@foreach`）之前或之后。

#### `@section` ####

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

`@section` 指令与 [MVC and Razor Pages layouts][] 结合使用，以使视图或页面能够在 HTML 页面的不同部分呈现内容。 有关详细信息，请参阅 [ASP.NET Core 中的布局][MVC and Razor Pages layouts]。

#### `@using` ####

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

CSHTML复制

@using System.IO
    @{
        var dir = Directory.GetCurrentDirectory();
    }
    <p>@dir</p>

在 [Razor components][Razor component] 中，`@using` 还可控制哪些组件在范围内。

### 指令属性 ###

Razor 指令属性由隐式表达式表示，`@` 符号后有保留关键字。 指令属性通常会更改元素的分析方式或启用不同的功能。

#### `@attributes` ####

*此方案仅适用于 组件 (`.razor`)。*

`@attributes` 允许组件呈现未声明的属性。 有关详细信息，请参阅 [ASP.NET Core Razor components][]。

#### `@bind` ####

*此方案仅适用于 组件 (`.razor`)。*

组件中的数据绑定通过 `@bind` 属性实现。 有关详细信息，请参阅 [ASP.NET Core Blazor data binding][]。

#### `@bind:culture` ####

*此方案仅适用于 组件 (`.razor`)。*

将 `@bind:culture` 属性与 [@bind][bind] 属性一起使用以提供 [System.Globalization.CultureInfo][] 用于分析和设置值的格式。 有关详细信息，请参阅 [ASP.NET Core Blazor globalization and localization][]。

#### `@on{EVENT}` ####

*此方案仅适用于 组件 (`.razor`)。*

Razor 为组件提供事件处理功能。 有关详细信息，请参阅 [ASP.NET Core Blazor event handling][]。

#### `@on{EVENT}:preventDefault` ####

*此方案仅适用于 组件 (`.razor`)。*

禁止事件的默认操作。

#### `@on{EVENT}:stopPropagation` ####

*此方案仅适用于 组件 (`.razor`)。*

停止事件的事件传播。

#### `@key` ####

*此方案仅适用于 组件 (`.razor`)。*

`@key` 指令属性使组件比较算法保证基于键的值保留元素或组件。 有关详细信息，请参阅 [ASP.NET Core Razor components][ASP.NET Core Razor components 1]。

#### `@ref` ####

*此方案仅适用于 组件 (`.razor`)。*

组件引用 (`@ref`) 提供了一种引用组件实例的方法，以便可以向该实例发出命令。 有关详细信息，请参阅 [ASP.NET Core Razor components][ASP.NET Core Razor components 2]。

#### `@typeparam` ####

*此方案仅适用于 组件 (`.razor`)。*

`@typeparam` 指令声明生成的组件类的`@typeparam`：

razor复制

@typeparam TEntity

支持具有 [where][] 类型约束的泛型类型：

razor复制

@typeparam TEntity where TEntity : IEntity

有关详细信息，请参阅以下文章：

*  [ASP.NET Core Razor components][ASP.NET Core Razor components 3]
 *  [ASP.NET Core Blazor templated components][]

### 模板化 Razor 委托 ###

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

CSHTML复制

@<tag>...</tag>

以下示例说明如何将模板化 Razor 委托指定为 [Func<T,TResult>][Func_T_TResult]。 为委托封装的方法的参数指定[动态类型][Link 4]。 将[对象类型][Link 5]指定为委托的返回值。 该模板与 `Pet`（具有 `Name` 属性）的 [List<T>][List_T] 一起使用。

C\#复制

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

CSHTML复制

@{
        Func<dynamic, object> petTemplate = @<p>You have a pet named <strong>@item.Name</strong>.</p>;
    
        var pets = new List<Pet>
        {
            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复制

<p>You have a pet named <strong>Rin Tin Tin</strong>.</p>
    <p>You have a pet named <strong>Mr. Bigglesworth</strong>.</p>
    <p>You have a pet named <strong>K-9</strong>.</p>

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

CSHTML复制

@using Microsoft.AspNetCore.Html
    
    @functions {
        public static IHtmlContent Repeat(IEnumerable<dynamic> items, int times,
            Func<dynamic, IHtmlContent> 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<T>][List_T]。
 *  每只宠物的重复次数。
 *  用于无序列表的列表项的内联模板。

CSHTML复制

<ul>
        @Repeat(pets, 3, @<li>@item.Name</li>)
    </ul>

呈现的输出：

HTML复制

<ul>
        <li>Rin Tin Tin</li>
        <li>Rin Tin Tin</li>
        <li>Rin Tin Tin</li>
        <li>Mr. Bigglesworth</li>
        <li>Mr. Bigglesworth</li>
        <li>Mr. Bigglesworth</li>
        <li>K-9</li>
        <li>K-9</li>
        <li>K-9</li>
    </ul>

### 标记帮助程序 ###

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

[标记帮助程序][Link 6]有三个相关指令。

<table>  标记帮助程序  
 <thead> 
  <tr> 
   <th>指令</th> 
   <th>函数</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><a href="https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/intro?view=aspnetcore-6.0#add-helper-label" title="@addTagHelper" rel="nofollow">@addTagHelper</a></td> 
   <td>向视图提供标记帮助程序。</td> 
  </tr> 
  <tr> 
   <td><a href="https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/intro?view=aspnetcore-6.0#remove-razor-directives-label" title="@removeTagHelper" rel="nofollow">@removeTagHelper</a></td> 
   <td>从视图中删除以前添加的标记帮助程序。</td> 
  </tr> 
  <tr> 
   <td><a href="https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/intro?view=aspnetcore-6.0#prefix-razor-directives-label" title="@tagHelperPrefix" rel="nofollow">@tagHelperPrefix</a></td> 
   <td>指定标记前缀，以启用标记帮助程序支持并阐明标记帮助程序的用法。</td> 
  </tr> 
 </tbody> 
</table>

### Razor 保留关键字 ###

#### Razor 关键字 ####

*  `page`
 *  `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\# 类 ###

[Razor SDK][] 处理 Razor 文件的编译。 生成项目时，Razor SDK 在项目根目录中生成 `obj/<build_configuration>/<target_framework_moniker>/Razor` 目录。 `Razor` 目录中的目录结构反映项目的目录结构。

请考虑 ASP.NET Core Razor Pages 项目中的以下目录结构：

复制

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

在“调试”配置中生成项目将生成以下 目录：

复制

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 页面。

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

### Razor 使用的导入 ###

以下导入由 ASP.NET Core Web 模板生成，以支持 Razor 文件：

复制

using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.AspNetCore.Mvc.Rendering;
    using Microsoft.AspNetCore.Mvc.ViewFeatures;

### 其他资源 ###

[Introduction to ASP.NET Web Programming Using the Razor Syntax][] 提供了许多使用 Razor 语法编程的示例。

[Rick Anderson]: https://twitter.com/RickAndMSFT
[Taylor Mullen]: https://twitter.com/ntaylormullen
[Dan Vicarel]: https://github.com/Rabadash8820
[Razor component]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/?view=aspnetcore-6.0
[JavaScript _ ASP.NET Core]: https://docs.microsoft.com/zh-cn/aspnet/core/client-side/spa-services?view=aspnetcore-6.0
[Introduction to ASP.NET Web Programming Using the Razor Syntax]: https://docs.microsoft.com/zh-cn/aspnet/web-pages/overview/getting-started/introducing-razor-syntax-c
[Razor reserved keyword]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#razor-reserved-keywords
[SVG]: https://developer.mozilla.org/docs/Web/SVG
[foreignObject]: https://developer.mozilla.org/docs/Web/SVG/Element/foreignObject
[explicit Razor expression]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#explicit-razor-expressions
[Razor code block]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#razor-code-blocks
[Link 1]: https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/classes-and-structs/local-functions
[Inspect the Razor C_ class generated for a view]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#inspect-the-razor-c-class-generated-for-a-view
[functions]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#functions
[System.IDisposable]: https://docs.microsoft.com/zh-cn/dotnet/api/system.idisposable
[Dispose]: https://docs.microsoft.com/zh-cn/dotnet/api/system.idisposable.dispose
[Link 2]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/dependency-injection?view=aspnetcore-6.0
[page]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#page
[ASP.NET Core Blazor layouts]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/layouts?view=aspnetcore-6.0
[Strongly typed models and the _model keyword]: https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/first-mvc-app/adding-model?view=aspnetcore-6.0#strongly-typed-models-and-the--keyword
[Link 3]: https://docs.microsoft.com/zh-cn/aspnet/core/razor-pages/?view=aspnetcore-6.0#custom-routes
[ASP.NET Core Blazor routing and navigation]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/fundamentals/routing?view=aspnetcore-6.0
[MVC and Razor Pages layouts]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/layout?view=aspnetcore-6.0
[ASP.NET Core Razor components]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/?view=aspnetcore-6.0#attribute-splatting-and-arbitrary-parameters
[ASP.NET Core Blazor data binding]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/data-binding?view=aspnetcore-6.0
[bind]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/razor?view=aspnetcore-6.0#bind
[System.Globalization.CultureInfo]: https://docs.microsoft.com/zh-cn/dotnet/api/system.globalization.cultureinfo
[ASP.NET Core Blazor globalization and localization]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/globalization-localization?view=aspnetcore-6.0#globalization
[ASP.NET Core Blazor event handling]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/event-handling?view=aspnetcore-6.0
[ASP.NET Core Razor components 1]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/?view=aspnetcore-6.0#use-key-to-control-the-preservation-of-elements-and-components
[ASP.NET Core Razor components 2]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/?view=aspnetcore-6.0#capture-references-to-components
[where]: https://docs.microsoft.com/zh-cn/dotnet/csharp/language-reference/keywords/where-generic-type-constraint
[ASP.NET Core Razor components 3]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/?view=aspnetcore-6.0#generic-type-parameter-support
[ASP.NET Core Blazor templated components]: https://docs.microsoft.com/zh-cn/aspnet/core/blazor/components/templated-components?view=aspnetcore-6.0
[Func_T_TResult]: https://docs.microsoft.com/zh-cn/dotnet/api/system.func-2
[Link 4]: https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/types/using-type-dynamic
[Link 5]: https://docs.microsoft.com/zh-cn/dotnet/csharp/language-reference/keywords/object
[List_T]: https://docs.microsoft.com/zh-cn/dotnet/api/system.collections.generic.list-1
[Link 6]: https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/intro?view=aspnetcore-6.0
[Razor SDK]: https://docs.microsoft.com/zh-cn/aspnet/core/razor-pages/sdk?view=aspnetcore-6.0