Auxiliares de Marcadores no ASP.NET Core

Por Rick Anderson

O que são Tag Helpers (auxiliares de tag)

Os Auxiliares de Tag permitem que o código do lado do servidor participe da criação e da renderização de elementos HTML em arquivos Razor. Por exemplo, o recurso integrado ImageTagHelper pode acrescentar um número de versão ao nome da imagem. Sempre que a imagem é alterada, o servidor gera uma nova versão exclusiva para a imagem, portanto, os clientes têm a garantia de obter a imagem atual (em vez de uma imagem obsoleta armazenada em cache). Há muitos Tag Helpers internos para tarefas comuns, como criar formulários, links, carregar recursos e muito mais; além disso, há ainda mais disponíveis em repositórios públicos do GitHub e como pacotes NuGet. Os Auxiliares de Marca são criados no C# e são direcionados a elementos HTML de acordo com o nome do elemento, o nome do atributo ou a marca pai. Por exemplo, o LabelTagHelper embutido pode direcionar o elemento HTML <label> quando os atributos LabelTagHelper são aplicados. Se você estiver familiarizado com HTML Helpers, os Tag Helpers reduzem as transições explícitas entre HTML e C# em Razor views. Em muitos casos, os Auxiliares HTML fornecem uma abordagem alternativa para um Auxiliar de Marca específico, mas é importante reconhecer que os Auxiliares de Marca não substituem os Auxiliares HTML. Não há um Tag Helper para cada Auxiliar HTML. A comparação entre os Auxiliares de Marca e os Auxiliares HTML explica as diferenças com mais detalhes.

Não há suporte para Tag Helpers em componentes Razor. Para obter mais informações, consulte ASP.NET Componentes principaisRazor.

O que os Auxiliares de Marca fornecem

Uma experiência de desenvolvimento amigável a HTML

Normalmente, a Razor marcação usando Tag Helpers se assemelha a HTML padrão. Designers de front-end conversantes com HTML/CSS/JavaScript podem editar Razor sem aprender a sintaxe C# Razor .

Um ambiente rico do IntelliSense para criar HTML e marcação Razor

Isso contrasta fortemente com os Auxiliares de HTML, a abordagem anterior para a criação de marcações no lado do servidor em modos de exibição do Razor. A comparação entre os Auxiliares de Marca e os Auxiliares HTML explica as diferenças com mais detalhes. O suporte do IntelliSense para Tag Helpers explica o ambiente do IntelliSense. Até mesmo os desenvolvedores experientes com a sintaxe de C# são mais produtivos usando Tag Helpers do que escrevendo marcação em C#.

Uma maneira de torná-lo mais produtivo e capaz de produzir um código mais robusto, confiável e mantenedível usando informações disponíveis apenas no servidor

Por exemplo, historicamente, o mantra sobre a atualização de imagens era mudar o nome da imagem ao modificá-la. As imagens devem ser armazenadas em cache agressivamente por motivos de desempenho e, a menos que você altere o nome de uma imagem, você corre o risco de os clientes obterem uma cópia obsoleta. Historicamente, depois que uma imagem foi editada, o nome tinha que ser alterado e cada referência à imagem no aplicativo Web precisava ser atualizada. Não só é muito trabalhoso, mas também propenso a erros (você pode perder uma referência, inserir acidentalmente a cadeia de caracteres errada, etc.). O recurso interno ImageTagHelper pode fazer isso automaticamente para você. Ele ImageTagHelper pode acrescentar um número de versão ao nome da imagem, portanto, sempre que a imagem for alterada, o servidor gerará automaticamente uma nova versão exclusiva para a imagem. Os clientes têm a garantia de obter a imagem atual. Essa robustez e economia de trabalho é obtida essencialmente sem custo através do ImageTagHelper.

A maioria dos auxiliares de marca internos é direcionada a elementos HTML padrão e fornece atributos do lado do servidor para o elemento. Por exemplo, o elemento <input> usado em muitas visões na pasta Exibições/Conta contém o atributo asp-for. Esse atributo extrai o nome da propriedade de modelo especificada para o HTML renderizado. Considere uma exibição Razor com o seguinte modelo:

