Razor Справочник по синтаксису для ASP.NET CoreRazor syntax reference for ASP.NET Core

По Рик Андерсон (, Кузнецова Маллени " викарел "By Rick Anderson, Taylor Mullen, and Dan Vicarel

Razor — это синтаксис разметки для внедрения серверного кода на веб-страницы.Razor is a markup syntax for embedding server-based code into webpages. RazorСинтаксис состоит из Razor разметки, C# и HTML.The Razor syntax consists of Razor markup, C#, and HTML. Файлы, содержащие Razor обычно, имеют расширение . cshtml .Files containing Razor generally have a .cshtml file extension. Razorтакже находится в файлах Razor Components ( . Razor ).Razor is also found in Razor components files ( .razor ).

Отрисовка HTMLRendering HTML

Языком по умолчанию Razor является HTML.The default Razor language is HTML. Отрисовка HTML из Razor разметки не отличается от отрисовки HTML из HTML-файла.Rendering HTML from Razor markup is no different than rendering HTML from an HTML file. Разметка HTML в CSHTML - Razor файлах отображается на сервере без изменений.HTML markup in .cshtml Razor files is rendered by the server unchanged.

Синтаксис RazorRazor syntax

Razor поддерживает C# и использует @ символ для перехода от HTML к C#.Razor supports C# and uses the @ symbol to transition from HTML to C#. Razor Вычисляет выражения C# и отображает их в выходных данных HTML.Razor evaluates C# expressions and renders them in the HTML output.

Если @ за символом следует Razor зарезервированное ключевое слово, он перемещается в Razor разметку, относящуюся к конкретному.When an @ symbol is followed by a Razor reserved keyword, it transitions into Razor-specific markup. В противном случае он переходит на обычный C#.Otherwise, it transitions into plain C#.

Чтобы экранировать @ символ в Razor разметке, используйте второй @ символ:To escape an @ symbol in Razor markup, use a second @ symbol:

<p>@@Username</p>

Код будет отображен в HTML с одним символом @:The code is rendered in HTML with a single @ symbol:

<p>@Username</p>

HTML-атрибуты и содержимое, включающие адреса электронной почты, не расценивают символ @ как символ перехода.HTML attributes and content containing email addresses don't treat the @ symbol as a transition character. Адреса электронной почты в следующем примере не затрагиваются путем Razor синтаксического анализа:The email addresses in the following example are untouched by Razor parsing:

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

Неявные Razor выраженияImplicit Razor expressions

Неявные Razor выражения начинаются с @ следующего кода C#:Implicit Razor expressions start with @ followed by C# code:

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

Неявные выражения не должны содержать пробелов. Исключением является ключевое слово C# await.With the exception of the C# await keyword, implicit expressions must not contain spaces. Если оператор C# имеет четкое окончание, пробелы вставлять можно:If the C# statement has a clear ending, spaces can be intermingled:

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

Неявные выражения не могут содержать универсальные шаблоны C#, так как символы в угловых скобках (<>) интерпретируются как тег HTML.Implicit expressions cannot contain C# generics, as the characters inside the brackets (<>) are interpreted as an HTML tag. Следующий код является недопустимым :The following code is not valid:

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

Приведенный выше код вызывает ошибку компилятора примерно следующего вида:The preceding code generates a compiler error similar to one of the following:

  • Элемент "int" не был закрыт.The "int" element wasn't closed. Все элементы должны быть самозакрывающимися или иметь соответствующий закрывающий тег.All elements must be either self-closing or have a matching end tag.
  • Не удается преобразовать группу методов "GenericMethod" в не являющийся делегатом тип "object".Cannot convert method group 'GenericMethod' to non-delegate type 'object'. Предполагалось вызывать этот метод?Did you intend to invoke the method?`

Вызовы универсальных методов должны быть заключены в явное Razor выражение или Razor блок кода.Generic method calls must be wrapped in an explicit Razor expression or a Razor code block.

Явные Razor выраженияExplicit Razor expressions

Явные Razor выражения состоят из @ символа с сбалансированной круглой скобкой.Explicit Razor expressions consist of an @ symbol with balanced parenthesis. Для визуализации времени на прошлой неделе Razor используется следующая разметка:To render last week's time, the following Razor markup is used:

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

Любое содержимое в скобках @() вычисляется и отображается в выходных данных.Any content within the @() parenthesis is evaluated and rendered to the output.

Неявные выражения, описанные в предыдущем разделе, обычно не содержат пробелов.Implicit expressions, described in the previous section, generally can't contain spaces. В следующем коде из значения текущего времени неделя не вычитается:In the following code, one week isn't subtracted from the current time:

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

Код отображает следующий HTML:The code renders the following HTML:

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

Явные выражения позволяют объединять результат своего выполнения с дополнительным текстом:Explicit expressions can be used to concatenate text with an expression result:

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

<p>Age@(joe.Age)</p>

Без явного выражения <p>Age@joe.Age</p> обрабатывается как адрес электронной почты, и на выходе отображается <p>Age@joe.Age</p>.Without the explicit expression, <p>Age@joe.Age</p> is treated as an email address, and <p>Age@joe.Age</p> is rendered. Если же текст написан как явное выражение, то вы получите <p>Age33</p>.When written as an explicit expression, <p>Age33</p> is rendered.

Вы можете использовать явные выражения для отображения выходных данных из универсальных методов в файлах CSHTML .Explicit expressions can be used to render output from generic methods in .cshtml files. В следующем примере показано, как исправить ошибку, показанную ранее и вызванную скобками в универсальном шаблоне C#.The following markup shows how to correct the error shown earlier caused by the brackets of a C# generic. Код записывается как явное выражение:The code is written as an explicit expression:

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

Кодирование выраженийExpression encoding

Выражения C#, которые имеют строковое выходное значение, кодируются в формате HTML.C# expressions that evaluate to a string are HTML encoded. Выражения C#, которые имеют значение IHtmlContent, обрабатываются непосредственно с помощью IHtmlContent.WriteTo.C# expressions that evaluate to IHtmlContent are rendered directly through IHtmlContent.WriteTo. Выражения C#, которые не имеют выходное значение IHtmlContent, преобразуются в строку с помощью ToString и кодируются перед обработкой.C# expressions that don't evaluate to IHtmlContent are converted to a string by ToString and encoded before they're rendered.

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

Приведенный выше код отображает следующий HTML:The preceding code renders the following HTML:

&lt;span&gt;Hello World&lt;/span&gt;

HTML-код отображается в браузере как обычный текст:The HTML is shown in the browser as plain text:

<охват > Hello World < /span><span>Hello World</span>

Выходные данные HtmlHelper.Raw не кодируются, но отображаются в виде разметки HTML.HtmlHelper.Raw output isn't encoded but rendered as HTML markup.

Предупреждение

Использование HtmlHelper.Raw с непроверенными входными данными пользователя представляет угрозу безопасности.Using HtmlHelper.Raw on unsanitized user input is a security risk. Эти входные данные могут содержать вредоносный код JavaScript или другие эксплойты.User input might contain malicious JavaScript or other exploits. Очистка вводимых пользователем данных является сложной задачей.Sanitizing user input is difficult. Старайтесь не использовать HtmlHelper.Raw с такими данными.Avoid using HtmlHelper.Raw with user input.

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

Код отображает следующий HTML:The code renders the following HTML:

<span>Hello World</span>

Razor блоки кодаRazor code blocks

Razor блоки кода начинаются с @ и заключаются в {} .Razor code blocks start with @ and are enclosed by {}. В отличие от выражений код C# внутри блоков кода не обрабатывается.Unlike expressions, C# code inside code blocks isn't rendered. Блоки кода и выражения в представлении используют общую область и определяются в следующем порядке:Code blocks and expressions in a view share the same scope and are defined in order:

@{
    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:The code renders the following 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>

В блоках кода объявите локальные функции с помощью разметки для использования в качестве методов создания шаблонов:In code blocks, declare local functions with markup to serve as templating methods:

@{
    void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }

    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

Код отображает следующий HTML:The code renders the following HTML:

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

Неявные переходыImplicit transitions

Языком по умолчанию в блоке кода является C#, но Razor страница может перейти обратно в HTML:The default language in a code block is C#, but the Razor Page can transition back to HTML:

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

Явный переход с разделителямиExplicit delimited transition

Чтобы определить подраздел блока кода, который должен визуализировать HTML, заключите символы для отрисовки с помощью Razor <text> тега:To define a subsection of a code block that should render HTML, surround the characters for rendering with the Razor <text> tag:

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

Используйте этот способ для отрисовки HTML, не заключенного в HTML-теги.Use this approach to render HTML that isn't surrounded by an HTML tag. Без HTML или Razor тега Razor возникает ошибка времени выполнения.Without an HTML or Razor tag, a Razor runtime error occurs.

Тег <text> хорошо подходит для контроля пробелов при отрисовке содержимого:The <text> tag is useful to control whitespace when rendering content:

  • Отрисовывается только содержимое между тегами <text>.Only the content between the <text> tag is rendered.
  • В выходных данных HTML пробелы до или после тега <text> не отображаются.No whitespace before or after the <text> tag appears in the HTML output.

Явный перенос строкиExplicit line transition

Для отрисовки оставшейся части строки в виде HTML внутри блока кода используйте синтаксис @::To render the rest of an entire line as HTML inside a code block, use @: syntax:

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

Без @: кода в коде Razor создается ошибка времени выполнения.Without the @: in the code, a Razor runtime error is generated.

Дополнительные @ символы в Razor файле могут вызвать ошибки компилятора в инструкциях далее в блоке.Extra @ characters in a Razor file can cause compiler errors at statements later in the block. Эти ошибки компилятора может быть трудно проанализировать, так как ошибка фактически возникает раньше, чем указано.These compiler errors can be difficult to understand because the actual error occurs before the reported error. Чаще всего эта ошибка появляется после объединения множества неявных или явных выражений в один блок кода.This error is common after combining multiple implicit/explicit expressions into a single code block.

Управляющие структурыControl structures

Управляющие структуры являются расширением блоков кода.Control structures are an extension of code blocks. Все аспекты блоков кода (переход на разметку, встроенный код C#) также относятся к следующим структурам.All aspects of code blocks (transitioning to markup, inline C#) also apply to the following structures:

Условные выражения @if, else if, else, and @switchConditionals @if, else if, else, and @switch

@if контролирует, когда нужно запускать код:@if controls when code runs:

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

Для else и else if символ @ не требуется:else and else if don't require the @ symbol:

@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:The following markup shows how to use a switch statement:

@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 whileLooping @for, @foreach, @while, and @do while

Операторы выполнения цикла позволяют выполнять отрисовку шаблонного HTML.Templated HTML can be rendered with looping control statements. Отрисовка списка людей:To render a list of people:

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

Поддерживаются следующие операторы выполнения цикла:The following looping statements are supported:

@for

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

@foreach

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

@while

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

    i++;
}

@do while

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

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

Составной оператор @usingCompound @using

В C# оператор using позволяет обеспечить использование какого-то объекта.In C#, a using statement is used to ensure an object is disposed. В Razor для создания вспомогательных функций HTML, содержащих дополнительное содержимое, используется тот же механизм.In Razor, the same mechanism is used to create HTML Helpers that contain additional content. В следующем коде вспомогательные функции HTML используют оператор @using для создания тега <form>:In the following code, HTML Helpers render a <form> tag with the @using statement:

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

@try, catch, finally

Обработка исключений выполняется так же, как в C#:Exception handling is similar to C#:

@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:Razor has the capability to protect critical sections with lock statements:

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

КомментарииComments

Razor поддерживает комментарии C# и HTML:Razor supports C# and HTML comments:

@{
    /* C# comment */
    // Another C# comment
}
<!-- HTML comment -->

Код отображает следующий HTML:The code renders the following HTML:

<!-- HTML comment -->

Razor перед отрисовкой веб-страницы комментарии удаляются с сервера.Razor comments are removed by the server before the webpage is rendered. Razor использует @* *@ для разделения комментариев.Razor uses @* *@ to delimit comments. Следующий код закомментирован, поэтому сервер не отрисовывает разметку:The following code is commented out, so the server doesn't render any markup:

@*
    @{
        /* C# comment */
        // Another C# comment
    }
    <!-- HTML comment -->
*@

ДирективыDirectives

Razor директивы представлены неявными выражениями с зарезервированными ключевыми словами после @ символа.Razor directives are represented by implicit expressions with reserved keywords following the @ symbol. Как правило, директива изменяет способ анализа представления или открывает доступ к дополнительным функциям.A directive typically changes the way a view is parsed or enables different functionality.

Понимание того Razor , как формирует код для представления, упрощает понимание принципов работы директив.Understanding how Razor generates code for a view makes it easier to understand how directives work.

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

<div>Quote of the Day: @quote</div>

Код создает класс, аналогичный следующему:The code generates a class similar to the following:

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#, созданного для представления .Later in this article, the section Inspect the Razor C# class generated for a view explains how to view this generated class.

@attribute

Директива @attribute добавляет данный атрибут к классу созданной страницы или представления.The @attribute directive adds the given attribute to the class of the generated page or view. В следующем примере добавляется атрибут [Authorize]:The following example adds the [Authorize] attribute:

@attribute [Authorize]

@code

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

@codeБлок позволяет Razor компоненту добавлять в компонент элементы C# (поля, свойства и методы):The @code block enables a Razor component to add C# members (fields, properties, and methods) to a component:

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

Для Razor компонентов @code является псевдонимом @functions и рекомендуется для @functions .For Razor components, @code is an alias of @functions and recommended over @functions. Допускается более одного блока @code.More than one @code block is permissible.

@functions

Директива @functions позволяет добавлять элементы C# (поля, свойства и методы) в создаваемый класс:The @functions directive enables adding C# members (fields, properties, and methods) to the generated class:

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

В Razor компонентахиспользуйте @code @functions для добавления членов C#.In Razor components, use @code over @functions to add C# members.

Пример:For example:

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

<div>From method: @GetHello()</div> 

Код создает следующую разметку HTML:The code generates the following HTML markup:

<div>From method: Hello</div>

Следующий код является созданным Razor классом C#:The following code is the generated Razor C# class:

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 служат в качестве методов создания шаблонов при наличии разметки:@functions methods serve as templating methods when they have markup:

@{
    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

@functions {
    private void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }
}

Код отображает следующий HTML:The code renders the following HTML:

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

@implements

Директива @implements реализует интерфейс для созданного класса.The @implements directive implements an interface for the generated class.

В следующем примере реализуется System.IDisposable, чтобы можно было вызывать метод Dispose:The following example implements System.IDisposable so that the Dispose method can be called:

@implements IDisposable

<h1>Example</h1>

@functions {
    private bool _isDisposed;

    ...

    public void Dispose() => _isDisposed = true;
}

@inherits

Директива @inherits позволяет полностью управлять классом, которому наследует представление:The @inherits directive provides full control of the class the view inherits:

@inherits TypeNameOfClassToInheritFrom

Следующий код является пользовательским Razor типом страницы:The following code is a custom Razor page type:

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:The CustomText is displayed in a view:

@inherits CustomRazorPage<TModel>

<div>Custom text: @CustomText</div>

Код отображает следующий HTML:The code renders the following HTML:

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

@model и @inherits могут использоваться в одном представлении.@model and @inherits can be used in the same view. @inherits может находиться в файле _ViewImports.cshtml , который импортируется представлением:@inherits can be in a _ViewImports.cshtml file that the view imports:

@inherits CustomRazorPage<TModel>

Следующий код показывает пример строго типизированного представления:The following code is an example of a strongly-typed view:

@inherits CustomRazorPage<TModel>

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

Если передать в модель "rick@contoso.com", представление создает следующую разметку HTML:If "rick@contoso.com" is passed in the model, the view generates the following HTML markup:

<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 странице внедрить службу из контейнера службы в представление.The @inject directive enables the Razor Page to inject a service from the service container into a view. Дополнительные сведения: Внедрение зависимостей в представления.For more information, see Dependency injection into views.

@layout

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

@layoutДиректива задает макет для Razor компонента.The @layout directive specifies a layout for a Razor component. Компоненты макета используются, чтобы избежать дублирования и несогласованности кода.Layout components are used to avoid code duplication and inconsistency. Для получения дополнительной информации см. Макеты Blazor в ASP.NET Core.For more information, see Макеты Blazor в ASP.NET Core.

@model

Этот сценарий применим только к представлениям и Razor страницам MVC (. cshtml).This scenario only applies to MVC views and Razor Pages (.cshtml).

Директива @model определяет тип модели, передаваемой в представление или страницу:The @model directive specifies the type of the model passed to a view or page:

@model TypeNameOfModel

В ASP.NET Core приложении MVC или Razor pages, созданном с учетными записями отдельных пользователей, представления/учетная запись/имя входа. cshtml содержит следующее объявление модели:In an ASP.NET Core MVC or Razor Pages app created with individual user accounts, Views/Account/Login.cshtml contains the following model declaration:

@model LoginViewModel

Созданный класс наследует от RazorPage<dynamic>:The class generated inherits from RazorPage<dynamic>:

public class _Views_Account_Login_cshtml : RazorPage<LoginViewModel>

Razor предоставляет Model свойство для доступа к модели, передаваемой в представление:Razor exposes a Model property for accessing the model passed to the view:

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

Директива @model задает тип свойства Model.The @model directive specifies the type of the Model property. Директива указывает T в RazorPage<T> — созданном классе, на основе которого создается производное представление.The directive specifies the T in RazorPage<T> that the generated class that the view derives from. Если директива @model не указана, свойство Model имеет тип dynamic.If the @model directive isn't specified, the Model property is of type dynamic. Дополнительные сведения см. в разделе модели со строгой типизацией и @model ключевое слово.For more information, see Strongly typed models and the @model keyword.

@namespace

Директива @namespace:The @namespace directive:

  • Задает пространство имен класса созданной Razor страницы, представления MVC или Razor компонента.Sets the namespace of the class of the generated Razor page, MVC view, or Razor component.
  • Устанавливает корневые производные пространства имен страниц, представлений или классов компонентов из ближайшего файла импорта в дереве каталогов, _ViewImports. cshtml (представления или страницы) или _Imports. Razor ( Razor компоненты).Sets the root derived namespaces of a pages, views, or components classes from the closest imports file in the directory tree, _ViewImports.cshtml (views or pages) or _Imports.razor (Razor components).
@namespace Your.Namespace.Here

Для Razor примера страниц, показанного в следующей таблице:For the Razor Pages example shown in the following table:

  • Каждая страница импортирует Pages/_ViewImports.cshtml .Each page imports Pages/_ViewImports.cshtml .
  • Файл Pages/_ViewImports.cshtml содержит @namespace Hello.World.Pages/_ViewImports.cshtml contains @namespace Hello.World.
  • Каждая страница имеет Hello.World в качестве корня пространства имен.Each page has Hello.World as the root of it's namespace.
СтраницаPage Пространство именNamespace
Pages/index. cshtmlPages/Index.cshtml Hello.World
Pages/MorePages/Page.cshtmlPages/MorePages/Page.cshtml Hello.World.MorePages
Pages/MorePages/EvenMorePages/Page.cshtmlPages/MorePages/EvenMorePages/Page.cshtml Hello.World.MorePages.EvenMorePages

Предыдущие связи применяются к файлам импорта, которые используются в представлениях и Razor компонентах MVC.The preceding relationships apply to import files used with MVC views and Razor components.

Если у нескольких файлов импорта есть директива @namespace, для задания корневого пространства имен используется файл, ближайший к странице, компоненту или представлению в дереве каталогов.When multiple import files have a @namespace directive, the file closest to the page, view, or component in the directory tree is used to set the root namespace.

Если папка EvenMorePages в предыдущем примере содержит файл импорта с @namespace Another.Planet (или же файл Pages/MorePages/EvenMorePages/Page.cshtml содержит @namespace Another.Planet), результат отображается в следующей таблице.If the EvenMorePages folder in the preceding example has an imports file with @namespace Another.Planet (or the Pages/MorePages/EvenMorePages/Page.cshtml file contains @namespace Another.Planet), the result is shown in the following table.

СтраницаPage Пространство именNamespace
Pages/index. cshtmlPages/Index.cshtml Hello.World
Pages/MorePages/Page.cshtmlPages/MorePages/Page.cshtml Hello.World.MorePages
Pages/MorePages/EvenMorePages/Page.cshtmlPages/MorePages/EvenMorePages/Page.cshtml Another.Planet

@page

Директива @page имеет различные эффекты в зависимости от типа файла, в котором она используется.The @page directive has different effects depending on the type of the file where it appears. Директива:The directive:

@pageДиректива в первой строке файла CSHTML указывает на то, что файл является Razor страницей.The @page directive on the first line of a .cshtml file indicates that the file is a Razor Page. Для получения дополнительной информации см. Введение в Razor Pages в ASP.NET Core.For more information, see Введение в Razor Pages в ASP.NET Core.

@section

Этот сценарий применим только к представлениям и Razor страницам MVC (. cshtml).This scenario only applies to MVC views and Razor Pages (.cshtml).

@sectionДиректива используется совместно с Razor разметкой MVC и Pages , позволяя представлениям или страницам отображать содержимое в различных частях HTML-страницы.The @section directive is used in conjunction with MVC and Razor Pages layouts to enable views or pages to render content in different parts of the HTML page. Для получения дополнительной информации см. Макет в ASP.NET Core.For more information, see Макет в ASP.NET Core.

@using

Директива @using добавляет директиву C# using в созданное представление:The @using directive adds the C# using directive to the generated view:

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

В Razor компонентах @using также управляет тем, какие компоненты находятся в области.In Razor components, @using also controls which components are in scope.

Атрибуты директивыDirective attributes

Razor атрибуты директивы представлены неявными выражениями с зарезервированными ключевыми словами после @ символа.Razor directive attributes are represented by implicit expressions with reserved keywords following the @ symbol. Атрибут директивы обычно изменяет способ синтаксического анализа элемента или предоставляет различные функциональные возможности.A directive attribute typically changes the way an element is parsed or enables different functionality.

@attributes

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

@attributes позволяет компоненту обрабатывать необъявленные атрибуты.@attributes allows a component to render non-declared attributes. Для получения дополнительной информации см. Создание и использование компонентов Razor ASP.NET Core.For more information, see Создание и использование компонентов Razor ASP.NET Core.

@bind

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Привязка данных в компонентах выполняется с помощью атрибута @bind.Data binding in components is accomplished with the @bind attribute. Для получения дополнительной информации см. Привязка к данным в ASP.NET Core Blazor.For more information, see Привязка к данным в ASP.NET Core Blazor.

@on{EVENT}

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Razor предоставляет функции обработки событий для компонентов.Razor provides event handling features for components. Для получения дополнительной информации см. Обработка событий Blazor в ASP.NET Core.For more information, see Обработка событий Blazor в ASP.NET Core.

@on{EVENT}:preventDefault

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Запрещает выполнение действия по умолчанию для события.Prevents the default action for the event.

@on{EVENT}:stopPropagation

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Останавливает распространение события.Stops event propagation for the event.

@key

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Атрибут директивы @key заставляет алгоритм сравнения компонентов гарантировать сохранение элементов или компонентов на основе значения ключа.The @key directive attribute causes the components diffing algorithm to guarantee preservation of elements or components based on the key's value. Для получения дополнительной информации см. Создание и использование компонентов Razor ASP.NET Core.For more information, see Создание и использование компонентов Razor ASP.NET Core.

@ref

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Ссылки на компоненты (@ref) предоставляют способ ссылаться на экземпляр компонента, чтобы можно было выполнять команды для этого экземпляра.Component references (@ref) provide a way to reference a component instance so that you can issue commands to that instance. Для получения дополнительной информации см. Создание и использование компонентов Razor ASP.NET Core.For more information, see Создание и использование компонентов Razor ASP.NET Core.

@typeparam

Этот сценарий применим только к Razor компонентам (. Razor).This scenario only applies to Razor components (.razor).

Директива @typeparam объявляет параметр универсального типа для созданного класса компонента.The @typeparam directive declares a generic type parameter for the generated component class. Для получения дополнительной информации см. Шаблонные компоненты Blazor в ASP.NET Core.For more information, see Шаблонные компоненты Blazor в ASP.NET Core.

Шаблонные Razor делегатыTemplated Razor delegates

Razor шаблоны позволяют определить фрагмент пользовательского интерфейса в следующем формате:Razor templates allow you to define a UI snippet with the following format:

@<tag>...</tag>

В следующем примере показано, как указать шаблонный Razor делегат в качестве Func<T,TResult> .The following example illustrates how to specify a templated Razor delegate as a Func<T,TResult>. Динамический тип указывается для параметра метода, инкапсулируемого делегатом.The dynamic type is specified for the parameter of the method that the delegate encapsulates. Тип объекта указывается в качестве возвращаемого значения делегата.An object type is specified as the return value of the delegate. Этот шаблон используется с List<T>объекта Pet, имеющим свойство Name.The template is used with a List<T> of Pet that has a Name property.

public class Pet
{
    public string Name { get; set; }
}
@{
    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" }
    };
}

Шаблон отрисовывается с использованием pets, предоставляемого оператором foreach:The template is rendered with pets supplied by a foreach statement:

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

Отображенные выходные данные:Rendered output:

<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 в качестве аргумента для метода.You can also supply an inline Razor template as an argument to a method. В следующем примере Repeat метод получает Razor шаблон.In the following example, the Repeat method receives a Razor template. Метод использует этот шаблон для создания HTML-содержимого с повторениями элементов из списка:The method uses the template to produce HTML content with repeats of items supplied from a list:

@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;
    }
}

С использованием списка домашних животных из предыдущего примера метод Repeat вызывается следующим образом:Using the list of pets from the prior example, the Repeat method is called with:

  • List<T> объекта Pet.List<T> of Pet.
  • Количество повторений для каждого домашнего животного.Number of times to repeat each pet.
  • Встроенный шаблон, используемый для перечисления элементов неупорядоченного списка.Inline template to use for the list items of an unordered list.
<ul>
    @Repeat(pets, 3, @<li>@item.Name</li>)
</ul>

Отображенные выходные данные:Rendered output:

<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>

Вспомогательные функции теговTag Helpers

Этот сценарий применим только к представлениям и Razor страницам MVC (. cshtml).This scenario only applies to MVC views and Razor Pages (.cshtml).

Существует три директивы, которые относятся к вспомогательным функциям тегов.There are three directives that pertain to Tag Helpers.

ДирективаDirective КомпонентFunction
@addTagHelper Делает вспомогательные функции тегов доступными в представлении.Makes Tag Helpers available to a view.
@removeTagHelper Удаляет из представления вспомогательные функции тегов, добавленные ранее.Removes Tag Helpers previously added from a view.
@tagHelperPrefix Задает префикс тега, который активирует поддержку вспомогательной функции тега и ее использования в явном виде.Specifies a tag prefix to enable Tag Helper support and to make Tag Helper usage explicit.

Razor зарезервированные ключевые словаRazor reserved keywords

Razor словамиRazor keywords

  • page (Требуется ASP.NET Core 2,1 или более поздней версии)page (Requires ASP.NET Core 2.1 or later)
  • namespace
  • functions
  • inherits
  • model
  • section
  • helper (В настоящее время не поддерживается ASP.NET Core)helper (Not currently supported by ASP.NET Core)

Razor Ключевые слова экранированы с помощью @(Razor Keyword) (например, @(functions) ).Razor keywords are escaped with @(Razor Keyword) (for example, @(functions)).

RazorКлючевые слова C#C# Razor keywords

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

RazorКлючевые слова C# должны быть двойным образом экранированы с помощью @(@C# Razor Keyword) (например, @(@case) ).C# Razor keywords must be double-escaped with @(@C# Razor Keyword) (for example, @(@case)). Первый заключается в @ Escape- Razor анализе.The first @ escapes the Razor parser. а второй @ — для обхода C#.The second @ escapes the C# parser.

Зарезервированные ключевые слова не используются RazorReserved keywords not used by Razor

  • class

Проверка Razor класса C#, созданного для представленияInspect the Razor C# class generated for a view

В пакет SDK для .NET Core 2,1 или более поздней версии Razor пакет SDK обрабатывает компиляцию Razor файлов.With .NET Core SDK 2.1 or later, the Razor SDK handles compilation of Razor files. При сборке проекта Razor пакет SDK создает obj/<build_configuration>/<target_framework_moniker>/ Razor каталог в корневом каталоге проекта.When building a project, the Razor SDK generates an obj/<build_configuration>/<target_framework_moniker>/Razor directory in the project root. Структура каталогов в Razor каталоге отражает структуру каталогов проекта.The directory structure within the Razor directory mirrors the project's directory structure.

Рассмотрим следующую структуру каталогов в проекте ASP.NET Core 2,1 Razor страниц, предназначенном для .NET Core 2,1:Consider the following directory structure in an ASP.NET Core 2.1 Razor Pages project targeting .NET Core 2.1:

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

При сборке проекта в конфигурации Отладка создается следующий каталог obj :Building the project in Debug configuration yields the following obj directory:

 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/netcoreapp 2.1/ Razor /Пажес/индекс.г.кштмл.КС .To view the generated class for Pages/Index.cshtml , open obj/Debug/netcoreapp2.1/Razor/Pages/Index.g.cshtml.cs .

Добавьте в MVC-проект ASP.NET следующий класс:Add the following class to the ASP.NET Core MVC project:

#if V2
using Microsoft.AspNetCore.Mvc.Razor.Extensions;
using Microsoft.AspNetCore.Razor.Language;

public class CustomTemplateEngine : MvcRazorTemplateEngine
{
    public CustomTemplateEngine(RazorEngine engine, RazorProject project) 
        : base(engine, project)
    {
    }
        
    public override RazorCSharpDocument GenerateCode(RazorCodeDocument codeDocument)
    {
        var csharpDocument = base.GenerateCode(codeDocument);
        var generatedCode = csharpDocument.GeneratedCode;

        // Look at generatedCode

        return csharpDocument;
    }
}
#endif

В Startup.ConfigureServices переопределите класс RazorTemplateEngine, добавленный MVC, классом CustomTemplateEngine:In Startup.ConfigureServices, override the RazorTemplateEngine added by MVC with the CustomTemplateEngine class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

Установите точку останова в операторе return csharpDocument; класса CustomTemplateEngine.Set a breakpoint on the return csharpDocument; statement of CustomTemplateEngine. Когда выполнение программы остановится в этой точке, просмотрите значение generatedCode.When program execution stops at the breakpoint, view the value of generatedCode.

Представление generatedCode в визуализаторе текста

Поиск данных в представлениях и учет регистраView lookups and case sensitivity

RazorОбработчик представлений выполняет поиск представлений с учетом регистра.The Razor view engine performs case-sensitive lookups for views. Однако фактический поиск зависит от используемой файловой системы.However, the actual lookup is determined by the underlying file system:

  • Источники в виде файлов:File based source:
    • В операционных системах, файловые системы которых не учитывают регистр (например, Windows), поиск поставщика физических файлов не зависит от регистра.On operating systems with case insensitive file systems (for example, Windows), physical file provider lookups are case insensitive. Например, поиск по return View("Test") выводит совпадения /Views/Home/Test.cshtml , /Views/home/test.cshtml и другие варианты с различными сочетаниями регистра.For example, return View("Test") results in matches for /Views/Home/Test.cshtml , /Views/home/test.cshtml , and any other casing variant.
    • В файловых системах, учитывающих регистр (например, в Linux, OSX и где используется EmbeddedFileProvider), поиск выполняется с учетом регистра.On case-sensitive file systems (for example, Linux, OSX, and with EmbeddedFileProvider), lookups are case-sensitive. Например, поиск по return View("Test") дает точное совпадение /Views/Home/Test.cshtml .For example, return View("Test") specifically matches /Views/Home/Test.cshtml .
  • Предварительно скомпилированные представления: в ASP.NET Core 2.0 и более поздних версиях поиск в предварительно скомпилированных представлениях выполняется без учета регистра во всех операционных системах.Precompiled views: With ASP.NET Core 2.0 and later, looking up precompiled views is case insensitive on all operating systems. Это поведение аналогично поведению поставщика физических файлов в Windows.The behavior is identical to physical file provider's behavior on Windows. Если два предварительно скомпилированных представления отличаются только регистром, результат поиска является недетерминированным.If two precompiled views differ only in case, the result of lookup is non-deterministic.

Разработчикам рекомендуется использовать для файлов и каталогов тот же регистр, что и для:Developers are encouraged to match the casing of file and directory names to the casing of:

  • имен областей, контроллеров и действий;Area, controller, and action names.
  • Razor См.Razor Pages.

Совпадающий регистр гарантирует, что развертываемые службы смогут находить свои представления вне зависимости от используемой файловой системы.Matching case ensures the deployments find their views regardless of the underlying file system.

Дополнительные ресурсыAdditional resources

Введение в веб-программирование ASP.NET с помощью Razor Синтаксис предоставляет множество примеров программирования с помощью Razor синтаксиса.Introduction to ASP.NET Web Programming Using the Razor Syntax provides many samples of programming with Razor syntax.