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复制
<p>@@Username</p>
该代码在 HTML 中使用单个 @
符号呈现:
HTML复制
<p>@Username</p>
包含电子邮件地址的 HTML 属性和内容不将 @
符号视为转换字符。 Razor 分析不会处理以下示例中的电子邮件地址:
CSHTML复制
<a href="mailto:Support@contoso.com">Support@contoso.com</a>
隐式 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"。 是否希望调用此方法?`
泛型方法调用必须包装在显式 Razor 表达式或 Razor 代码块中。
显式 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>
隐式转换
代码块中的默认语言为 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#)同样适用于以下结构:
条件语句 @、else if、else 和 @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 和 @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];
<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 comment -->
该代码呈现以下 HTML:
HTML复制
<!-- HTML comment -->
在呈现网页之前,服务器会删除 Razor 注释。 Razor 使用 @* *@
来分隔注释。 以下代码已被注释禁止,因此服务器不呈现任何标记:
CSHTML复制
@*
@{
/* C# comment */
// Another C# comment
}
<!-- HTML 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>");
}
}
本文后面的检查为视图生成的 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";
}
}
<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
@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 页面将服务从服务容器注入到视图。 有关详细信息,请参阅视图中的依赖关系注入。
@model
此方案仅适用于 MVC 视图和 Razor 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
。 有关详细信息,请参阅强类型模型和 @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();
}
<p>@dir</p>
模板化 Razor 委托
通过 Razor 模板,可使用以下格式定义 UI 代码片段:
CSHTML复制
@<tag>...</tag>
下面的示例演示如何指定模板化 Razor 委托作为 Func<T,TResult>。 为委托封装的方法的参数指定动态类型。 将对象类型指定为委托的返回值。 该模板与 Pet
(具有 Name
属性)的 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>。 - 每只宠物的重复次数。
- 用于无序列表的列表项的内联模板。
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 视图和 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/<build_configuration>/<target_framework_moniker>/Razor 目录 。 Razor 目录中的目录结构反映项目的目录结构 。
在面向 .NET Core 2.1 的 ASP.NET Core 2.1 Razor Pages 项目中,请考虑以下目录结构:
- Areas/
- Admin/
- Pages/
- Index.cshtml
- Index.cshtml.cs
- Pages/
- Admin/
- Pages/
- Shared/
- _Layout.cshtml
- _ViewImports.cshtml
- _ViewStart.cshtml
- Index.cshtml
- Index.cshtml.cs
- Shared/
在 Debug 配置下生成项目将生成以下 obj 目录 :
- obj/
- Debug/
- netcoreapp2.1/
- Razor/
- Areas/
- Admin/
- Pages/
- Index.g.cshtml.cs
- Pages/
- Admin/
- Pages/
- Shared/
- _Layout.g.cshtml.cs
- _ViewImports.g.cshtml.cs
- _ViewStart.g.cshtml.cs
- Index.g.cshtml.cs
- Shared/
- Areas/
- Razor/
- netcoreapp2.1/
- Debug/
若要查看 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。
- 在使用不区分大小写的文件系统的操作系统(例如,Windows)上,物理文件提供程序查找不区分大小写。 例如,
- 预编译视图:在 ASP.NET Core 2.0 及更高版本中,预编译视图查找在所有操作系统上均不区分大小写。 该行为与 Windows 上物理文件提供程序的行为相同。 如果两个预编译视图仅大小写不同,则查找的结果具有不确定性。
建议开发人员将文件和目录名称的大小写与以下项的大小写匹配:
- 区域、控制器和操作名称。
- Razor 页面。
匹配大小写可确保无论使用哪种基础文件系统,部署都能找到其视图。