public class Movie
{
    public int ID { get; set; }
    public string Title { get; set; }
    public DateTime ReleaseDate { get; set; }
    public string Genre { get; set; }
    public decimal Price { get; set; }
}

A seguinte Razor marcação:

<label asp-for="Movie.Title"></label>

Gera o seguinte HTML:

<label for="Movie_Title">Title</label>

O asp-for atributo é disponibilizado pela For propriedade no LabelTagHelper. Consulte Author Tag Helpers para obter mais informações.

Gerenciando o escopo do Auxiliar de Marca

O escopo dos Auxiliares de Marca é controlado por uma combinação de @addTagHelper, @removeTagHelper e o caractere de recusa "!".

@addTagHelper disponibiliza Tag Helpers

Se você criar um novo aplicativo Web ASP.NET Core chamado AuthoringTagHelpers, o seguinte Views/_ViewImports.cshtml arquivo será adicionado ao seu projeto:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

A diretiva @addTagHelper disponibiliza os Auxiliares de Marca para a exibição. Nesse caso, o arquivo de exibição é Pages/_ViewImports.cshtml, que por padrão é herdado por todos os arquivos na pasta Páginas e subpastas; disponibilizando Tag Helpers. O código anterior utiliza a sintaxe de curinga (“*”) para especificar que todos os Auxiliares de Marcas na montagem indicada (Microsoft.AspNetCore.Mvc.TagHelpers) estarão disponíveis para todos os arquivos de visualização no diretório Exibições ou em seus subdiretórios. O primeiro parâmetro após @addTagHelper especifica os Auxiliares de Marca a serem carregados (estamos usando "*" para todos os Auxiliares de Marca) e o segundo parâmetro "Microsoft. AspNetCore.Mvc.TagHelpers" especifica o assembly que contém os Auxiliares de Marca. Microsoft.AspNetCore.Mvc.TagHelpers é o assembly para os Tag Helpers internos do ASP.NET Core.

Para expor todos os Tag Helpers neste projeto (que cria um assembly chamado AuthoringTagHelpers), você usaria:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

Se o projeto contém um EmailTagHelper com o namespace padrão (AuthoringTagHelpers.TagHelpers.EmailTagHelper), forneça o FQN ( nome totalmente qualificado) do Auxiliar de Marca:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

Para adicionar um Auxiliar de Marca a uma exibição usando um FQN, primeiro adicione o FQN (AuthoringTagHelpers.TagHelpers.EmailTagHelper) e, em seguida, o nome do assembly (AuthoringTagHelpers). A maioria dos desenvolvedores prefere usar a sintaxe curinga "*". A sintaxe de curinga permite que você insira o caractere "*" como sufixo em um FQN. Por exemplo, qualquer uma das seguintes diretivas incorporará o EmailTagHelper:

@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers

Conforme mencionado anteriormente, adicionar a diretiva @addTagHelper ao arquivo Views/_ViewImports.cshtml disponibiliza o Tag Helper para todos os arquivos de exibição no diretório Views e subdiretórios. Você pode usar a diretiva @addTagHelper em arquivos de visualização específicos se quiser optar por expor o Tag Helper apenas para essas visualizações.

@removeTagHelper remove os Auxiliares de Marca

O @removeTagHelper tem os mesmos dois parâmetros que @addTagHelper, e remove um Tag Helper que foi adicionado anteriormente. Por exemplo, @removeTagHelper aplicado a uma exibição específica remove o Auxiliar de Marca especificado da exibição. O uso de @removeTagHelper em um arquivo Views/Folder/_ViewImports.cshtml remove o Auxiliar de Marca especificado de todas as exibições na Pasta.

Como controlando o escopo do Auxiliar de Marca com o arquivo _ViewImports.cshtml

