Asistentes de etiquetas en ASP.NET Core

Por Rick Anderson

¿Qué son los asistentes de etiquetas?

Los asistentes de etiquetas permiten que el código del lado servidor participe en la creación y representación de elementos HTML en Razor archivos. Por ejemplo, el integrado ImageTagHelper puede anexar un número de versión al nombre de la imagen. Cada vez que cambia la imagen, el servidor genera una nueva versión única para la imagen, por lo que se garantiza que los clientes obtengan la imagen actual (en lugar de una imagen almacenada en caché obsoleta). Hay muchos asistentes de etiquetas integrados para tareas comunes, como crear formularios, vínculos, cargar recursos y mucho más, e incluso más disponibles en repositorios públicos de GitHub y como paquetes NuGet. Los asistentes de etiquetas se crean en C#, y tienen como destino elementos HTML basados en el nombre del elemento, el nombre del atributo o la etiqueta principal. Por ejemplo, el atributo incorporado LabelTagHelper puede tener como destino el elemento HTML <label> cuando se aplican los atributos LabelTagHelper. Si está familiarizado con los HTML Helpers, los Tag Helpers reducen las transiciones explícitas entre HTML y C# en las vistas Razor. En muchos casos, los asistentes HTML proporcionan un enfoque alternativo a un asistente de etiquetas específico, pero es importante reconocer que los asistentes de etiquetas no reemplazan a los asistentes HTML y no hay un asistente de etiquetas para cada asistente HTML. Los asistentes de etiquetas en comparación con los asistentes HTML explican las diferencias con más detalle.

Los asistentes de etiquetas no se admiten en Razor los componentes. Para obtener más información, consulta Componentes de ASP.NET Core Razor.

Qué proporcionan los asistentes de etiquetas

Una experiencia de desarrollo fácil de html

En su mayor parte, el marcado usando Tag Helpers Razor tiene un aspecto similar al HTML estándar. Los diseñadores front-end que conversan con HTML/CSS/JavaScript pueden editar Razor sin necesidad de aprender la sintaxis de C# Razor .

Un entorno de IntelliSense rico para crear HTML y Razor markup

Esto contrasta marcadamente con los asistentes HTML, el enfoque anterior para la creación del marcado en las vistas del lado del servidor en Razor. Los asistentes de etiquetas en comparación con los asistentes HTML explican las diferencias con más detalle. La compatibilidad de IntelliSense con asistentes de etiquetas explica el entorno de IntelliSense. Incluso los desarrolladores experimentados con la sintaxis de C# son más productivos usando Tag Helpers que escribiendo markup en C#.

Una manera de hacer que sea más productivo y capaz de generar código más sólido, confiable y fácil de mantener con información solo disponible en el servidor

Por ejemplo, históricamente el mantra sobre la actualización de las imágenes era cambiar el nombre de la imagen cuando se cambiaba la imagen. Las imágenes deben almacenarse en caché de forma agresiva por motivos de rendimiento y, a menos que cambie el nombre de una imagen, se arriesga a que los clientes obtengan una copia obsoleta. Históricamente, después de editar una imagen, el nombre tenía que cambiarse y cada referencia a la imagen de la aplicación web debía actualizarse. No solo requiere mucho trabajo, también es propenso a errores (podrías pasar por alto una referencia, escribir accidentalmente la cadena incorrecta, etc.). La función integrada ImageTagHelper puede hacerlo automáticamente. ImageTagHelper puede anexar un número de versión al nombre de la imagen, por lo que cada vez que cambia la imagen, el servidor genera automáticamente una nueva versión única para la imagen. Se garantiza que los clientes obtengan la imagen actual. Este nivel de solidez y ahorros de mano de obra se obtiene prácticamente gratis mediante el uso de ImageTagHelper.

La mayoría de los asistentes de etiquetas integradas tienen como destino elementos HTML estándar y proporcionan atributos del lado servidor para el elemento. Por ejemplo, el <input> elemento usado en muchas vistas de la carpeta Views/Account contiene el asp-for atributo . Este atributo extrae el nombre de la propiedad de modelo especificada en el HTML representado. Considere una Razor vista con el siguiente 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; }
}

El marcado siguiente Razor :

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

Se genera el siguiente código HTML:

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

El atributo asp-for está disponible mediante la propiedad For en LabelTagHelper. Consulte Author Tag Helpers (Asistentes de etiquetas de autor ) para obtener más información.

Gestión del ámbito del Tag Helper

El ámbito de asistentes de etiquetas se controla mediante una combinación de @addTagHelper, @removeTagHelper y el carácter de exclusión "!".

@addTagHelper hace que los asistentes de etiquetas estén disponibles

