Helper tag di ancoraggio in ASP.NET CoreAnchor Tag Helper in ASP.NET Core

Di Peter Kellner e Scott AddieBy Peter Kellner and Scott Addie

L'helper tag di ancoraggio migliora il tag di ancoraggio HTML standard (<a ... ></a>) con l'aggiunta di nuovi attributi.The Anchor Tag Helper enhances the standard HTML anchor (<a ... ></a>) tag by adding new attributes. Per convenzione, i nomi di attributo hanno il prefisso asp-.By convention, the attribute names are prefixed with asp-. Il valore dell'attributo href dell'elemento di ancoraggio visualizzato dipende dai valori degli attributi asp-.The rendered anchor element's href attribute value is determined by the values of the asp- attributes.

Per una panoramica degli helper tag, vedere Helper tag in ASP.NET Core.For an overview of Tag Helpers, see Helper tag in ASP.NET Core.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

SpeakerController viene usato negli esempi in tutto il documento:SpeakerController is used in samples throughout this document:

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 ancoraggioAnchor Tag Helper attributes

asp-controllerasp-controller

L'attributo asp-controller assegna il controller usato per generare l'URL.The asp-controller attribute assigns the controller used for generating the URL. Il markup seguente elenca tutti gli altoparlanti:The following markup lists all speakers:

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

Codice HTML generato:The generated HTML:

<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.If the asp-controller attribute is specified and asp-action isn't, the default asp-action value is the controller action associated with the currently executing view. Se asp-action viene omesso dal markup precedente e viene usato l'helper tag di ancoraggio nella visualizzazione Index di HomeController ( /Home), il codice HTML generato è:If asp-action is omitted from the preceding markup, and the Anchor Tag Helper is used in HomeController's Index view (/Home), the generated HTML is:

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

asp-actionasp-action

Il valore dell'attributo asp-action rappresenta il nome dell'azione del controller incluso nell'attributo href generato.The asp-action attribute value represents the controller action name included in the generated href attribute. Il markup seguente imposta il valore dell'attributo href generato sulla pagina delle valutazioni degli altoparlanti:The following markup sets the generated href attribute value to the speaker evaluations page:

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

Codice HTML generato:The generated HTML:

<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.If no asp-controller attribute is specified, the default controller calling the view executing the current view is used.

Se il valore dell'attributo asp-action è Index non viene accodata alcuna azione all'URL, con conseguente chiamata dell'azione Index predefinita.If the asp-action attribute value is Index, then no action is appended to the URL, leading to the invocation of the default Index action. L'azione specificata (o usata per impostazione predefinita) deve esistere nel controller a cui si fa riferimento in asp-controller.The action specified (or defaulted), must exist in the controller referenced in asp-controller.

asp-route-{value}asp-route-{value}

L'attributo asp-route-{value} abilita un prefisso di route con caratteri jolly.The asp-route-{value} attribute enables a wildcard route prefix. Qualsiasi valore che sostituisce il segnaposto {value} viene interpretato come potenziale parametro di route.Any value occupying the {value} placeholder is interpreted as a potential route parameter. Se non viene trovata una route predefinita, il prefisso di route viene accodato come parametro di richiesta e relativo valore all'attributo href generato.If a default route isn't found, this route prefix is appended to the generated href attribute as a request parameter and value. In caso contrario viene sostituito nel modello di route.Otherwise, it's substituted in the route template.

Esaminare l'azione del controller seguente:Consider the following controller action:

public IActionResult AnchorTagHelper(int id)
{
    var speaker = new Speaker
    {
        SpeakerId = id
    };

    return View(speaker);
}

Con un modello di route predefinito definito in Startup.Configure:With a default route template defined 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:The MVC view uses the model, provided by the action, as follows:

@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.The default route's {id?} placeholder was matched. Codice HTML generato:The generated HTML:

<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:Assume the route prefix isn't part of the matching routing template, as with the following MVC view:

@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:The following HTML is generated because speakerid wasn't found in the matching route:

<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.If either asp-controller or asp-action aren't specified, then the same default processing is followed as is in the asp-route attribute.

asp-routeasp-route

L'attributo asp-route viene usato per la creazione di un URL collegato direttamente a una route denominata.The asp-route attribute is used for creating a URL linking directly to a named route. Mediante gli attributi di routing è possibile assegnare un nome a una route come mostrato in SpeakerController e usarla nell'azione Evaluations corrispondente:Using routing attributes, a route can be named as shown in the SpeakerController and used in its Evaluations action:

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

Nel markup seguente l'attributo asp-route fa riferimento alla route denominata:In the following markup, the asp-route attribute references the named route:

<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.The Anchor Tag Helper generates a route directly to that controller action using the URL /Speaker/Evaluations. Codice HTML generato:The generated HTML:

<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.If asp-controller or asp-action is specified in addition to asp-route, the route generated may not be what you expect. Per evitare un conflitto di route, è consigliabile non usare asp-route con gli attributi asp-controller o asp-action.To avoid a route conflict, asp-route shouldn't be used with the asp-controller and asp-action attributes.

asp-all-route-dataasp-all-route-data

L'attributo asp-all-route-data supporta la creazione di un dizionario di coppie chiave-valore.The asp-all-route-data attribute supports the creation of a dictionary of key-value pairs. La chiave è il nome del parametro e il valore è il valore del parametro.The key is the parameter name, and the value is the parameter value.

Nell'esempio seguente viene inizializzato un dizionario che viene poi passato a una visualizzazione Razor.In the following example, a dictionary is initialized and passed to a Razor view. In alternativa è possibile passare i dati con il modello.Alternatively, the data could be passed in with your model.