Você pode adicionar uma _ViewImports.cshtml a qualquer pasta de exibição e o mecanismo de exibição aplica as diretivas desse arquivo e do Views/_ViewImports.cshtml arquivo. Se você adicionou um arquivo vazio Views/Home/_ViewImports.cshtml para as Home exibições, não haverá alteração porque o _ViewImports.cshtml arquivo é aditivo. Quaisquer diretivas @addTagHelper que você adicionar ao arquivo Views/Home/_ViewImports.cshtml (que não estejam no arquivo padrão Views/_ViewImports.cshtml.) farão com que esses Auxiliares de Marca fiquem disponíveis apenas para as visualizações na pasta Home.

Recusar elementos individuais

Desabilite um Auxiliar de Marca no nível do elemento com o caractere de recusa do Auxiliar de Marca ("!"). Por exemplo, a validação Email está desabilitada no <span> com o caractere de recusa do Auxiliar de Marca:

<!span asp-validation-for="Email" class="text-danger"></!span>

Você deve aplicar o caractere de recusa do Tag Helper à tag de abertura e fechamento. (O editor do Visual Studio adiciona automaticamente o caractere de recusa à marca de fechamento quando você adiciona um à marca de abertura). Depois de adicionar o caractere de recusa, o elemento e os atributos do Auxiliar de Marca deixam de ser exibidos em uma fonte diferenciada.

Usar @tagHelperPrefix para tornar explícito o uso do Tag Helper

A @tagHelperPrefix diretiva permite que você especifique uma cadeia de caracteres de prefixo de marca para habilitar o suporte ao Auxiliar de Marca e tornar explícito o uso do Auxiliar de Marca. Por exemplo, você pode adicionar a seguinte marcação ao Views/_ViewImports.cshtml arquivo:

@tagHelperPrefix th:

Na imagem de código a seguir, o prefixo Auxiliar de Marca é definido como th:, portanto, somente esses elementos que usam o prefixo th: dão suporte a Auxiliares de Marca (elementos habilitados para Auxiliar de Marca têm uma fonte distinta). Os elementos <label> e <input> têm o prefixo Tag Helper e estão com Tag Helper ativado, enquanto o elemento <span> não.

As mesmas regras de hierarquia que se aplicam @addTagHelper também se aplicam a @tagHelperPrefix.

Auxiliares de Marca com autofechamento

Muitos Tag Helpers não podem ser usados como tags auto-fecháveis. Alguns Tag Helpers foram projetados para serem tags auto-fechantes. Usar um Tag Helper que não foi projetado para se auto-fechar suprime a saída renderizada. Um Auxiliar de Marca com autofechamento resulta em uma marca com autofechamento na saída renderizada. Para obter mais informações, confira esta observação em Criando Auxiliares de Marca.

C# no atributo/declaração Auxiliares de Marca

Os Auxiliares de Marcações não permitem C# na área de declaração de atributo ou de tag do elemento. Por exemplo, o código a seguir não é válido:

<input asp-for="LastName"  
       @(Model?.LicenseId == null ? "disabled" : string.Empty) />

O código anterior pode ser escrito como:

<input asp-for="LastName" 
       disabled="@(Model?.LicenseId == null)" />

Normalmente, o @ operador insere uma representação textual de uma expressão na marcação HTML renderizada. No entanto, quando uma expressão é avaliada como lógica false, a estrutura remove o atributo. No exemplo anterior, o atributo disabled será definido como true se Model ou LicenseId for null.

Inicializadores auxiliares de tag

Embora os atributos possam ser usados para configurar instâncias individuais de auxiliares de marca, ITagHelperInitializer<TTagHelper> podem ser usados para configurar todas as instâncias auxiliares de marca de um tipo específico. Considere o seguinte exemplo de um inicializador auxiliar de marca que configura o atributo asp-append-version ou a propriedade AppendVersion para todas as instâncias de ScriptTagHelper no aplicativo:

public class AppendVersionTagHelperInitializer : ITagHelperInitializer<ScriptTagHelper>
{
    public void Initialize(ScriptTagHelper helper, ViewContext context)
    {
        helper.AppendVersion = true;
    }
}