Si crea una nueva aplicación web de ASP.NET Core denominada AuthoringTagHelpers, se agregará el siguiente Views/_ViewImports.cshtml archivo al proyecto:

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

La @addTagHelper directiva hace que los asistentes de etiquetas estén disponibles para la vista. En este caso, el archivo de vista es Pages/_ViewImports.cshtml, que de forma predeterminada hereda todos los archivos de la carpeta Pages y las subcarpetas; haciendo que los asistentes de etiquetas estén disponibles. El código anterior usa la sintaxis comodín ("*") para especificar que todos los asistentes de etiquetas del ensamblado especificado (Microsoft.AspNetCore.Mvc.TagHelpers) estarán disponibles para todos los archivos de vista del directorio o subdirectorio views . El primer parámetro después de @addTagHelper especifica los asistentes de etiquetas que se van a cargar (usamos "*" para todos los asistentes de etiquetas), y el segundo parámetro "Microsoft.AspNetCore.Mvc.TagHelpers" especifica la biblioteca que contiene los asistentes de etiquetas. Microsoft.AspNetCore.Mvc.TagHelpers es el ensamblado de los asistentes de etiquetas principales de ASP.NET integrados.

Para exponer todos los asistentes de etiquetas de este proyecto (que crea un ensamblado denominado AuthoringTagHelpers), debe usar lo siguiente:

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

Si tu proyecto contiene un EmailTagHelper con el espacio de nombres predeterminado (AuthoringTagHelpers.TagHelpers.EmailTagHelper), puedes proporcionar el nombre completo (FQN) del Tag Helper.

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

Para agregar un asistente de etiquetas a una vista mediante un FQN, primero agregue el FQN (AuthoringTagHelpers.TagHelpers.EmailTagHelper) y, a continuación, el nombre del ensamblado (AuthoringTagHelpers). La mayoría de los desarrolladores prefieren usar la sintaxis de comodín "*". La sintaxis de caracteres comodín permite insertar el carácter comodín "*" como sufijo en un FQN. Por ejemplo, cualquiera de las siguientes directivas incluirá el EmailTagHelper:

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

Como se mencionó anteriormente, agregar la @addTagHelper directiva al Views/_ViewImports.cshtml archivo hace que el asistente de etiquetas esté disponible para todos los archivos de vista en el directorio Views y subdirectorios. Puede usar la directiva @addTagHelper en archivos de vista específicos si desea optar por exponer el helper de etiquetas solo a esas vistas.

@removeTagHelper quita asistentes de etiquetas

@removeTagHelper tiene los mismos dos parámetros que @addTagHelpery quita un asistente de etiquetas que se agregó anteriormente. Por ejemplo, @removeTagHelper aplicado a una vista específica quita el asistente de etiquetas especificado de la vista. El uso de @removeTagHelper en un archivo Views/Folder/_ViewImports.cshtml quita el Tag Helper especificado de todas las vistas de la carpeta.

Control del ámbito del Asistente de Etiquetas con el archivo _ViewImports.cshtml

Puede agregar un _ViewImports.cshtml elemento a cualquier carpeta de vista y el motor de vistas aplica las directivas tanto de ese archivo como del Views/_ViewImports.cshtml archivo. Si agregó un archivo vacío Views/Home/_ViewImports.cshtml para las Home vistas, no habría ningún cambio porque el _ViewImports.cshtml archivo es aditivo. Las directivas @addTagHelper que agregue al archivo Views/Home/_ViewImports.cshtml (que no están en el archivo predeterminado Views/_ViewImports.cshtml) expondrían esos Tag Helpers a las vistas solo en la carpeta Home.

Exclusión de los elementos individuales

Puede deshabilitar un asistente de etiquetas en el nivel de elemento con el carácter de exclusión del asistente de etiquetas ("!"). Por ejemplo, Email la validación está deshabilitada en <span> con el carácter de exclusión de Tag Helper:

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

Debe aplicar el carácter de exclusión del Tag Helper a la etiqueta de apertura y cierre. (El editor de Visual Studio agrega automáticamente el carácter de exclusión a la etiqueta de cierre al agregar uno a la etiqueta de apertura). Después de agregar el carácter de exclusión, los atributos del elemento y del asistente de etiquetas ya no se muestran en una fuente distintiva.

Uso de @tagHelperPrefix para hacer explícito el uso del asistente de etiquetas

La @tagHelperPrefix directiva permite especificar una cadena de prefijo de etiqueta para habilitar la compatibilidad con el asistente de etiquetas y hacer que el uso del asistente de etiquetas sea explícito. Por ejemplo, podría agregar el marcado siguiente al Views/_ViewImports.cshtml archivo:

@tagHelperPrefix th:

En la imagen de código siguiente, el prefijo del Tag Helper se establece en th:, por lo que solo los elementos que usan el prefijo th: admiten Tag Helpers. Los elementos habilitados para el Tag Helper tienen una fuente distintiva. Los <label> elementos y <input> tienen el prefijo del asistente de etiquetas y están habilitados para el asistente de etiquetas, mientras que el <span> elemento no lo hace.

Las mismas reglas de jerarquía que se aplican a @addTagHelper también se aplican a @tagHelperPrefix.

Asistentes de etiquetas de autocierre

Muchos Tag Helpers no pueden utilizarse como etiquetas autocerradas. Algunos ayudantes de etiquetas están diseñados para ser etiquetas auto-cerrables. El uso de un Tag Helper que no fue diseñado para cerrarse por sí mismo suprime la salida renderizada. Cerrar automáticamente un asistente de etiquetas da como resultado una etiqueta de autocierre en la salida representada. Para obtener más información, consulte esta nota en Creación de asistentes de etiquetas.

C# en atributo/declaración de Tag Helpers

Los asistentes de etiquetas no permiten C# en el área de declaración de atributos o etiquetas del elemento. Por ejemplo, el código siguiente no es válido:

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

El código anterior se puede escribir como:

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

Normalmente, el @ operador inserta una representación textual de una expresión en el marcado HTML representado. Sin embargo, cuando una expresión se evalúa como lógica false, el marco quita el atributo en su lugar. En el ejemplo anterior, el atributo disabled se establece en true si Model o LicenseId es null.

Inicializadores auxiliares de etiquetas

Aunque los atributos se pueden usar para configurar instancias individuales de asistentes de etiquetas, ITagHelperInitializer<TTagHelper> se pueden usar para configurar todas las instancias auxiliares de etiquetas de un tipo específico. Considere el siguiente ejemplo de un inicializador de ayudante de etiquetas que configura el atributo asp-append-version o la propiedad AppendVersion para todas las instancias de ScriptTagHelper en la aplicación.

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

Para usar el inicializador, configúrelo registrándolo como parte del inicio de la aplicación:

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

Generación automática de versiones del asistente de etiquetas fuera de wwwroot

Para que un asistente de etiquetas genere una versión para un archivo estático fuera wwwrootde , consulte Servir archivos desde varias ubicaciones.

Compatibilidad de IntelliSense con asistentes de etiquetas

Considere la posibilidad de escribir un elemento HTML <label> . Tan pronto como escriba <l en el editor de Visual Studio, IntelliSense muestra elementos coincidentes:

No solo se obtiene ayuda HTML, sino también el icono (el símbolo "@" con "<>" bajo él).

El icono identifica el elemento como destino de los asistentes de etiquetas. Los elementos HTML puros (como ) fieldsetmuestran el icono "<>".

Una etiqueta HTML <label> pura muestra la etiqueta HTML (con el tema de color predeterminado de Visual Studio) en una fuente marrón, los atributos en rojo y los valores de atributo en azul.

Después de escribir <label, IntelliSense enumera los atributos HTML/CSS disponibles y los atributos de destino del asistente de etiquetas:

La finalización de instrucciones de IntelliSense permite presionar la tecla de tabulación para completar la instrucción con el valor seleccionado.

Tan pronto como se escriba un atributo del asistente de etiquetas, las fuentes de etiqueta y atributo cambian. Con el tema de color "Azul" o "Claro" predeterminado de Visual Studio, la fuente es púrpura en negrita. Si usa el tema "Oscuro", la fuente está en negrita. Las imágenes de este documento se tomaron con el tema predeterminado.

Puede escribir el acceso directo CompleteWord de Visual Studio (Ctrl + barra espaciadora es el valor predeterminado) dentro de las comillas dobles ("") y estará trabajando con C#, como si estuviera trabajando en una clase de C#. IntelliSense muestra todos los métodos y propiedades del modelo de página. Los métodos y propiedades están disponibles porque el tipo de propiedad es ModelExpression. En la imagen siguiente, estoy editando la vista Register, por lo que RegisterViewModel está disponible.

IntelliSense enumera las propiedades y los métodos disponibles para el modelo en la página. El entorno de IntelliSense enriquecido le ayuda a seleccionar la clase CSS:

Asistentes de etiquetas en comparación con los asistentes HTML

Los asistentes de etiquetas se adjuntan a elementos HTML en Razor vistas, mientras que los asistentes HTML se invocan como métodos intercalados con HTML en Razor vistas. Tenga en cuenta el marcado siguiente Razor , que crea una etiqueta HTML con la clase CSS "caption":

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

El símbolo at (@) indica Razor que este es el inicio del código. Los dos parámetros siguientes ("FirstName" y "First Name:") son cadenas, por lo que IntelliSense no puede ayudar. El último argumento:

new {@class="caption"}

