Auxiliar de Marca de Âncora no ASP.NET Core

  • Artigo

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ção de Âncora for usado HomeModo de exibiçãode Índice do Controle (/Home), 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&currentYear=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

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:

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
    • 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>

Recursos adicionais