Razor referência de sintaxe para ASP.NET CoreRazor syntax reference for ASP.NET Core

Por Rick Anderson, Taylor Mullene Dan VicarelBy Rick Anderson, Taylor Mullen, and Dan Vicarel

Razor é uma sintaxe de marcação para inserir código baseado em servidor em páginas da Web.Razor is a markup syntax for embedding server-based code into webpages. A Razor sintaxe consiste em Razor marcação, C# e HTML.The Razor syntax consists of Razor markup, C#, and HTML. Os arquivos que contêm Razor geralmente têm uma extensão de arquivo . cshtml .Files containing Razor generally have a .cshtml file extension. Razortambém é encontrado em arquivos de Razor componentes (. Razor).Razor is also found in Razor components files (.razor).

Renderização de HTMLRendering HTML

O Razor idioma padrão é HTML.The default Razor language is HTML. O processamento de HTML da Razor marcação não é diferente do processamento de HTML de um arquivo HTML.Rendering HTML from Razor markup is no different than rendering HTML from an HTML file. A marcação HTML em arquivos . cshtml Razor é renderizada pelo servidor inalterado.HTML markup in .cshtml Razor files is rendered by the server unchanged.

Sintaxe de RazorRazor syntax

Razor dá suporte a C# e usa o @ símbolo para fazer a transição de HTML para C#.Razor supports C# and uses the @ symbol to transition from HTML to C#. Razor avalia as expressões C# e as renderiza na saída HTML.Razor evaluates C# expressions and renders them in the HTML output.

Quando um @ símbolo é seguido por uma Razor palavra-chave reservada, ele faz a transição para uma Razor marcação específica.When an @ symbol is followed by a Razor reserved keyword, it transitions into Razor-specific markup. Caso contrário, ele faz a transição para C# simples.Otherwise, it transitions into plain C#.

Para escapar de um @ símbolo na Razor marcação, use um segundo @ símbolo:To escape an @ symbol in Razor markup, use a second @ symbol:

<p>@@Username</p>

O código é renderizado em HTML com um único símbolo @:The code is rendered in HTML with a single @ symbol:

<p>@Username</p>

Conteúdo e atributos HTML que contêm endereços de email não tratam o símbolo @ como um caractere de transição.HTML attributes and content containing email addresses don't treat the @ symbol as a transition character. Os endereços de email no exemplo a seguir são inalterados pela Razor análise:The email addresses in the following example are untouched by Razor parsing:

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

Expressões implícitas RazorImplicit Razor expressions

As Razor expressões implícitas começam com @ seguido pelo código C#:Implicit Razor expressions start with @ followed by C# code:

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

Com exceção da palavra-chave C# await, expressões implícitas não devem conter espaços.With the exception of the C# await keyword, implicit expressions must not contain spaces. Se a instrução C# tiver uma terminação clara, espaços podem ser misturados:If the C# statement has a clear ending, spaces can be intermingled:

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

Expressões implícitas não podem conter elementos genéricos de C#, pois caracteres dentro de colchetes (<>) são interpretados como uma marca HTML.Implicit expressions cannot contain C# generics, as the characters inside the brackets (<>) are interpreted as an HTML tag. O código a seguir é inválido:The following code is not valid:

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

