Helper tag di ancoraggio in ASP.NET Core

  • Articolo

Di Peter Kellner e Scott Addie

L'helper tag di ancoraggio migliora il tag di ancoraggio HTML standard (<a ... ></a>) con l'aggiunta di nuovi attributi. Per convenzione, i nomi di attributo hanno il prefisso asp-. Il valore dell'attributo href dell'elemento di ancoraggio visualizzato dipende dai valori degli attributi asp-.

Per una panoramica degli helper tag, vedere Helper tag in ASP.NET Core.

Visualizzare o scaricare il codice di esempio (procedura per il download)

SpeakerController viene usato negli esempi in tutto il documento:

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;

public class SpeakerController : Controller
{
    private List<Speaker> Speakers =
        new List<Speaker>
        {
            new Speaker {SpeakerId = 10},
            new Speaker {SpeakerId = 11},
            new Speaker {SpeakerId = 12}
        };

    [Route("Speaker/{id:int}")]
    public IActionResult Detail(int id) =>
        View(Speakers.FirstOrDefault(a => a.SpeakerId == id));

    [Route("/Speaker/Evaluations", 
           Name = "speakerevals")]
    public IActionResult Evaluations() => View();

    [Route("/Speaker/EvaluationsCurrent",
           Name = "speakerevalscurrent")]
    public IActionResult Evaluations(
        int speakerId,
        bool currentYear) => View();

    public IActionResult Index() => View(Speakers);
}

public class Speaker
{
    public int SpeakerId { get; set; }
}

Attributi dell'helper tag di ancoraggio

asp-controller

L'attributo asp-controller assegna il controller usato per generare l'URL. Il markup seguente elenca tutti gli altoparlanti:

<a asp-controller="Speaker"
   asp-action="Index">All Speakers</a>

Codice HTML generato:

<a href="/Speaker">All Speakers</a>

Se si specifica l'attributo asp-controller e l'attributo asp-action viene omesso, il valore asp-action predefinito è l'azione del controller associata alla visualizzazione di esecuzione corrente. Se asp-action viene omesso dal markup precedente e l'helper tag di ancoraggio viene usato nella Homevisualizzazione Indice del controller (/Home), il codice HTML generato è:

<a href="/Home">All Speakers</a>

asp-action

Il valore dell'attributo asp-action rappresenta il nome dell'azione del controller incluso nell'attributo href generato. Il markup seguente imposta il valore dell'attributo href generato sulla pagina delle valutazioni degli altoparlanti:

<a asp-controller="Speaker"
   asp-action="Evaluations">Speaker Evaluations</a>

Codice HTML generato:

<a href="/Speaker/Evaluations">Speaker Evaluations</a>

Se non viene specificato alcun attributo asp-controller viene usato il controller predefinito per chiamare la visualizzazione che esegue la visualizzazione corrente.

Se il valore dell'attributo asp-action è Index non viene accodata alcuna azione all'URL, con conseguente chiamata dell'azione Index predefinita. L'azione specificata (o usata per impostazione predefinita) deve esistere nel controller a cui si fa riferimento in asp-controller.

asp-route-{value}

L'attributo asp-route-{value} abilita un prefisso di route con caratteri jolly. Qualsiasi valore che sostituisce il segnaposto {value} viene interpretato come potenziale parametro di route. Se non viene trovata una route predefinita, il prefisso di route viene accodato come parametro di richiesta e relativo valore all'attributo href generato. In caso contrario viene sostituito nel modello di route.

Esaminare l'azione del controller seguente:

private List<Speaker> Speakers =
    new List<Speaker>
    {
        new Speaker {SpeakerId = 10},
        new Speaker {SpeakerId = 11},
        new Speaker {SpeakerId = 12}
    };

[Route("Speaker/{id:int}")]
public IActionResult Detail(int id) =>
    View(Speakers.FirstOrDefault(a => a.SpeakerId == id));

Con un modello di route predefinito definito in Startup.Configure:

app.UseMvc(routes =>
{
    // need route and attribute on controller: [Area("Blogs")]
    routes.MapRoute(name: "mvcAreaRoute",
                    template: "{area:exists}/{controller=Home}/{action=Index}");

    // default route for non-areas
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

La visualizzazione MVC usa il modello, fornito dall'azione, come segue:

@model Speaker
<!DOCTYPE html>
<html>
<body>
    <a asp-controller="Speaker"
       asp-action="Detail" 
       asp-route-id="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
</body>
</html>

È stata trovata una corrispondenza per il segnaposto {id?} della route predefinita. Codice HTML generato:

<a href="/Speaker/Detail/12">SpeakerId: 12</a>

Si supponga che il prefisso di route non faccia parte del modello di routing corrispondente, come nel caso della visualizzazione MVC seguente:

@model Speaker
<!DOCTYPE html>
<html>
<body>
    <a asp-controller="Speaker"
       asp-action="Detail"
       asp-route-speakerid="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
<body>
</html>

Il codice HTML seguente viene generato perché speakerid non è stato trovato nella route corrispondente:

<a href="/Speaker/Detail?speakerid=12">SpeakerId: 12</a>

Se asp-controller o asp-action non vengono specificati, viene eseguita la stessa elaborazione predefinita usata nell'attributo asp-route.

asp-route

L'attributo asp-route viene usato per la creazione di un URL collegato direttamente a una route denominata. Mediante gli attributi di routing è possibile assegnare un nome a una route come mostrato in SpeakerController e usarla nell'azione Evaluations corrispondente:

[Route("/Speaker/Evaluations", 
       Name = "speakerevals")]

Nel markup seguente l'attributo asp-route fa riferimento alla route denominata:

<a asp-route="speakerevals">Speaker Evaluations</a>

L'helper tag di ancoraggio genera una route direttamente per tale azione del controller usando l'URL /Speaker/Evaluations. Codice HTML generato:

<a href="/Speaker/Evaluations">Speaker Evaluations</a>

Se è specificato asp-controller o asp-action in aggiunta a asp-route, la route generata potrebbe non essere quella prevista. Per evitare un conflitto di route, è consigliabile non usare asp-route con gli attributi asp-controller o asp-action.

asp-all-route-data

L'attributo asp-all-route-data supporta la creazione di un dizionario di coppie chiave-valore. La chiave è il nome del parametro e il valore è il valore del parametro.

Nell'esempio seguente un dizionario viene inizializzato e passato a una Razor visualizzazione. In alternativa è possibile passare i dati con il modello.

@{
var parms = new Dictionary<string, string>
            {
                { "speakerId", "11" },
                { "currentYear", "true" }
            };
}

<a asp-route="speakerevalscurrent"
   asp-all-route-data="parms">Speaker Evaluations</a>

Il codice precedente genera il codice HTML seguente:

<a href="/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true">Speaker Evaluations</a>

Il dizionario asp-all-route-data viene reso flat per produrre una stringa di query corrispondente ai requisiti dell'azione Evaluations in overload:

public IActionResult Evaluations() => View();

[Route("/Speaker/EvaluationsCurrent",
       Name = "speakerevalscurrent")]
public IActionResult Evaluations(

In presenza di chiavi nel dizionario corrispondenti ai parametri di route, questi valori vengono sostituiti nella route come appropriato. Gli altri valori non corrispondenti vengono generati come parametri di richiesta.

asp-fragment

L'attributo asp-fragment definisce un frammento di URL da accodare all'URL. L'helper tag di ancoraggio aggiunge il carattere hash (#). Considerare il markup seguente:

<a asp-controller="Speaker"
   asp-action="Evaluations"
   asp-fragment="SpeakerEvaluations">Speaker Evaluations</a>

Codice HTML generato:

<a href="/Speaker/Evaluations#SpeakerEvaluations">Speaker Evaluations</a>

I tag hash sono utili per la compilazione di app sul lato client. Ad esempio possono essere usati per semplificare l'uso di contrassegni e la ricerca in JavaScript.

asp-area

L'attributo asp-area imposta il nome dell'area usato per impostare la route appropriata. Gli esempi seguenti illustrano come l'attributo asp-area determina la modifica del mapping delle route.

Utilizzo nelle Razor pagine

Razor Le aree pagine sono supportate in ASP.NET Core 2.1 o versione successiva.

Considerare la gerarchia di directory seguente:

  • {Nome progetto}
    • wwwroot
    • Aree
      • Sessioni
        • Pagine
          • _ViewStart.cshtml
          • Index.cshtml
          • Index.cshtml.cs
    • Pagine

Il markup per fare riferimento alla pagina indiceRazor dell'area Sessioni è:

<a asp-area="Sessions"
   asp-page="/Index">View Sessions</a>

Codice HTML generato:

<a href="/Sessions">View Sessions</a>

Suggerimento

Per supportare le aree in un'app Razor Pages, eseguire una delle operazioni seguenti in Startup.ConfigureServices:

Utilizzo in MVC

Considerare la gerarchia di directory seguente:

  • {Nome progetto}
    • wwwroot
    • Aree
      • Blog
        • Controller
          • HomeController.cs
        • Visualizzazioni
          • Home
            • AboutBlog.cshtml
            • Index.cshtml
          • _ViewStart.cshtml
    • Controller

Se si imposta asp-area su "Blogs", la directory Areas/Blogs viene aggiunta come prefisso alle route dei controller e delle visualizzazioni associati per questo tag di ancoraggio. Il markup per fare riferimento alla visualizzazione AboutBlog è:

<a asp-area="Blogs"
   asp-controller="Home"
   asp-action="AboutBlog">About Blog</a>

Codice HTML generato:

<a href="/Blogs/Home/AboutBlog">About Blog</a>

Suggerimento

Per supportare le aree in un'app MVC, il modello di route deve includere un riferimento all'area, se esistente. Tale modello è rappresentato dal secondo parametro della chiamata del metodo routes.MapRoute in Startup.Configure:

app.UseMvc(routes =>
{
    // need route and attribute on controller: [Area("Blogs")]
    routes.MapRoute(name: "mvcAreaRoute",
                    template: "{area:exists}/{controller=Home}/{action=Index}");

    // default route for non-areas
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

asp-protocol

L'attributo asp-protocol consente di specificare un protocollo (ad esempio https) nell'URL. Ad esempio:

<a asp-protocol="https"
   asp-controller="Home"
   asp-action="About">About</a>

Codice HTML generato:

<a href="https://localhost/Home/About">About</a>

Il nome host nell'esempio è localhost. L'helper tag di ancoraggio usa il dominio pubblico del sito Web per generare l'URL.

asp-host

L'attributo asp-host consente di specificare un nome host nell'URL. Ad esempio:

<a asp-protocol="https"
   asp-host="microsoft.com"
   asp-controller="Home"
   asp-action="About">About</a>

Codice HTML generato:

<a href="https://microsoft.com/Home/About">About</a>

asp-page

L'attributo asp-page viene usato con Razor Pages. Usarlo per impostare il valore dell'attributo href per un tag di ancoraggio su una pagina specifica. Il prefisso del nome della pagina con / crea un URL per una pagina corrispondente dalla radice dell'app:

Con il codice di esempio, il markup seguente crea un collegamento alla pagina dei partecipanti Razor :

<a asp-page="/Attendee">All Attendees</a>

Codice HTML generato:

<a href="/Attendee">All Attendees</a>

L'attributo asp-page e gli attributi asp-route, asp-controller e asp-action si escludono a vicenda. asp-page può tuttavia essere usato con asp-route-{value} per il controllo del routing, come dimostra il markup seguente:

<a asp-page="/Attendee"
   asp-route-attendeeid="10">View Attendee</a>

Codice HTML generato:

<a href="/Attendee?attendeeid=10">View Attendee</a>

Se la pagina a cui si fa riferimento non esiste, viene generato un collegamento alla pagina corrente usando un valore di ambiente dalla richiesta. Non viene indicato alcun avviso, tranne a livello di log di debug.

asp-page-handler

L'attributo asp-page-handler viene usato con Razor Pages. È progettato per il collegamento di gestori di pagine specifici.

Si consideri il gestore di pagine seguente:

public void OnGetProfile(int attendeeId)
{
    ViewData["AttendeeId"] = attendeeId;

    // code omitted for brevity
}

Il markup associato del modello di pagina si collega al gestore di pagina OnGetProfile. Si noti che il prefisso On<Verb> del nome del metodo del gestore di pagina viene omesso nel valore dell'attributo asp-page-handler. Quando il metodo è asincrono, viene omesso anche il suffisso Async.

<a asp-page="/Attendee"
   asp-page-handler="Profile"
   asp-route-attendeeid="12">Attendee Profile</a>

Codice HTML generato:

<a href="/Attendee?attendeeid=12&handler=Profile">Attendee Profile</a>

Risorse aggiuntive