Para usar o inicializador, configure-o registrando-o como parte da inicialização do aplicativo:

builder.Services.AddSingleton
    <ITagHelperInitializer<ScriptTagHelper>, AppendVersionTagHelperInitializer>();

Geração automática de versão do Tag Helper fora do wwwroot

Para que um Tag Helper gere uma versão para um arquivo estático fora de wwwroot, consulte Servir arquivos de vários locais

Suporte do IntelliSense para Tag Helpers

Considere escrever um elemento HTML <label> . Assim que você entra <l no editor do Visual Studio, o IntelliSense exibe elementos correspondentes:

Não só você obtém ajuda HTML, mas também o ícone (o símbolo "@" com "<>" sob ele).

O ícone identifica o elemento como sendo alvo pelos Tag Helpers. Elementos HTML puros (como o fieldset) exibem o ícone "<>".

Uma marca HTML <label> pura exibe a marca HTML (com o tema de cor padrão do Visual Studio) em uma fonte marrom, os atributos em vermelho e os valores de atributo em azul.

Depois de inserir <label, o IntelliSense lista os atributos HTML/CSS disponíveis e os atributos direcionados ao Tag Helper:

O preenchimento de declaração do IntelliSense permite que você pressione a tecla TAB para preencher a declaração com o valor selecionado:

Assim que um atributo de Tag Helper é inserido, as fontes da tag e do atributo são alteradas. Usando o padrão tema de cor "Azul" ou "Claro" do Visual Studio, o texto é roxo em negrito. Se você estiver usando o tema “Escuro”, a fonte será azul-petróleo em negrito. As imagens neste documento foram tiradas usando o tema padrão.

Você pode digitar o atalho do Visual Studio CompleteWord (Ctrl + barra de espaço é o padrão) entre aspas duplas (""), e agora você estará no C#, exatamente como se estivesse em uma classe de C#. O IntelliSense exibe todos os métodos e propriedades no modelo de página. Os métodos e as propriedades estão disponíveis porque o tipo de propriedade é ModelExpression. Na imagem a seguir, estou editando a visualização Register, de modo que RegisterViewModel fique disponível.

O IntelliSense lista as propriedades e os métodos disponíveis para o modelo na página. O ambiente avançado do IntelliSense ajuda você a selecionar a classe CSS:

Comparação entre Auxiliares de Marca e Auxiliares HTML

Auxiliares de marca são anexados a elementos HTML em modos de exibição do Razor, enquanto os Auxiliares de HTML são invocados como métodos intercalados com HTML em modos de exibição do Razor. Considere a marcação a seguir Razor , que cria um rótulo HTML com a classe CSS "caption":

@Html.Label("FirstName", "First Name:", new {@class="caption"})

O símbolo at (@) informa Razor que este é o início do código. Os próximos dois parâmetros ("FirstName" e "First Name:") são cadeias de caracteres, portanto, o IntelliSense não pode ajudar. O último argumento:

new {@class="caption"}

É um objeto anônimo usado para representar atributos. Como class é uma palavra-chave reservada em C#, você usa o @ símbolo para forçar C# a interpretar @class= como um símbolo (nome da propriedade). Para um designer de front-end (alguém familiarizado com HTML/CSS/JavaScript e outras tecnologias de cliente, mas não familiarizado com C# e Razor), a maior parte da linha é estrangeira. Toda a linha deve ser criada sem ajuda do IntelliSense.

Usando o LabelTagHelper, a mesma marcação pode ser escrita como:

<label class="caption" asp-for="FirstName"></label>

Com a versão Tag Helper, assim que você digita <l no editor do Visual Studio, o IntelliSense exibe elementos correspondentes.

O IntelliSense ajuda você a escrever a linha inteira.

A imagem de código a seguir mostra a seção de Formulário da Views/Account/Register.cshtmlRazor exibição gerada a partir do modelo MVC do ASP.NET 4.5.x incluído no Visual Studio.