O código anterior gera um erro de compilador semelhante a um dos seguintes:The preceding code generates a compiler error similar to one of the following:

  • O elemento "int" não foi fechado.The "int" element wasn't closed. Todos os elementos devem ter fechamento automático ou ter uma marca de fim correspondente.All elements must be either self-closing or have a matching end tag.
  • Não é possível converter o grupo de métodos "GenericMethod" em um "object" de tipo não delegado.Cannot convert method group 'GenericMethod' to non-delegate type 'object'. Você pretendia invocar o método?Did you intend to invoke the method?`

Chamadas de método genérico devem ser encapsuladas em uma Razor expressão explícita ou em um Razor bloco de código.Generic method calls must be wrapped in an explicit Razor expression or a Razor code block.

Expressões explícitas RazorExplicit Razor expressions

Expressões explícitas Razor consistem em um @ símbolo com parênteses equilibrados.Explicit Razor expressions consist of an @ symbol with balanced parenthesis. Para renderizar a hora da semana passada, a seguinte Razor marcação é usada:To render last week's time, the following Razor markup is used:

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

Qualquer conteúdo dentro dos parênteses @() é avaliado e renderizado para a saída.Any content within the @() parenthesis is evaluated and rendered to the output.

Expressões implícitas, descritas na seção anterior, geralmente não podem conter espaços.Implicit expressions, described in the previous section, generally can't contain spaces. No código a seguir, uma semana não é subtraída da hora atual:In the following code, one week isn't subtracted from the current time:

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

O código renderiza o HTML a seguir:The code renders the following HTML:

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

Expressões explícitas podem ser usadas para concatenar texto com um resultado de expressão:Explicit expressions can be used to concatenate text with an expression result:

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

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

Sem a expressão explícita, <p>Age@joe.Age</p> é tratado como um endereço de email e <p>Age@joe.Age</p> é renderizado.Without the explicit expression, <p>Age@joe.Age</p> is treated as an email address, and <p>Age@joe.Age</p> is rendered. Quando escrito como uma expressão explícita, <p>Age33</p> é renderizado.When written as an explicit expression, <p>Age33</p> is rendered.

Expressões explícitas podem ser usadas para renderizar a saída de métodos genéricos em arquivos .cshtml.Explicit expressions can be used to render output from generic methods in .cshtml files. A marcação a seguir mostra como corrigir o erro mostrado anteriormente causado pelos colchetes de um C# genérico.The following markup shows how to correct the error shown earlier caused by the brackets of a C# generic. O código é escrito como uma expressão explícita:The code is written as an explicit expression:

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

Codificação de expressãoExpression encoding

Expressões em C# que são avaliadas como uma cadeia de caracteres estão codificadas em HTML.C# expressions that evaluate to a string are HTML encoded. Expressões em C# que são avaliadas como IHtmlContent são renderizadas diretamente por meio IHtmlContent.WriteTo.C# expressions that evaluate to IHtmlContent are rendered directly through IHtmlContent.WriteTo. Expressões em C# que não são avaliadas como IHtmlContent são convertidas em uma cadeia de caracteres por ToString e codificadas antes que sejam renderizadas.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>")

O código anterior processa o seguinte HTML:The preceding code renders the following HTML:

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

O HTML é mostrado no navegador como texto sem formatação:The HTML is shown in the browser as plain text:

<>Olá, mundo < /span de span><span>Hello World</span>

A saída HtmlHelper.Raw não é codificada, mas renderizada como marcação HTML.HtmlHelper.Raw output isn't encoded but rendered as HTML markup.

Aviso

Usar HtmlHelper.Raw em uma entrada do usuário que não está limpa é um risco de segurança.Using HtmlHelper.Raw on unsanitized user input is a security risk. A entrada do usuário pode conter JavaScript mal-intencionado ou outras formas de exploração.User input might contain malicious JavaScript or other exploits. Limpar a entrada do usuário é difícil.Sanitizing user input is difficult. Evite usar HtmlHelper.Raw com a entrada do usuário.Avoid using HtmlHelper.Raw with user input.

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

O código renderiza o HTML a seguir:The code renders the following HTML:

<span>Hello World</span>

Razor blocos de códigoRazor code blocks

Razor os blocos de código começam com @ e são incluídos por {} .Razor code blocks start with @ and are enclosed by {}. Diferente das expressões, o código C# dentro de blocos de código não é renderizado.Unlike expressions, C# code inside code blocks isn't rendered. Blocos de código e expressões em uma exibição compartilham o mesmo escopo e são definidos em ordem: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>

O código renderiza o HTML a seguir: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>

Em blocos de código, declare funções locais com uma marcação para servir como métodos de modelagem: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.");
}

O código renderiza o HTML a seguir:The code renders the following HTML:

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

Transições implícitasImplicit transitions

O idioma padrão em um bloco de código é C#, mas a Razor página pode fazer a transição de volta para o 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>
}

Transição delimitada explícitaExplicit delimited transition

Para definir uma subseção de um bloco de código que deve renderizar HTML, coloque os caracteres para renderização com a Razor <text> marca: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>
}

Use essa abordagem para renderizar HTML que não está circundado por uma marca HTML.Use this approach to render HTML that isn't surrounded by an HTML tag. Sem um HTML ou Razor marca, Razor ocorre um erro de tempo de execução.Without an HTML or Razor tag, a Razor runtime error occurs.

A marca <text> é útil para controlar o espaço em branco ao renderizar conteúdo:The <text> tag is useful to control whitespace when rendering content:

  • Somente o conteúdo entre a marca <text> é renderizado.Only the content between the <text> tag is rendered.
  • Não aparece nenhum espaço em branco antes ou depois da marca <text> na saída HTML.No whitespace before or after the <text> tag appears in the HTML output.

Transição de linha explícitaExplicit line transition

Para renderizar o restante de uma linha inteira como HTML dentro de um bloco de código, use a @: sintaxe: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
}

Sem o @: no código, um Razor erro de tempo de execução é gerado.Without the @: in the code, a Razor runtime error is generated.

@Caracteres extras em um Razor arquivo podem causar erros de compilador em instruções posteriores no bloco.Extra @ characters in a Razor file can cause compiler errors at statements later in the block. Esses erros do compilador podem ser difíceis de entender porque o erro real ocorre antes do erro relatado.These compiler errors can be difficult to understand because the actual error occurs before the reported error. Esse erro é comum após combinar várias expressões implícitas/explícitas em um bloco de código único.This error is common after combining multiple implicit/explicit expressions into a single code block.

Estruturas de controleControl structures

Estruturas de controle são uma extensão dos blocos de código.Control structures are an extension of code blocks. Todos os aspectos dos blocos de código (transição para marcação, C# embutido) também se aplicam às seguintes estruturas:All aspects of code blocks (transitioning to markup, inline C#) also apply to the following structures:

Condicionais @if, else if, else, and @switchConditionals @if, else if, else, and @switch

@if controla quando o código é executado:@if controls when code runs:

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

else e else if não exigem o símbolo @: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>
}

A marcação a seguir mostra como usar uma instrução 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;
}

Loop @for, @foreach, @while, and @do whileLooping @for, @foreach, @while, and @do while

O HTML no modelo pode ser renderizado com instruções de controle em loop.Templated HTML can be rendered with looping control statements. Para renderizar uma lista de pessoas:To render a list of people:

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

Há suporte para as seguintes instruções em loop: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);

@using compostoCompound @using

Em C#, uma instrução using é usada para garantir que um objeto seja descartado.In C#, a using statement is used to ensure an object is disposed. No Razor , o mesmo mecanismo é usado para criar auxiliares HTML que contêm conteúdo adicional.In Razor, the same mechanism is used to create HTML Helpers that contain additional content. No código a seguir, os Auxiliares HTML renderizam uma marca <form> com a instrução @using: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

O tratamento de exceções é semelhante ao de 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 o tem a capacidade de proteger seções críticas com instruções Lock:Razor has the capability to protect critical sections with lock statements:

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

ComentáriosComments

Razor dá suporte a comentários em C# e HTML:Razor supports C# and HTML comments:

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

O código renderiza o HTML a seguir:The code renders the following HTML:

<!-- HTML comment -->

Razor Os comentários são removidos pelo servidor antes que a página da Web seja renderizada.Razor comments are removed by the server before the webpage is rendered. Razor usa @* *@ para delimitar comentários.Razor uses @* *@ to delimit comments. O código a seguir é comentado, de modo que o servidor não renderiza nenhuma marcação:The following code is commented out, so the server doesn't render any markup:

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

DiretivasDirectives

Razor as diretivas são representadas por expressões implícitas com palavras-chave reservadas após o @ símbolo.Razor directives are represented by implicit expressions with reserved keywords following the @ symbol. Uma diretiva geralmente altera o modo como uma exibição é analisada ou habilita uma funcionalidade diferente.A directive typically changes the way a view is parsed or enables different functionality.

Entender como o Razor gera código para uma exibição torna mais fácil entender como as diretivas funcionam.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>

O código gera uma classe semelhante à seguinte: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>");
    }
}

Posteriormente neste artigo, a seção inspecionar a Razor classe C# gerada para uma exibição explica como exibir essa classe gerada.Later in this article, the section Inspect the Razor C# class generated for a view explains how to view this generated class.

@attribute

A diretiva @attribute adiciona o atributo fornecido à classe da página ou exibição gerada.The @attribute directive adds the given attribute to the class of the generated page or view. O exemplo a seguir adiciona o atributo [Authorize]:The following example adds the [Authorize] attribute:

@attribute [Authorize]

@code

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

O @code bloco permite que um Razor componente adicione Membros C# (campos, propriedades e métodos) a um componente: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)
}

Para Razor componentes @code do, é um alias de @functions e é recomendado @functions .For Razor components, @code is an alias of @functions and recommended over @functions. Mais de um bloco de @code é permitido.More than one @code block is permissible.

@functions

A diretiva @functions permite adicionar membros (campos, propriedades e métodos) de C# à classe gerada:The @functions directive enables adding C# members (fields, properties, and methods) to the generated class:

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

Em Razor componentes, use @code @functions para adicionar Membros C#.In Razor components, use @code over @functions to add C# members.

Por exemplo:For example:

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

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

O código gera a seguinte marcação HTML:The code generates the following HTML markup:

<div>From method: Hello</div>

O código a seguir é a Razor classe C# gerada: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

Os métodos @functions servem como métodos de modelagem quando têm uma marcação:@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>
    }
}

O código renderiza o HTML a seguir:The code renders the following HTML:

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

@implements

A diretiva @implements implementa uma interface para a classe gerada.The @implements directive implements an interface for the generated class.

O exemplo a seguir implementa System.IDisposable para que o método Dispose possa ser chamado: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

A diretiva @inherits fornece controle total da classe que a exibição herda:The @inherits directive provides full control of the class the view inherits:

@inherits TypeNameOfClassToInheritFrom

O código a seguir é um Razor tipo de página personalizada: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.";
}

O CustomText é exibido em uma exibição:The CustomText is displayed in a view:

@inherits CustomRazorPage<TModel>

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

O código renderiza o HTML a seguir: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 e @inherits podem ser usados na mesma exibição.@model and @inherits can be used in the same view. @inherits pode estar em um arquivo _ViewImports.cshtml que a exibição importa:@inherits can be in a _ViewImports.cshtml file that the view imports:

@inherits CustomRazorPage<TModel>

O código a seguir é um exemplo de exibição fortemente tipada: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>

Se "rick@contoso.com" for passado no modelo, a exibição gerará a seguinte marcação 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

A @inject diretiva permite que a Razor página Insira um serviço do contêiner de serviço em uma exibição.The @inject directive enables the Razor Page to inject a service from the service container into a view. Para obter mais informações, consulte Injeção de dependência em exibições.For more information, see Dependency injection into views.

@layout

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

A @layout diretiva especifica um layout para componentes roteáveis Razor que têm uma @page diretiva.The @layout directive specifies a layout for routable Razor components that have an @page directive. Os componentes de layout são usados para evitar casos de duplicação e inconsistência no código.Layout components are used to avoid code duplication and inconsistency. Para obter mais informações, consulte BlazorLayouts de ASP.NET Core.For more information, see BlazorLayouts de ASP.NET Core.

@model

Este cenário só se aplica a exibições e Razor páginas do MVC (. cshtml).This scenario only applies to MVC views and Razor Pages (.cshtml).

A diretiva @model especifica o tipo do modelo passado para uma exibição ou página:The @model directive specifies the type of the model passed to a view or page:

@model TypeNameOfModel

Em um ASP.NET Core aplicativo MVC ou Razor páginas criado com contas de usuário individuais, views/Account/Login. cshtml contém a seguinte declaração de modelo: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

A classe gerada herda de RazorPage<dynamic>:The class generated inherits from RazorPage<dynamic>:

public class _Views_Account_Login_cshtml : RazorPage<LoginViewModel>

Razor expõe uma Model propriedade para acessar o modelo passado para a exibição:Razor exposes a Model property for accessing the model passed to the view:

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

A diretiva @model especifica o tipo da propriedade Model.The @model directive specifies the type of the Model property. A diretiva especifica o T em RazorPage<T> da classe gerada da qual a exibição deriva.The directive specifies the T in RazorPage<T> that the generated class that the view derives from. Se a diretiva @model não for especificada, a propriedade Model será do tipo dynamic.If the @model directive isn't specified, the Model property is of type dynamic. Para obter mais informações, consulte modelos fortemente tipados e a @model palavra-chave.For more information, see Strongly typed models and the @model keyword.

@namespace

A diretiva @namespace:The @namespace directive:

  • Define o namespace da classe da Razor página gerada, da exibição MVC ou do Razor componente.Sets the namespace of the class of the generated Razor page, MVC view, or Razor component.
  • Define os namespaces raiz derivados de páginas, exibições ou classes de componentes do arquivo de importações mais próximo na árvore de diretórios, _ViewImports. cshtml (exibições ou páginas) ou _Imports. Razor ( Razor componentes).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

Para o Razor exemplo de páginas mostrado na tabela a seguir:For the Razor Pages example shown in the following table:

  • Cada página importa Pages/_ViewImports.cshtml.Each page imports Pages/_ViewImports.cshtml.
  • Pages/_ViewImports.cshtml contém @namespace Hello.World.Pages/_ViewImports.cshtml contains @namespace Hello.World.
  • Cada página tem Hello.World como a raiz do namespace.Each page has Hello.World as the root of it's namespace.
PáginaPage NamespaceNamespace
Páginas/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

As relações anteriores se aplicam a arquivos de importação usados com exibições e componentes do MVC Razor .The preceding relationships apply to import files used with MVC views and Razor components.

Quando vários arquivos de importação têm uma diretiva @namespace, o arquivo mais próximo da página, exibição ou componente na árvore de diretórios é usado para definir o namespace raiz.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.

Se a pasta EvenMorePages no exemplo anterior tiver um arquivo de importações com @namespace Another.Planet (ou se o arquivo Pages/MorePages/EvenMorePages/Page.cshtml contiver @namespace Another.Planet), o resultado será mostrado na tabela a seguir.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.

PáginaPage NamespaceNamespace
Páginas/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

A diretiva @page tem efeitos diferentes dependendo do tipo do arquivo em que aparece.The @page directive has different effects depending on the type of the file where it appears. A diretiva:The directive:

A @page diretiva na primeira linha de um arquivo . cshtml indica que o arquivo é uma Razor página.The @page directive on the first line of a .cshtml file indicates that the file is a Razor Page. Para obter mais informações, consulte Introdução às Razor páginas no ASP.NET Core.For more information, see Introdução às Razor páginas no ASP.NET Core.

@preservewhitespace

Esse cenário se aplica somente aos Razor componentes ( .razor ).This scenario only applies to Razor components (.razor).

Quando definido como false (padrão), o espaço em branco na marcação renderizada de Razor Components ( .razor ) será removido se:When set to false (default), whitespace in the rendered markup from Razor components (.razor) is removed if:

  • À esquerda ou à direita dentro de um elemento.Leading or trailing within an element.
  • À esquerda ou à direita dentro de um RenderFragment parâmetro.Leading or trailing within a RenderFragment parameter. Por exemplo, conteúdo filho passado para outro componente.For example, child content passed to another component.
  • Ele precede ou segue um bloco de código C#, como @if ou @foreach .It precedes or follows a C# code block, such as @if or @foreach.

@section

Este cenário só se aplica a exibições e Razor páginas do MVC (. cshtml).This scenario only applies to MVC views and Razor Pages (.cshtml).

A @section diretiva é usada em conjunto com o MVC e Razor layouts de páginas para permitir exibições ou páginas para renderizar conteúdo em diferentes partes da página 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. Para obter mais informações, consulte Layout no ASP.NET Core.For more information, see Layout no ASP.NET Core.

@using

A diretiva @using adiciona a diretiva using de C# à exibição gerada:The @using directive adds the C# using directive to the generated view:

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

Em Razor componentes, @using o também controla quais componentes estão no escopo.In Razor components, @using also controls which components are in scope.

Atributos de diretivaDirective attributes

Razor os atributos de diretiva são representados por expressões implícitas com palavras-chave reservadas após o @ símbolo.Razor directive attributes are represented by implicit expressions with reserved keywords following the @ symbol. Um atributo de diretiva normalmente altera a maneira como um elemento é analisado ou habilita uma funcionalidade diferente.A directive attribute typically changes the way an element is parsed or enables different functionality.

@attributes

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

@attributes permite que um componente renderize atributos não declarados.@attributes allows a component to render non-declared attributes. Para obter mais informações, consulte Criar e usar componentes de ASP.NET Core Razor.For more information, see Criar e usar componentes de ASP.NET Core Razor.

@bind

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

A vinculação de dados nos componentes é realizada com o atributo @bind.Data binding in components is accomplished with the @bind attribute. Para obter mais informações, consulte ASP.NET Core Blazor Associação de dados.For more information, see ASP.NET Core Blazor Associação de dados.

@on{EVENT}

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

Razor fornece recursos de manipulação de eventos para componentes do.Razor provides event handling features for components. Para obter mais informações, consulte Manipulação de eventos de ASP.NET Core Blazor.For more information, see Manipulação de eventos de ASP.NET Core Blazor.

@on{EVENT}:preventDefault

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

Impede a ação padrão para o evento.Prevents the default action for the event.

@on{EVENT}:stopPropagation

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

Interrompe a propagação do evento.Stops event propagation for the event.

@key

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

O atributo da diretiva @key faz com que os componentes comparem o algoritmo para garantir a preservação de elementos ou componentes com base no valor da chave.The @key directive attribute causes the components diffing algorithm to guarantee preservation of elements or components based on the key's value. Para obter mais informações, consulte Criar e usar componentes de ASP.NET Core Razor.For more information, see Criar e usar componentes de ASP.NET Core Razor.

@ref

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

Referências de componente (@ref) proporcionam uma maneira de fazer referência a uma instância de componente para que você possa emitir comandos para essa instância.Component references (@ref) provide a way to reference a component instance so that you can issue commands to that instance. Para obter mais informações, consulte Criar e usar componentes de ASP.NET Core Razor.For more information, see Criar e usar componentes de ASP.NET Core Razor.

@typeparam

Esse cenário se aplica somente a Razor componentes (. Razor).This scenario only applies to Razor components (.razor).

A @typeparam diretiva declara um parâmetro de tipo genérico para a classe de componente gerada.The @typeparam directive declares a generic type parameter for the generated component class. Para obter mais informações, consulte ASP.NET Core Blazor componentes modelados.For more information, see ASP.NET Core Blazor componentes modelados.

Delegados de modelo RazorTemplated Razor delegates

Razor os modelos permitem que você defina um trecho de código de interface do usuário com o seguinte formato:Razor templates allow you to define a UI snippet with the following format:

@<tag>...</tag>

O exemplo a seguir ilustra como especificar um delegado de modelo Razor como um Func<T,TResult> .The following example illustrates how to specify a templated Razor delegate as a Func<T,TResult>. O tipo dinâmico é especificado para o parâmetro do método encapsulado pelo delegado.The dynamic type is specified for the parameter of the method that the delegate encapsulates. Um tipo de objeto é especificado como o valor retornado do delegado.An object type is specified as the return value of the delegate. O modelo é usado com uma List<T> de Pet que tem uma propriedade 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" }
    };
}

O modelo é renderizado com pets fornecido por uma instrução foreach:The template is rendered with pets supplied by a foreach statement:

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

Saída renderizada: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>

Você também pode fornecer um modelo embutido Razor como um argumento para um método.You can also supply an inline Razor template as an argument to a method. No exemplo a seguir, o Repeat método recebe um Razor modelo.In the following example, the Repeat method receives a Razor template. O método usa o modelo para produzir o conteúdo HTML com repetições de itens fornecidos em uma lista: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;
    }
}

Usando a lista de animais de estimação do exemplo anterior, o método Repeat é chamado com:Using the list of pets from the prior example, the Repeat method is called with:

  • List<T> de Pet.List<T> of Pet.
  • Número de vezes que deve ser repetido cada animal de estimação.Number of times to repeat each pet.
  • Modelo embutido a ser usado para os itens da lista de uma lista não ordenada.Inline template to use for the list items of an unordered list.
<ul>
    @Repeat(pets, 3, @<li>@item.Name</li>)
</ul>

Saída renderizada: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>

Auxiliares de MarcaTag Helpers

Este cenário só se aplica a exibições e Razor páginas do MVC (. cshtml).This scenario only applies to MVC views and Razor Pages (.cshtml).

Há três diretivas que relacionadas aos Auxiliares de marca.There are three directives that pertain to Tag Helpers.

DiretivaDirective FunçãoFunction
@addTagHelper Disponibiliza os Auxiliares de marca para uma exibição.Makes Tag Helpers available to a view.
@removeTagHelper Remove os Auxiliares de marca adicionados anteriormente de uma exibição.Removes Tag Helpers previously added from a view.
@tagHelperPrefix Especifica um prefixo de marca para habilitar o suporte do Auxiliar de marca e tornar explícito o uso do Auxiliar de marca.Specifies a tag prefix to enable Tag Helper support and to make Tag Helper usage explicit.

Razor Palavras-chave reservadasRazor reserved keywords

Razor Palavras-chaveRazor keywords

  • page (Requer o ASP.NET Core 2,1 ou posterior)page (Requires ASP.NET Core 2.1 or later)
  • namespace
  • functions
  • inherits
  • model
  • section
  • helper (Não tem suporte no momento por ASP.NET Core)helper (Not currently supported by ASP.NET Core)

Razor as palavras-chave têm escape @(Razor Keyword) (por exemplo, @(functions) ).Razor keywords are escaped with @(Razor Keyword) (for example, @(functions)).

RazorPalavras-chave do C#C# Razor keywords

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

As Razor palavras-chave do C# devem ter um escape duplo com @(@C# Razor Keyword) (por exemplo, @(@case) ).C# Razor keywords must be double-escaped with @(@C# Razor Keyword) (for example, @(@case)). O primeiro @ escapa o Razor analisador.The first @ escapes the Razor parser. O segundo @ faz o escape do analisador C#.The second @ escapes the C# parser.

Palavras-chave reservadas não usadas por RazorReserved keywords not used by Razor

  • class

Inspecionar a Razor classe C# gerada para uma exibiçãoInspect the Razor C# class generated for a view

Com o SDK do .NET Core 2,1 ou posterior, o Razor SDK manipula a compilação de Razor arquivos.With .NET Core SDK 2.1 or later, the Razor SDK handles compilation of Razor files. Ao criar um projeto, o Razor SDK gera um obj/<build_configuration>/<target_framework_moniker>/ Razor Directory na raiz do projeto.When building a project, the Razor SDK generates an obj/<build_configuration>/<target_framework_moniker>/Razor directory in the project root. A estrutura de diretório no Razor diretório espelha a estrutura de diretório do projeto.The directory structure within the Razor directory mirrors the project's directory structure.

Considere a seguinte estrutura de diretório em um projeto de páginas ASP.NET Core 2,1 Razor direcionado ao .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

A criação do projeto na configuração de Depuração produz o seguinte diretório 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

Para exibir a classe gerada para pages/index. cshtml, abra obj/Debug/netcoreapp 2.1/ Razor /pages/index.g.cshtml.cs.To view the generated class for Pages/Index.cshtml, open obj/Debug/netcoreapp2.1/Razor/Pages/Index.g.cshtml.cs.

Adicione a seguinte classe ao projeto do ASP.NET Core MVC: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

Em Startup.ConfigureServices, substitua o RazorTemplateEngine adicionado pelo MVC pela classe CustomTemplateEngine:In Startup.ConfigureServices, override the RazorTemplateEngine added by MVC with the CustomTemplateEngine class:

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

Defina o ponto de interrupção CustomTemplateEngine na instrução return csharpDocument;.Set a breakpoint on the return csharpDocument; statement of CustomTemplateEngine. Quando a execução do programa for interrompida no ponto de interrupção, veja o valor de generatedCode.When program execution stops at the breakpoint, view the value of generatedCode.

Exibição do Visualizador de Texto de generatedCode

Pesquisas de exibição e diferenciação de maiúsculas e minúsculasView lookups and case sensitivity

O Razor mecanismo de exibição executa pesquisas que diferenciam maiúsculas de minúsculas para exibições.The Razor view engine performs case-sensitive lookups for views. No entanto, a pesquisa real é determinada pelo sistema de arquivos subjacente:However, the actual lookup is determined by the underlying file system:

  • Origem baseada em arquivo:File based source:
    • Em sistemas operacionais com sistemas de arquivos que não diferenciam maiúsculas e minúsculas (por exemplo, Windows), pesquisas no provedor de arquivos físico não diferenciam maiúsculas de minúsculas.On operating systems with case insensitive file systems (for example, Windows), physical file provider lookups are case insensitive. Por exemplo, return View("Test") resulta em correspondências para /Views/Home/Test.cshtml, /Views/home/test.cshtml e qualquer outra variação de maiúsculas e minúsculas.For example, return View("Test") results in matches for /Views/Home/Test.cshtml, /Views/home/test.cshtml, and any other casing variant.
    • Em sistemas de arquivos que diferenciam maiúsculas de minúsculas (por exemplo, Linux, OSX e com EmbeddedFileProvider), as pesquisas diferenciam maiúsculas de minúsculas.On case-sensitive file systems (for example, Linux, OSX, and with EmbeddedFileProvider), lookups are case-sensitive. Por exemplo, return View("Test") corresponde especificamente a /Views/Home/Test.cshtml.For example, return View("Test") specifically matches /Views/Home/Test.cshtml.
  • Exibições pré-compiladas: com o ASP.NET Core 2.0 e posteriores, pesquisar em exibições pré-compiladas não diferencia maiúsculas de minúsculas em nenhum sistema operacional.Precompiled views: With ASP.NET Core 2.0 and later, looking up precompiled views is case insensitive on all operating systems. O comportamento é idêntico ao comportamento do provedor de arquivos físico no Windows.The behavior is identical to physical file provider's behavior on Windows. Se duas exibições pré-compiladas diferirem apenas quanto ao padrão de maiúsculas e minúsculas, o resultado da pesquisa não será determinístico.If two precompiled views differ only in case, the result of lookup is non-deterministic.

Os desenvolvedores são incentivados a fazer a correspondência entre as maiúsculas e minúsculas dos nomes dos arquivos e de diretórios com o uso de maiúsculas e minúsculas em:Developers are encouraged to match the casing of file and directory names to the casing of:

  • Nomes de área, controlador e ação.Area, controller, and action names.
  • Razor Pages.Razor Pages.

Fazer essa correspondência garante que as implantações encontrem suas exibições, independentemente do sistema de arquivos subjacente.Matching case ensures the deployments find their views regardless of the underlying file system.

Recursos adicionaisAdditional resources

Introdução à programação da Web do ASP.NET usando o Razor A sintaxe fornece muitos exemplos de programação com Razor sintaxe.Introduction to ASP.NET Web Programming Using the Razor Syntax provides many samples of programming with Razor syntax.