Helper tag in ASP.NET Core

Articolo
11/30/2023

Descrizione di helper tag

Gli helper tag consentono al codice lato server di partecipare alla creazione e al rendering di elementi HTML nei Razor file. Ad esempio, l'elemento predefinito ImageTagHelper può aggiungere un numero di versione al nome dell'immagine. Quando l'immagine viene modificata, il server genera una nuova versione univoca per l'immagine, in modo da garantire che i client ricevano sempre l'immagine corrente (anziché un'immagine non aggiornata memorizzata nella cache). Esistono molti helper tag predefiniti per le attività comuni, ad esempio la creazione di moduli e collegamenti, il caricamento di asset e così via, e altri ancora sono disponibili nei repository GitHub pubblici e come pacchetti NuGet. Gli helper tag vengono creati in C# e hanno come destinazione gli elementi HTML in base al nome di elemento, nome di attributo o tag padre. Ad esempio, l'elemento predefinito LabelTagHelper può avere come destinazione l'elemento HTML <label> quando vengono applicati gli attributi di LabelTagHelper. Se si ha familiarità con gli helper HTML, gli helper tag riducono le transizioni esplicite tra HTML e C# nelle Razor visualizzazioni. In molti casi, gli helper HTML offrono un approccio alternativo a un helper tag specifico, ma è importante tenere presente che gli helper tag non sostituiscono gli helper HTML e che non esiste un helper tag per ogni helper HTML. Nella sezione Helper tag e helper HTML a confronto vengono illustrate le differenze in modo più dettagliato.

Gli helper tag non sono supportati nei Razor componenti. Per altre informazioni, vedere ASP.NET Componenti di baseRazor.

Vantaggi degli helper tag

Un'esperienza di sviluppo compatibile con HTML

Nella maggior parte dei casi, Razor il markup con gli helper tag è simile al codice HTML standard. I progettisti front-end conversano con HTML/CSS/JavaScript possono modificare Razor senza imparare la sintassi C# Razor .

Ambiente IntelliSense avanzato per la creazione di html e Razor markup

Questo è in contrasto con gli helper HTML, l'approccio precedente alla creazione lato server del markup nelle Razor visualizzazioni. Nella sezione Helper tag e helper HTML a confronto vengono illustrate le differenze in modo più dettagliato. Nella sezione Supporto IntelliSense per gli helper tag viene illustrato l'ambiente IntelliSense. Anche gli sviluppatori esperti con Razor la sintassi C# sono più produttivi usando gli helper tag rispetto alla scrittura di markup C# Razor .

Un modo per rendere più produttivo e in grado di produrre codice più affidabile, affidabile e gestibile usando solo le informazioni disponibili nel server

Ad esempio, storicamente il motto sull'aggiornamento delle immagini era quello di modificare il nome dell'immagine quando si modifica l'immagine. Per motivi di prestazioni, le immagini devono essere memorizzate nella cache e, a meno che il nome dell'immagine non venga cambiato, si rischia che i client ricevano una copia non aggiornata. Dopo che un'immagine era stata modificata, il nome doveva essere sempre cambiato e ogni riferimento all'immagine nell'app Web doveva essere aggiornato. Non solo è molto intensivo, è anche soggetto a errori (si potrebbe perdere un riferimento, immettere accidentalmente la stringa errata e così via). Questa operazione può essere eseguita automaticamente dall'utente ImageTagHelper . ImageTagHelper è in grado di aggiungere un numero di versione al nome dell'immagine in modo che quando l'immagine viene modificata il server generi automaticamente una nuova versione univoca dell'immagine. I client riceveranno sicuramente l'immagine corrente. Grazie all'uso di ImageTagHelper, efficienza e risparmio di energie sono essenzialmente gratuiti.

La maggior parte degli helper tag predefiniti usano come destinazione elementi HTML standard e specificano attributi sul lato server per l'elemento. Ad esempio, l'elemento <input> usato in molte visualizzazioni nella cartella Views/Account (Visualizzazioni/Account) contiene l'attributo asp-for. Questo attributo consente di estrarre il nome della proprietà del modello specificato nel codice HTML visualizzabile. Si consideri una Razor visualizzazione con il modello seguente:

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

Il markup seguente Razor :

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

Viene generato il codice HTML seguente:

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

L'attributo asp-for viene reso disponibile dalla proprietà For in LabelTagHelper. Per altre informazioni, vedere Creare helper tag.

Gestione dell'ambito dell'helper tag

L'ambito degli helper tag è controllato da una combinazione di @addTagHelper, @removeTagHelper e del carattere di esclusione "!".

`@addTagHelper` rende disponibili gli helper tag

