Helper tag di ancoraggio in ASP.NET Core
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 visualizzazione Indice di HomeController (/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¤tYear=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
- Sessioni
- 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
:
Impostare la versione di compatibilità su 2.1 o successiva.
Impostare la proprietà RazorPagesOptions.AllowAreas su
true
:services.AddMvc() .AddRazorPagesOptions(options => options.AllowAreas = true);
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
- Home
- Controller
- Blog
- 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>