Referência da sintaxe Razor para ASP.NET CoreRazor syntax reference for ASP.NET Core

Por Rick Anderson, Luke Latham, Taylor Mullen e Dan VicarelBy Rick Anderson, Luke Latham, 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 sintaxe Razor é composta pela marcação Razor, por C# e por HTML.The Razor syntax consists of Razor markup, C#, and HTML. Arquivos que contêm Razor geralmente têm a extensão de arquivo .cshtml.Files containing Razor generally have a .cshtml file extension. O Razor também é encontrado em arquivos de Componentes do Razor ( .razor).Razor is also found in Razor components files (.razor).

Renderizando HTMLRendering HTML

A linguagem padrão do Razor padrão é o HTML.The default Razor language is HTML. Renderizar HTML da marcação Razor não é diferente de renderizar 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 Razor .cshtml é renderizada pelo servidor inalterado.HTML markup in .cshtml Razor files is rendered by the server unchanged.

Sintaxe RazorRazor syntax

O 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#. O Razor avalia expressões em 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 palavra-chave reservada do Razor, ele faz a transição para marcação específica do Razor.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 fazer o escape de um símbolo @ na marcação Razor, 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 não são alterados pela análise do Razor:The email addresses in the following example are untouched by Razor parsing:

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

Expressões Razor implícitasImplicit Razor expressions

Expressões Razor implícitas são iniciadas por @ seguido do 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 expressão Razor explícita ou em um bloco de código Razor.Generic method calls must be wrapped in an explicit Razor expression or a Razor code block.

Expressões Razor explícitasExplicit Razor expressions

Expressões Razor explícitas consistem de um símbolo @ com parênteses equilibradas.Explicit Razor expressions consist of an @ symbol with balanced parenthesis. Para renderizar a hora da última semana, a seguinte marcação Razor é 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 renderiza o HTML a seguir:The code renders the following HTML:

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

O HTML é mostrado no navegador como:The HTML is shown in the browser as:

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

Blocos de código RazorRazor code blocks

Blocos de código Razor são iniciados por @ e delimitados 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

A linguagem padrão em um bloco de código é C#, mas a página Razor pode fazer a transição de volta para 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, circunde os caracteres para renderização com a marca de 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>
}

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 uma marca HTML ou Razor, ocorrerá um erro de tempo de execução do Razor.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ícita com @:Explicit line transition with @:

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 the @: syntax:

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

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

Caracteres @ extras em um arquivo Razor podem causar erros do compilador em instruções mais adiante 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 e @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;
}

Looping @for, @foreach, @while e @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);

Composto @usingCompound @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 tê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@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@lock

O Razor tem a capacidade de proteger seções críticas com instruções de bloqueio:Razor has the capability to protect critical sections with lock statements:

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

ComentáriosComments

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

Comentários em Razor 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. O 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

Diretivas de Razor 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.

Compreender 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>");
    }
}

Mais adiante neste artigo, a seção Inspecionar a classe do Razor 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@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@code

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

O bloco @code permite que um componente de Razor adicione membros (campos, propriedades e métodos) de C# 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 componentes de Razor, @code é um alias de @functions e é recomendado seu uso com @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@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 Componentes de Razor, use @code com @functions para adicionar membros de 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 classe C# do Razor 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@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@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 tipo de página Razor personalizado: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@inject

A diretiva @inject permite que a página do Razor injete 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@layout

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

A diretiva @layout especifica um layout para um componente de Razor.The @layout directive specifies a layout for a Razor component. 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 ASP.NET Core layouts mais incrivelmente.For more information, see ASP.NET Core layouts mais incrivelmente.

@model@model