Se si crea una nuova app Web ASP.NET Core denominata AuthoringTagHelpers, il file seguente Views/_ViewImports.cshtml verrà aggiunto al progetto:

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

La direttiva @addTagHelper rende gli helper tag disponibili per la visualizzazione. In questo caso, il file di visualizzazione è Pages/_ViewImports.cshtml, che per impostazione predefinita viene ereditato da tutti i file nella cartella Pages e nelle sottocartelle, rendendo disponibili gli helper tag. Il codice precedente usa la sintassi con caratteri jolly ("*") per specificare che tutti gli helper tag nell'assembly specificato (Microsoft.AspNetCore.Mvc.TagHelpers) saranno disponibili per ogni file di visualizzazione nella directory Views o nella sottodirectory. Il primo parametro dopo @addTagHelper specifica gli helper tag da caricare (si usa "*" per tutti gli helper tag) e il secondo parametro "Microsoft.AspNetCore.Mvc.TagHelpers" specifica l'assembly contenente gli helper tag. Microsoft.AspNetCore.Mvc.TagHelpers è l'assembly per gli helper tag predefiniti di ASP.NET Core.

Per esporre tutti gli helper tag di questo progetto, che crea un assembly denominato AuthoringTagHelpers, usare il codice seguente:

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

Se il progetto contiene un EmailTagHelper con lo spazio dei nomi predefinito (AuthoringTagHelpers.TagHelpers.EmailTagHelper), è possibile fornire il nome completo dell'helper tag:

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

Per aggiungere un helper tag a una visualizzazione usando un nome completo, aggiungere prima il nome completo (AuthoringTagHelpers.TagHelpers.EmailTagHelper) e quindi il nome dell'assembly (AuthoringTagHelpers). La maggior parte degli sviluppatori preferisce usare la sintassi con caratteri jolly "*". La sintassi con caratteri jolly consente di inserire il carattere jolly "*" come suffisso in un FQN. Le direttive seguenti, ad esempio, aggiungeranno EmailTagHelper:

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

Come accennato in precedenza, l'aggiunta della @addTagHelper direttiva al Views/_ViewImports.cshtml file rende disponibile l'helper tag per tutti i file di visualizzazione nella directory Views e nelle sottodirectory. È possibile usare la direttiva @addTagHelper in file di visualizzazione specifici se si vuole acconsentire esplicitamente a esporre l'helper tag solo a queste visualizzazioni.

`@removeTagHelper` rimuove gli helper tag

@removeTagHelper contiene gli stessi due parametri di @addTagHelper e rimuove un helper tag che era stato precedentemente aggiunto. Se ad esempio si applica @removeTagHelper a una visualizzazione specifica, l'helper tag specificato viene rimosso dalla visualizzazione. Se si usa @removeTagHelper in un Views/Folder/_ViewImports.cshtml file, l'helper tag specificato viene rimosso da tutte le visualizzazioni in Cartella.

Controllo dell'ambito dell'helper tag con il `_ViewImports.cshtml` file

È possibile aggiungere un oggetto _ViewImports.cshtml a qualsiasi cartella di visualizzazione e il motore di visualizzazione applica le direttive del file e del Views/_ViewImports.cshtml file. Se è stato aggiunto un file vuoto Views/Home/_ViewImports.cshtml per le Home visualizzazioni, non verrà apportata alcuna modifica perché il _ViewImports.cshtml file è additive. Tutte le @addTagHelper direttive aggiunte al Views/Home/_ViewImports.cshtml file (che non si trovano nel file predefinito Views/_ViewImports.cshtml ) espongono tali helper tag alle visualizzazioni solo nella Home cartella.

Esclusione di singoli elementi

È possibile disabilitare un helper tag a livello di elemento con il carattere di esclusione ("!") dell'helper tag. La convalida Email viene ad esempio disabilitata in <span> con il carattere di esclusione dell'helper tag:

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

È necessario applicare il carattere di esclusione dell'helper tag ai tag di apertura e chiusura. L'editor di Visual Studio aggiunge automaticamente il carattere di esclusione al tag di chiusura se ne è stato aggiunto uno al tag di apertura. Dopo che il carattere di esclusione è stato aggiunto, l'elemento e gli attributi dell'helper tag non verranno più visualizzati in un tipo di carattere distintivo.

Uso di `@tagHelperPrefix` per rendere esplicito l'uso dell'helper tag

La direttiva @tagHelperPrefix consente di specificare una stringa di prefisso del tag per abilitare il supporto dell'helper tag e renderne esplicito l'uso. Ad esempio, è possibile aggiungere il markup seguente al Views/_ViewImports.cshtml file:

@tagHelperPrefix th:

Nell'immagine di codice seguente, il prefisso dell'helper tag è impostato su th:. Pertanto, solo gli elementi che usano il prefisso th: supportano gli helper tag. Gli elementi abilitati per gli helper tag hanno un tipo di carattere distintivo. Gli elementi <label> e <input> includono il prefisso dell'helper tag e sono abilitati per gli helper tag, mentre l'elemento <span> non lo è.

Razor markup with Tag Helper prefix set to

Le stesse regole di gerarchia che si applicano a @addTagHelper sono valide anche per @tagHelperPrefix.

Helper tag di chiusura automatico

Molti helper tag non possono essere usati come tag di chiusura automatici. Alcuni helper tag sono progettati per essere tag di chiusura automatici. Se si usa un helper tag non progettato per la chiusura automatica, l'output sottoposto a rendering viene eliminato. La chiusura automatica di un helper tag genera un tag di chiusura automatico nell'output sottoposto a rendering. Per altre informazioni, vedere questa nota in Creare helper tag in ASP.NET Core.

C# nell'attributo/dichiarazione degli helper tag

Gli helper tag non consentono C# nell'area di dichiarazione dell'attributo o del tag dell'elemento. Ad esempio, il codice seguente non è valido:

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

Il codice precedente può essere scritto come segue:

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

In genere, l'operatore @ inserisce una rappresentazione testuale di un'espressione nel markup HTML sottoposto a rendering. Tuttavia, quando un'espressione restituisce logico false, il framework rimuove invece l'attributo . Nell'esempio precedente l'attributo disabled è impostato su true se Model o LicenseId è null.

Inizializzatori helper tag

Sebbene gli attributi possano essere usati per configurare singole istanze degli helper tag, ITagHelperInitializer<TTagHelper> è possibile usare per configurare tutte le istanze helper tag di un tipo specifico. Si consideri l'esempio seguente di un inizializzatore helper tag che configura l'attributo o AppendVersion la asp-append-version proprietà per tutte le istanze di ScriptTagHelper nell'app:

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

Per usare l'inizializzatore, configurarlo registrandolo come parte dell'avvio dell'applicazione:

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

Generazione automatica della versione helper tag all'esterno di wwwroot

Per un helper tag per generare una versione per un file statico all'esterno wwwrootdi , vedere Gestire i file da più posizioni

Supporto IntelliSense per gli helper tag

Si supponga di scrivere un elemento <label> HTML. Non appena si inizia a digitare <l nell'editor di Visual Studio, IntelliSense visualizza gli elementi corrispondenti:

After typing

Non solo si ottiene la Guida HTML, ma anche l'icona (il simbolo "@" con "<>" sotto di esso).

The

L'icona identifica l'elemento come destinazione dagli helper tag. Gli elementi HTML puri (ad esempio ) fieldsetvisualizzano l'icona "<>".

Un tag <label> HTML puro visualizza il tag HTML (con il tema colori di Visual Studio predefinito) con un tipo di carattere marrone, gli attributi in rosso e i valori degli attributi in blu.

Example

Dopo avere immesso <label, IntelliSense elenca gli attributi HTML/CSS disponibili e gli attributi di destinazione dell'helper tag:

The user has typed an opening bracket and the HTML element name

Il completamento istruzioni di IntelliSense consente di usare il tasto TAB per completare l'istruzione con il valore selezionato:

The user has typed an opening bracket, the HTML element name

Non appena un attributo dell'helper tag viene immesso, i tipi di carattere del tag e dell'attributo cambiano. Con il tema colori predefinito "Blu" o "Chiaro" di Visual Studio, il tipo di carattere è in grassetto viola. Se si usa il tema colori "Scuro", il tipo di carattere è in grassetto verde acqua. Nelle immagini acquisite per questo documento è stato usato il tema predefinito.

The user selected