@{
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:The preceding code generates the following HTML:

<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:The asp-all-route-data dictionary is flattened to produce a querystring meeting the requirements of the overloaded Evaluations action:

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

In presenza di chiavi nel dizionario corrispondenti ai parametri di route, questi valori vengono sostituiti nella route come appropriato.If any keys in the dictionary match route parameters, those values are substituted in the route as appropriate. Gli altri valori non corrispondenti vengono generati come parametri di richiesta.The other non-matching values are generated as request parameters.

asp-fragmentasp-fragment

L'attributo asp-fragment definisce un frammento di URL da accodare all'URL.The asp-fragment attribute defines a URL fragment to append to the URL. L'helper tag di ancoraggio aggiunge il carattere hash (#).The Anchor Tag Helper adds the hash character (#). Considerare il markup seguente:Consider the following markup:

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

Codice HTML generato:The generated HTML:

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

I tag hash sono utili per la compilazione di app sul lato client.Hash tags are useful when building client-side apps. Ad esempio possono essere usati per semplificare l'uso di contrassegni e la ricerca in JavaScript.They can be used for easy marking and searching in JavaScript, for example.

asp-areaasp-area

L'attributo asp-area imposta il nome dell'area usato per impostare la route appropriata.The asp-area attribute sets the area name used to set the appropriate route. Gli esempi seguenti illustrano come l'attributo asp-area determina la modifica del mapping delle route.The following examples depict how the asp-area attribute causes a remapping of routes.

Utilizzo in Razor PagesUsage in Razor Pages

Le aree Razor Pages sono supportate in ASP.NET Core 2.1 o versioni successive.Razor Pages areas are supported in ASP.NET Core 2.1 or later.

Considerare la gerarchia di directory seguente:Consider the following directory hierarchy:

  • {Nome progetto}{Project name}
    • wwwrootwwwroot
    • AreeAreas
      • SessioniSessions
        • PaginePages
          • _ViewStart.cshtml_ViewStart.cshtml
          • Index.cshtmlIndex.cshtml
          • Index.cshtml.csIndex.cshtml.cs
    • PaginePages

Il markup per fare riferimento alla pagina Razor Index dell'area Sessioni è:The markup to reference the Sessions area Index Razor Page is:

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

Codice HTML generato:The generated HTML:

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

Suggerimento

Per supportare le aree in un'app Razor Pages, eseguire una delle operazioni seguenti in Startup.ConfigureServices:To support areas in a Razor Pages app, do one of the following in Startup.ConfigureServices:

Utilizzo in MVCUsage in MVC

Considerare la gerarchia di directory seguente:Consider the following directory hierarchy:

  • {Nome progetto}{Project name}
    • wwwrootwwwroot
    • AreeAreas
      • BlogBlogs
        • ControllerControllers
          • HomeController.csHomeController.cs
        • VisualizzazioniViews
          • HomeHome
            • AboutBlog.cshtmlAboutBlog.cshtml
            • Index.cshtmlIndex.cshtml
          • _ViewStart.cshtml_ViewStart.cshtml
    • ControllerControllers

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.Setting asp-area to "Blogs" prefixes the directory Areas/Blogs to the routes of the associated controllers and views for this anchor tag. Il markup per fare riferimento alla visualizzazione AboutBlog è:The markup to reference the AboutBlog view is:

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

Codice HTML generato:The generated HTML:

<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.To support areas in an MVC app, the route template must include a reference to the area, if it exists. Tale modello è rappresentato dal secondo parametro della chiamata del metodo routes.MapRoute in Startup.Configure:That template is represented by the second parameter of the routes.MapRoute method call 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-protocolasp-protocol

L'attributo asp-protocol consente di specificare un protocollo (ad esempio https) nell'URL.The asp-protocol attribute is for specifying a protocol (such as https) in your URL. Ad esempio:For example:

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

Codice HTML generato:The generated HTML:

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

Il nome host nell'esempio è localhost.The host name in the example is localhost. L'helper tag di ancoraggio usa il dominio pubblico del sito Web per generare l'URL.The Anchor Tag Helper uses the website's public domain when generating the URL.

asp-hostasp-host

L'attributo asp-host consente di specificare un nome host nell'URL.The asp-host attribute is for specifying a host name in your URL. Ad esempio:For example:

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

Codice HTML generato:The generated HTML:

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

asp-pageasp-page

L'attributo asp-page viene usato con le pagine Razor.The asp-page attribute is used with Razor Pages. Usarlo per impostare il valore dell'attributo href per un tag di ancoraggio su una pagina specifica.Use it to set an anchor tag's href attribute value to a specific page. L'URL viene creato anteponendo una barra ("/") al nome della pagina.Prefixing the page name with a forward slash ("/") creates the URL.

L'esempio seguente fa riferimento alla pagina Razor Attendee:The following sample points to the attendee Razor Page:

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

Codice HTML generato:The generated HTML:

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

L'attributo asp-page e gli attributi asp-route, asp-controller e asp-action si escludono a vicenda.The asp-page attribute is mutually exclusive with the asp-route, asp-controller, and asp-action attributes. asp-page può tuttavia essere usato con asp-route-{value} per il controllo del routing, come dimostra il markup seguente:However, asp-page can be used with asp-route-{value} to control routing, as the following markup demonstrates:

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

Codice HTML generato:The generated HTML:

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

asp-page-handlerasp-page-handler

L'attributo asp-page-handler viene usato con le pagine Razor.The asp-page-handler attribute is used with Razor Pages. È progettato per il collegamento di gestori di pagine specifici.It's intended for linking to specific page handlers.

Si consideri il gestore di pagine seguente:Consider the following page handler:

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.The page model's associated markup links to the OnGetProfile page handler. Si noti che il prefisso On<Verb> del nome del metodo del gestore di pagina viene omesso nel valore dell'attributo asp-page-handler.Note the On<Verb> prefix of the page handler method name is omitted in the asp-page-handler attribute value. Quando il metodo è asincrono, viene omesso anche il suffisso Async.When the method is asynchronous, the Async suffix is omitted, too.

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

Codice HTML generato:The generated HTML:

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

Risorse aggiuntiveAdditional resources