Este cenário aplica-se somente a exibições do MVC e do Razor Pages (.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 aplicativo de MVC ou Razor Pages do ASP.NET Core criado com contas de usuário individuais, Views/Account/Login.cshtml contém a declaração de modelo a seguir: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>

O Razor expõe uma propriedade Model 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 palavra-chave @model.For more information, see Strongly typed models and the @model keyword.

@namespace@namespace

A diretiva @namespace:The @namespace directive:

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

Para o exemplo de Razor Pages 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
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

As relações anteriores se aplicam a arquivos de importação usados com exibições de MVC e componentes de 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
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

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 diretiva @page na primeira linha de um arquivo .cshtml indica que o arquivo é uma página do Razor.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 a Páginas do Razor no ASP.NET Core.For more information, see Introdução a Páginas do Razor no ASP.NET Core.

@section@section

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

A diretiva @section é usada em conjunto com layouts de MVC e Razor Pages para permitir que as exibições ou páginas renderizem conteúdo em partes diferentes 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@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>

Nos componentes de Razor, @using também controla quais componentes estão em um escopo.In Razor components, @using also controls which components are in scope.

Atributos de diretivaDirective attributes

@attributes@attributes

Este cenário aplica-se somente a componentes do Razor (.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 ASP.NET Core componentes do Razor.For more information, see Criar e usar ASP.NET Core componentes do Razor.

@bind@bind

Este cenário aplica-se somente a componentes do Razor (.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 Criar e usar ASP.NET Core componentes do Razor.For more information, see Criar e usar ASP.NET Core componentes do Razor.

@on{event}@on{event}

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

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

@key@key

Este cenário aplica-se somente a componentes do Razor (.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 ASP.NET Core componentes do Razor.For more information, see Criar e usar ASP.NET Core componentes do Razor.

@ref@ref

Este cenário aplica-se somente a componentes do Razor (.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 ASP.NET Core componentes do Razor.For more information, see Criar e usar ASP.NET Core componentes do Razor.

Representantes do Razor com modeloTemplated Razor delegates

Os modelos Razor permitem que você defina um snippet da 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 do Razor com modelo 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 Razor embutido 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 método Repeat recebe um modelo Razor.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 aplica-se somente a exibições do MVC e do Razor Pages (.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.

Palavras-chave reservadas ao RazorRazor reserved keywords

Palavras-chave do RazorRazor keywords

  • page (exige o ASP.NET Core 2.1 ou posterior)page (Requires ASP.NET Core 2.1 or later)
  • namespacenamespace
  • funçõesfunctions
  • herdainherits
  • modelomodel
  • sectionsection
  • helper (atualmente sem suporte do ASP.NET Core)helper (Not currently supported by ASP.NET Core)

Palavras-chave do Razor têm o escape feito com @(Razor Keyword) (por exemplo, @(functions)).Razor keywords are escaped with @(Razor Keyword) (for example, @(functions)).

Palavras-chave do Razor em C#C# Razor keywords

  • casecase
  • dodo
  • defaultdefault
  • forfor
  • foreachforeach
  • ifif
  • elseelse
  • bloqueiolock
  • switchswitch
  • trytry
  • catchcatch
  • finallyfinally
  • usingusing
  • whilewhile

Palavras-chave do Razor em C# precisam ter o 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 @ faz o escape do analisador Razor.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 pelo RazorReserved keywords not used by Razor

  • classeclass

Inspecionar a classe do Razor 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 SDK do Razor lida com a compilação de arquivos do Razor.With .NET Core SDK 2.1 or later, the Razor SDK handles compilation of Razor files. Ao compilar um projeto, o SDK do Razor gera um diretório obj/<configuração_de_build>/<moniker_da_estrutura_de_destino>/Razor 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órios dentro do diretório do Razor espelha a estrutura de diretórios do projeto.The directory structure within the Razor directory mirrors the project's directory structure.

Considere a seguinte estrutura de diretórios em um projeto do Razor Pages ASP.NET Core 2.1 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/Areas/
    • Admin/Admin/
      • Pages/Pages/
        • Index.cshtmlIndex.cshtml
        • Index.cshtml.csIndex.cshtml.cs
  • Pages/Pages/
    • Shared/Shared/
      • _Layout.cshtml_Layout.cshtml
    • _ViewImports.cshtml_ViewImports.cshtml
    • _ViewStart.cshtml_ViewStart.cshtml
    • Index.cshtmlIndex.cshtml
    • Index.cshtml.csIndex.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/obj/
    • Debug/Debug/
      • netcoreapp2.1/netcoreapp2.1/
        • Razor/Razor/
          • Areas/Areas/
            • Admin/Admin/
              • Pages/Pages/
                • Index.g.cshtml.csIndex.g.cshtml.cs
          • Pages/Pages/
            • Shared/Shared/
              • _Layout.g.cshtml.cs_Layout.g.cshtml.cs
            • _ViewImports.g.cshtml.cs_ViewImports.g.cshtml.cs
            • _ViewStart.g.cshtml.cs_ViewStart.g.cshtml.cs
            • Index.g.cshtml.csIndex.g.cshtml.cs

Para exibir a classe gerada para Pages/Index.cshtml, abra obj/Debug/netcoreapp2.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:

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

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 void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddSingleton<RazorTemplateEngine, CustomTemplateEngine>();
}

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 mecanismo de exibição do Razor executa pesquisas que diferenciam maiúsculas de minúsculas para as 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.
  • Páginas do Razor.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.