Es un objeto anónimo que se usa para representar atributos. Dado que class es una palabra clave reservada en C#, se usa el @ símbolo para forzar a C# a interpretar @class= como un símbolo (nombre de propiedad). Para un diseñador front-end (alguien familiarizado con HTML/CSS/JavaScript y otras tecnologías de cliente, pero que no está familiarizado con C# y Razor), la mayoría de la línea es desconocida. Toda la línea debe crearse sin ayuda de IntelliSense.

Usando LabelTagHelper, se puede escribir el mismo marcado de la siguiente manera:

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

Con la versión del asistente de etiquetas, tan pronto como escriba <l en el editor de Visual Studio, IntelliSense muestra los elementos coincidentes:

IntelliSense le ayuda a escribir toda la línea.

En la imagen de código siguiente se muestra la parte Formulario de la Views/Account/Register.cshtmlRazor vista generada a partir de la plantilla MVC de ASP.NET 4.5.x incluida con Visual Studio.

El editor de Visual Studio muestra código de C# con un fondo gris. Por ejemplo, el AntiForgeryToken asistente HTML:

@Html.AntiForgeryToken()

se muestra con un fondo gris. La mayoría del código en la vista de registro es C#. Compárelo con el enfoque equivalente mediante asistentes de etiquetas:

El marcado es mucho más limpio y fácil de leer, editar y mantener que el enfoque de los asistentes HTML. El código de C# se reduce al mínimo que el servidor necesita conocer. El editor de Visual Studio muestra el marcado destinado a un Tag Helper en una tipografía distintiva.

Considere el grupo Correo electrónico :

<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 uno de los atributos "asp-" tiene un valor de "Email", pero "Email" no es una cadena. En este contexto, "Email" es la propiedad de expresión de modelo de C# para el RegisterViewModel.

El editor de Visual Studio le ayuda a escribir todo el marcado en el enfoque del asistente de etiquetas del formulario de registro, mientras que Visual Studio no proporciona ayuda para la mayoría del código en el enfoque de asistentes HTML. La compatibilidad de IntelliSense con asistentes de etiquetas incluye detalles sobre cómo trabajar con asistentes de etiquetas en el editor de Visual Studio.

Asistentes de etiquetas en comparación con los controles de servidor web

• Los asistentes de etiquetas no poseen el elemento al que están asociados; simplemente participan en la representación del elemento y el contenido. Los controles de servidor web de ASP.NET se declaran e invocan en una página.

• Los controles de servidor web de ASP.NET tienen un ciclo de vida complejo que puede hacer difícil el desarrollo y la depuración.

• Los controles de servidor web permiten agregar funcionalidad a los elementos DOM de cliente mediante un control de cliente. Los asistentes de etiquetas no tienen DOM.

• Los controles de servidor web incluyen la detección automática del explorador. Los asistentes de etiquetas no tienen conocimiento del explorador.

• Varios asistentes de etiquetas pueden actuar en el mismo elemento (vea Evitar conflictos del asistente de etiquetas), mientras que normalmente no se pueden crear controles de servidor web.

• Los asistentes de etiquetas pueden modificar la etiqueta y el contenido de los elementos HTML a los que están asociados, pero no modifican directamente nada más en la página. Los controles de servidor web tienen un ámbito menos específico y pueden realizar acciones que afecten a otras partes de la página; habilitar efectos secundarios no deseados.

• Los controles de servidor web usan convertidores de tipos para convertir cadenas en objetos. Con Tag Helpers, trabaja de forma nativa en C#, por lo que no es necesario realizar la conversión de tipos.

• Los controles de servidor web usan System.ComponentModel para implementar el comportamiento en tiempo de ejecución y tiempo de diseño de los componentes y controles. System.ComponentModel incluye las clases e interfaces base para implementar atributos y convertidores de tipos, enlazar a orígenes de datos y componentes de licencias. Contrasta eso con los asistentes de etiquetas, que normalmente derivan de TagHelper, y la clase base TagHelper expone solo dos métodos: Process y ProcessAsync.

Personalización de la fuente del elemento auxiliar de etiquetas

Puede personalizar la fuente y la colorización desde Herramientas>Opciones>Entorno>Fuentes y Colores:

Asistentes de etiquetas principales de ASP.NET integradas

Ancla

Cache

Componente

Caché distribuida

Medio ambiente

Formulario

Acción de formulario

Imagen

Entrada

Etiqueta

Enlace

Parcial

Conservar el estado del componente

Script

Seleccionar

Textarea

Mensaje de validación

Resumen de validación

Recursos adicionales

• Creación de asistentes de etiquetas
• Trabajar con formularios
• TagHelperSamples en GitHub contiene ejemplos del asistente de etiquetas para trabajar con Bootstrap.