È possibile immettere il tasto di scelta rapida CompleteWord di Visual Studio (CTRL+barra spaziatrice è l'impostazione predefinita) all'interno delle virgolette doppie ("") e si è ora in C#, proprio come si farebbe in una classe C#. IntelliSense visualizza tutti i metodi e le proprietà nel modello di pagina. I metodi e le proprietà sono disponibili perché il tipo di proprietà è ModelExpression. Nell'immagine seguente viene modificata la visualizzazione Register, quindi è disponibile il modello RegisterViewModel.

The user types

IntelliSense elenca le proprietà e i metodi disponibili per il modello nella pagina. L'ambiente avanzato di IntelliSense consente di selezionare la classe CSS:

The user types

Helper tag e helper HTML a confronto

Gli helper tag si collegano agli elementi HTML nelle Razor visualizzazioni, mentre gli helper HTML vengono richiamati come metodi interspersi con HTML nelle Razor visualizzazioni. Si consideri il markup seguenteRazor, che crea un'etichetta HTML con la classe CSS "didascalia":

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

Il simbolo at (@) indica Razor che questo è l'inizio del codice. I due parametri successivi ("FirstName" e "First Name:") sono stringhe, quindi IntelliSense non risulta utile. L'ultimo argomento:

new {@class="caption"}

è un oggetto anonimo usato per rappresentare gli attributi. Poiché class è una parola chiave riservata in C#, usare il simbolo @ per imporre a C# di interpretare @class= come un simbolo (nome di proprietà). Per una finestra di progettazione front-end (qualcuno che ha familiarità con HTML/CSS/JavaScript e altre tecnologie client ma non ha familiarità con C# e Razor), la maggior parte della riga è esterna. L'intera riga deve essere creata senza alcun aiuto da parte di IntelliSense.

Usando LabelTagHelper, è possibile scrivere lo stesso markup nel modo seguente:

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

Con la versione helper tag, non appena si digita <l nell'editor di Visual Studio, IntelliSense visualizza gli elementi corrispondenti:

The user types

IntelliSense aiuta a scrivere l'intera riga.

L'immagine di codice seguente mostra la parte Modulo della Views/Account/Register.cshtmlRazor visualizzazione generata dal modello MVC 4.5.x ASP.NET incluso in Visual Studio.

Razor markup for the form portion of the Register Razor view for ASP.NET 4.5 MVC project template

Nell'editor di Visual Studio il codice C# viene visualizzato con uno sfondo grigio. Ad esempio, l'helper HTML AntiForgeryToken:

@Html.AntiForgeryToken()

viene visualizzato con uno sfondo grigio. La maggior parte del markup nella visualizzazione Register è C#. Confrontarlo con l'approccio equivalente usando gli helper tag:

Razor markup with Tag Helpers for the form portion of the Register Razor view for an ASP.NET Core project template

Rispetto all'approccio con gli helper HTML, il markup è molto più chiaro e facile da leggere, modificare e gestire. Il codice C# è ridotto al numero minimo di elementi che il server deve conoscere. Nell'editor di Visual Studio il markup di destinazione di un helper tag viene visualizzato in un tipo di carattere distintivo.

Si osservi il gruppo 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>

Ogni attributo "asp-" ha il valore "Email", ma "Email" non è una stringa. In questo contesto "Email" è la proprietà di espressione del modello C# per RegisterViewModel.

L'editor di Visual Studio agevola la scrittura di tutto il markup nell'approccio con l'helper tag del modulo di registrazione, mentre Visual Studio non offre alcun aiuto per la maggior parte del codice nell'approccio con gli helper HTML. Nella sezione Supporto IntelliSense per gli helper tag viene illustrato in modo dettagliato l'uso degli helper tag nell'editor di Visual Studio.

Helper tag e controlli server Web a confronto

Gli helper tag non sono i proprietari dell'elemento a cui sono associati, ma partecipano semplicemente al rendering dell'elemento e del contenuto. ASP.NET i controlli server Web vengono dichiarati e richiamati in una pagina.
ASP.NET i controlli server Web hanno un ciclo di vita non semplice che può rendere difficile lo sviluppo e il debug.
I controlli server Web consentono di aggiungere funzionalità agli elementi DOM client usando un controllo client. Gli helper tag non includono DOM.
I controlli server Web includono il rilevamento automatico del browser. Gli helper tag non hanno conoscenza del browser.
Più helper tag possono agire sullo stesso elemento (vedere evitare conflitti di helper tag) mentre in genere non è possibile comporre controlli server Web.
Gli helper tag possono modificare il tag e il contenuto degli elementi HTML che rientrano nel proprio ambito, ma non modificano altro in modo diretto in una pagina. I controlli server Web hanno un ambito meno specifico e possono eseguire azioni che influiscono su altre parti della pagina, provocando effetti collaterali imprevisti.
I controlli server Web usano i convertitori di tipi per convertire le stringhe in oggetti. Gli helper tag consentono di lavorare in modo nativo in C#, quindi la conversione dei tipi non è necessaria.
I controlli server Web usano System.ComponentModel per implementare il comportamento in fase di esecuzione e progettazione di componenti e controlli. System.ComponentModel include le classi e le interfacce di base per l'implementazione di attributi e convertitori, l'associazione a origini dati e le licenze per i componenti. Gli helper tag invece derivano in genere da TagHelper e la classe di base TagHelper espone solo due metodi, Process e ProcessAsync.