O editor do Visual Studio exibe código C# com um plano de fundo cinza. Por exemplo, o AntiForgeryToken Auxiliar HTML:

@Html.AntiForgeryToken()

é exibido com um plano de fundo cinza. A maior parte da marcação na vista Registrar é C#. Compare isso à abordagem equivalente usando Tag Helpers:

A marcação é muito mais limpa e fácil de ler, editar e manter do que a abordagem de Auxiliares HTML. O código C# é reduzido ao mínimo que o servidor precisa saber. O editor do Visual Studio exibe a marcação alvo de um Tag Helper em uma fonte distinta.

Considere o grupo de email :

<div class="form-group">
    <label asp-for="Email" class="col-md-2 control-label"></label>
    <div class="col-md-10">
        <input asp-for="Email" class="form-control" />
        <span asp-validation-for="Email" class="text-danger"></span>
    </div>
</div>

Cada um dos atributos "asp-" tem um valor de "Email", mas "Email" não é uma cadeia de caracteres. Nesse contexto, "Email" é a propriedade de expressão do modelo C# para o RegisterViewModel.

O editor do Visual Studio ajuda você a escrever toda a marcação na abordagem do Auxiliar de Marca de formulário de registro, enquanto o Visual Studio não fornece nenhuma ajuda para a maioria do código na abordagem de Auxiliares HTML. Suporte do IntelliSense para Auxiliares de Marca explica em detalhes como trabalhar com Auxiliares de Marca no editor do Visual Studio.

Comparação entre Auxiliares de Marca e Controles de Servidor Web

• Os Auxiliares de Marca não são proprietários do elemento ao qual estão associados; eles participam da renderização do elemento e do conteúdo. ASP.NET controles de servidor da Web são declarados e invocados em uma página.

• Controles de Servidor Web do ASP.NET têm um ciclo de vida não trivial que pode dificultar o desenvolvimento e a depuração.

• Os controles do Servidor Web permitem adicionar funcionalidade aos elementos DOM cliente usando um controle de cliente. Os Tag Helpers não têm DOM.

• Os controles do Servidor Web incluem a detecção automática do navegador. Os Auxiliares de Marca não têm conhecimento do navegador.

• Vários Tag Helpers podem atuar no mesmo elemento (consulte Evitando conflitos de Tag Helpers), enquanto geralmente não é possível compor controles de Servidor Web.

• Os Auxiliares de Tag podem modificar a tag e o conteúdo dos elementos HTML aos quais estão associados, mas não modificam diretamente nada em uma página. Os controles do Servidor Web têm um escopo menos específico e podem executar ações que afetam outras partes da sua página; habilitando efeitos colaterais não intencionais.

• Os controles do Servidor Web usam conversores de tipo para converter cadeias de caracteres em objetos. Com os Tag Helpers, você trabalha de forma nativa em C#, então não precisa se preocupar com conversão de tipos.

• Os controles do Servidor Web usam System.ComponentModel para implementar o comportamento de tempo de execução e tempo de design de componentes e controles. System.ComponentModel inclui as classes base e interfaces para implementar atributos e conversores de tipo, associação a fontes de dados e componentes de licenciamento. Compare isso com os Auxiliares de Marca, que normalmente são derivados de TagHelper, e a classe base TagHelper expõe apenas dois métodos, Process e ProcessAsync.

Personalizando a fonte do elemento Tag Helper

Você pode personalizar a fonte e a colorização em Ferramentas>Opções>Ambiente>Fontes e Cores:

Auxiliares de marcação internos do ASP.NET Core

Âncora

Cache

Componente

Cache Distribuído

Ambiente

Formulário

Ação de formulário

Image

Entrada

Rótulo

Link

Parcial

Manter o estado do componente

Script

Selecionar

Textarea

Mensagem de validação

Resumo da validação

Recursos adicionais

• Auxiliares de Tag de Autor
• Trabalhar com formulários
• TagHelperSamples no GitHub inclui exemplos de Tag Helper para uso com o Bootstrap.