Auxiliar de Marca de Âncora no ASP.NET Core
De Peter Kellner e Scott Addie
O Auxiliar de Marca de Âncora aprimora a marca de âncora HTML padrão (<a ... ></a>
) adicionando novos atributos. Por convenção, os nomes de atributos são prefixados com asp-
. O valor do atributo href
do elemento de âncora renderizado é determinado pelos valores dos atributos asp-
.
Para ter uma visão geral dos Auxiliares de Marcação, confira Auxiliares de Marcação no ASP.NET Core.
Exibir ou baixar código de exemplo (como baixar)
SpeakerController é usado em exemplos ao longo de todo este 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; }
}
Atributos do Auxiliar de Marca de Âncora
asp-controller
O atributo asp-controller designa o controlador usado para gerar a URL. A marcação a seguir lista todos os palestrantes:
<a asp-controller="Speaker"
asp-action="Index">All Speakers</a>
O HTML gerado:
<a href="/Speaker">All Speakers</a>
Se o atributo asp-controller
for especificado e asp-action
não for, o valor asp-action
padrão é a ação do controlador associada ao modo de exibição em execução no momento. Se asp-action
for omitido da marcação anterior e o Auxiliar de Marca de Âncora for usado na exibição Índice (/Home) do HomeController, o HTML gerado será:
<a href="/Home">All Speakers</a>
asp-action
O valor do atributo asp-action representa o nome da ação do controlador incluído no atributo href
gerado. A seguinte marcação define o valor do atributo href
gerado para a página de avaliações do palestrante:
<a asp-controller="Speaker"
asp-action="Evaluations">Speaker Evaluations</a>
O HTML gerado:
<a href="/Speaker/Evaluations">Speaker Evaluations</a>
Se nenhum atributo asp-controller
for especificado, o controlador padrão que está chamando a exibição que executa a exibição atual é usado.
Se o valor do atributo asp-action
for Index
, nenhuma ação será anexada à URL, causando a invocação da ação Index
padrão. A ação especificada (ou padrão), deve existir no controlador referenciado em asp-controller
.
asp-route-{value}
O atributo asp-route-{value} permite um prefixo de roteamento de caractere curinga. Qualquer valor que esteja ocupando o espaço reservado {value}
é interpretado como um possível parâmetro de roteamento. Se uma rota padrão não for encontrada, esse prefixo de rota será anexado ao atributo href
gerado como um valor e parâmetro de solicitação. Caso contrário, ele será substituído no modelo de rota.
Considere a seguinte ação do controlador:
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));
Com um modelo de rota padrão definido em 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?}");
});
O modo de exibição MVC usa o modelo fornecido pela ação, da seguinte forma:
@model Speaker
<!DOCTYPE html>
<html>
<body>
<a asp-controller="Speaker"
asp-action="Detail"
asp-route-id="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
</body>
</html>
O espaço reservado {id?}
da rota padrão foi correspondido. O HTML gerado:
<a href="/Speaker/Detail/12">SpeakerId: 12</a>
Suponha que o prefixo de roteamento não faça parte do modelo de roteamento de correspondência, como com o seguinte modo de exibição de MVC:
@model Speaker
<!DOCTYPE html>
<html>
<body>
<a asp-controller="Speaker"
asp-action="Detail"
asp-route-speakerid="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
<body>
</html>
O seguinte HTML é gerado porque o speakerid
não foi encontrado na rota correspondente:
<a href="/Speaker/Detail?speakerid=12">SpeakerId: 12</a>
Se asp-controller
ou asp-action
não forem especificados, o mesmo processamento padrão será seguido, como no atributo asp-route
.
asp-route
O atributo asp-route é usado para criar um link de URL diretamente para uma rota nomeada. Usando atributos de roteamento, uma rota pode ser nomeada como mostrado em SpeakerController
e usada em sua ação Evaluations
:
[Route("/Speaker/Evaluations",
Name = "speakerevals")]
Na seguinte marcação, o atributo asp-route
faz referência à rota nomeada:
<a asp-route="speakerevals">Speaker Evaluations</a>
O Auxiliar de Marca de Âncora gera uma rota diretamente para essa ação de controlador usando a URL /Speaker/Evaluations. O HTML gerado:
<a href="/Speaker/Evaluations">Speaker Evaluations</a>
Se asp-controller
ou asp-action
for especificado além de asp-route
, a rota gerada poderá não ser a esperada. Para evitar um conflito de rota, asp-route
não deve ser usado com os atributos asp-controller
ou asp-action
.
asp-all-route-data
O atributo asp-all-route-data oferece suporte à criação de um dicionário ou par chave-valor. A chave é o nome do parâmetro e o valor é o valor do parâmetro.
No exemplo a seguir, um dicionário é inicializado e passado para um modo de exibição do Razor. Como alternativa, os dados podem ser passado com seu modelo.
@{
var parms = new Dictionary<string, string>
{
{ "speakerId", "11" },
{ "currentYear", "true" }
};
}
<a asp-route="speakerevalscurrent"
asp-all-route-data="parms">Speaker Evaluations</a>
O código anterior gera o seguinte HTML:
<a href="/Speaker/EvaluationsCurrent?speakerId=11¤tYear=true">Speaker Evaluations</a>
O dicionário asp-all-route-data
é simplificado para produzir um querystring que atenda aos requisitos da ação Evaluations
sobrecarregada:
public IActionResult Evaluations() => View();
[Route("/Speaker/EvaluationsCurrent",
Name = "speakerevalscurrent")]
public IActionResult Evaluations(
Se todas as chaves no dicionário corresponderem aos parâmetros, esses valores serão substituídos na rota conforme apropriado. Os outros valores não correspondentes são gerados como parâmetros de solicitação.
asp-fragment
O atributo asp-fragment define um fragmento de URL para anexar à URL. O Auxiliar de Marca de Âncora adiciona o caractere de hash (#). Considere a seguinte marcação:
<a asp-controller="Speaker"
asp-action="Evaluations"
asp-fragment="SpeakerEvaluations">Speaker Evaluations</a>
O HTML gerado:
<a href="/Speaker/Evaluations#SpeakerEvaluations">Speaker Evaluations</a>
As marcas de hash são úteis ao criar aplicativos do lado do cliente. Elas podem ser usadas para marcar e pesquisar com facilidade em JavaScript, por exemplo.
asp-area
O atributo asp-area define o nome de área usado para definir a rota apropriada. O exemplo a seguir ilustra como o atributo asp-area
causa um remapeamento das rotas.
Uso em Páginas do Razor
As áreas de Páginas do Razor têm suporte no ASP.NET Core 2.1 ou posterior.
Considere a seguinte hierarquia de diretórios:
- {Nome do projeto}
- wwwroot
- Áreas
- Sessões
- Páginas
- _ViewStart.cshtml
Index.cshtml
Index.cshtml.cs
- Páginas
- Sessões
- Páginas
A marcação para fazer referência à Página de Índiceda áreaRazor é:
<a asp-area="Sessions"
asp-page="/Index">View Sessions</a>
O HTML gerado:
<a href="/Sessions">View Sessions</a>
Dica
para dar suporte a áreas em um aplicativo de Páginas do Razor, siga um dos procedimentos em Startup.ConfigureServices
:
Defina a versão de compatibilidade para 2.1 ou posterior.
Para fazer isso, defina a RazorPagesOptions.AllowAreaspropriedade para
true
:services.AddMvc() .AddRazorPagesOptions(options => options.AllowAreas = true);
Uso no MVC
Considere a seguinte hierarquia de diretórios:
- {Nome do projeto}
- wwwroot
- Áreas
- Blogs
- Controladores
HomeController.cs
- Exibições
- Home
AboutBlog.cshtml
Index.cshtml
- _ViewStart.cshtml
- Home
- Controladores
- Blogs
- Controladores
Definir asp-area
como "Blogs" faz com que o diretório Áreas/Blogs seja prefixado nas rotas dos controladores e exibições associados a essa marca de âncora. A marcação para fazer referência à exibição AboutBlog é:
<a asp-area="Blogs"
asp-controller="Home"
asp-action="AboutBlog">About Blog</a>
O HTML gerado:
<a href="/Blogs/Home/AboutBlog">About Blog</a>
Dica
Para dar suporte às áreas em um aplicativo MVC, o modelo de rota deverá incluir uma referência à área, se ela existir. Esse modelo é representado pelo segundo parâmetro da chamada do método routes.MapRoute
em 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
O atributo asp-protocol é destinado a especificar um protocolo (como https
) em sua URL. Por exemplo:
<a asp-protocol="https"
asp-controller="Home"
asp-action="About">About</a>
O HTML gerado:
<a href="https://localhost/Home/About">About</a>
O nome do host no exemplo é localhost. O Auxiliar de Marca de Âncora usa o domínio público do site ao gerar a URL.
asp-host
O atributo asp-host é para especificar um nome do host na sua URL. Por exemplo:
<a asp-protocol="https"
asp-host="microsoft.com"
asp-controller="Home"
asp-action="About">About</a>
O HTML gerado:
<a href="https://microsoft.com/Home/About">About</a>
asp-page
O atributo asp-page é usado com as Páginas do Razor. Use-o para definir um valor de atributo href
da marca de âncora para uma página específica. Prefixar o nome da página com /
cria uma URL para uma página correspondente da raiz do aplicativo:
Com o código de exemplo, a marcação a seguir cria um link para a Página Razor do participante :
<a asp-page="/Attendee">All Attendees</a>
O HTML gerado:
<a href="/Attendee">All Attendees</a>
O atributo asp-page
é mutuamente exclusivo com os atributos asp-route
, asp-controller
e asp-action
. No entanto, o asp-page
pode ser usado com o asp-route-{value}
para controlar o roteamento, como mostra a marcação a seguir:
<a asp-page="/Attendee"
asp-route-attendeeid="10">View Attendee</a>
O HTML gerado:
<a href="/Attendee?attendeeid=10">View Attendee</a>
Se a página referenciada não existir, um link para a página atual será gerado usando um valor ambiente da solicitação. Nenhum aviso é indicado, exceto no nível do log de depuração.
asp-page-handler
O atributo asp-page-handler é usado com as Páginas do Razor. Ele se destina à vinculação a manipuladores de página específicos.
Considere o seguinte manipulador de página:
public void OnGetProfile(int attendeeId)
{
ViewData["AttendeeId"] = attendeeId;
// code omitted for brevity
}
A marcação associada do modelo de página vincula ao manipulador de página OnGetProfile
. Observe que o prefixo On<Verb>
do nome do método do manipulador de página é omitido no valor do atributo asp-page-handler
. Quando o método é assíncrono, o sufixo Async
também é omitido.
<a asp-page="/Attendee"
asp-page-handler="Profile"
asp-route-attendeeid="12">Attendee Profile</a>
O HTML gerado:
<a href="/Attendee?attendeeid=12&handler=Profile">Attendee Profile</a>