Pomocnik tagów zakotwiczenia w programie ASP.NET Core

  • Artykuł

Autor: Peter Kellner i Scott Addie

Pomocnik tagów zakotwiczenia rozszerza standardowy tag kotwicy HTML (<a ... ></a>), dodając nowe atrybuty. Zgodnie z konwencją nazwy atrybutów są poprzedzone prefiksem asp-. Wartość atrybutu href renderowanego elementu kotwicy jest określana przez wartości atrybutów asp- .

Aby zapoznać się z omówieniem pomocników tagów, zobacz Pomocnicy tagów na platformie ASP.NET Core.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Funkcja SpeakerController jest używana w przykładach w tym dokumencie:

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; }
}

Atrybuty pomocnika tagów zakotwiczenia

asp-controller

Atrybut asp-controller przypisuje kontroler używany do generowania adresu URL. Na poniższej liście znaczników znajdują się wszystkie osoby mówiące:

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

Wygenerowany kod HTML:

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

asp-controller Jeśli atrybut jest określony i asp-action nie, wartość domyślna asp-action to akcja kontrolera skojarzona z aktualnie wykonywanym widokiem. Jeśli asp-action zostanie pominięty z poprzedniego znacznika, a pomocnik tagu zakotwiczenia jest używany w Homewidoku indeksu kontrolera (/Home), wygenerowany kod HTML to:

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

asp-action

Wartość atrybutu asp-action reprezentuje nazwę akcji kontrolera uwzględnionej w wygenerowanym href atrybucie. Poniższy znacznik ustawia wygenerowaną href wartość atrybutu na stronę oceny osoby mówiącej:

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

Wygenerowany kod HTML:

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

Jeśli nie asp-controller określono żadnego atrybutu, używany jest domyślny kontroler wywołujący widok wykonujący bieżący widok.

Jeśli wartość atrybutu asp-action to Index, żadna akcja nie jest dołączana do adresu URL, co prowadzi do wywołania akcji domyślnej Index . Określona akcja (lub domyślna) musi istnieć w kontrolerze, do których odwołuje się element .asp-controller

asp-route-{value}

Atrybut asp-route-{value} umożliwia prefiks trasy wieloznacznych. Każda wartość zajmująca {value} symbol zastępczy jest interpretowana jako potencjalny parametr trasy. Jeśli nie znaleziono trasy domyślnej, ten prefiks trasy jest dołączany do wygenerowanego href atrybutu jako parametr i wartość żądania. W przeciwnym razie jest on zastępowany w szablonie trasy.

Rozważ następujące działanie kontrolera:

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));

Przy użyciu domyślnego szablonu trasy zdefiniowanego w pliku 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?}");
});

Widok MVC używa modelu dostarczonego przez akcję w następujący sposób:

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

Symbol zastępczy trasy domyślnej {id?} został dopasowany. Wygenerowany kod HTML:

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

Załóżmy, że prefiks trasy nie jest częścią pasującego szablonu routingu, podobnie jak w przypadku następującego widoku 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>

Wygenerowano następujący kod HTML, ponieważ speakerid nie znaleziono go w pasującej trasie:

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

Jeśli zostanie określony element asp-controller lub asp-action nie zostanie określony, następuje to samo domyślne przetwarzanie, co w atrybucie asp-route .

asp-route

Atrybut asp-route służy do tworzenia adresu URL łączącego się bezpośrednio z nazwaną trasą. Przy użyciu atrybutów routingu trasa może być nazwana tak, jak pokazano w akcji i użyta w SpeakerController jej Evaluations akcji:

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

W poniższym znaczniku asp-route atrybut odwołuje się do nazwanej trasy:

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

Pomocnik tagu zakotwiczenia generuje trasę bezpośrednio do tej akcji kontrolera przy użyciu adresu URL /Speaker/Evaluations. Wygenerowany kod HTML:

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

Jeśli asp-controller oprócz parametru lub asp-action jest określona oprócz asp-routeparametru , wygenerowana trasa może nie być oczekiwana. Aby uniknąć konfliktu tras, asp-route nie należy używać z asp-controller atrybutami i asp-action .

asp-all-route-data

Atrybut asp-all-route-data obsługuje tworzenie słownika par klucz-wartość. Klucz jest nazwą parametru, a wartość jest wartością parametru.

W poniższym przykładzie słownik jest inicjowany i przekazywany do Razor widoku. Alternatywnie dane mogą być przekazywane do modelu.

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

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

Powyższy kod generuje następujący kod HTML:

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

Słownik asp-all-route-data jest spłaszczany w celu utworzenia ciągu zapytania spełniającego wymagania przeciążonej Evaluations akcji:

public IActionResult Evaluations() => View();

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

Jeśli jakiekolwiek klucze w słowniku pasują do parametrów trasy, te wartości są zastępowane zgodnie z potrzebami w trasie. Inne wartości niezgodne są generowane jako parametry żądania.

asp-fragment

Atrybut asp-fragment definiuje fragment adresu URL, który ma być dołączany do adresu URL. Pomocnik tagu zakotwiczenia dodaje znak skrótu (#). Rozważmy następujące znaczniki:

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

Wygenerowany kod HTML:

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

Tagi skrótów są przydatne podczas tworzenia aplikacji po stronie klienta. Mogą one służyć do łatwego oznaczania i wyszukiwania w języku JavaScript, na przykład.

asp-area

Atrybut asp-area ustawia nazwę obszaru używaną do ustawiania odpowiedniej trasy. W poniższych przykładach przedstawiono sposób, w jaki asp-area atrybut powoduje ponowne mapowanie tras.

Użycie na Razor stronach

Razor Obszary stron są obsługiwane w programie ASP.NET Core 2.1 lub nowszym.

Rozważ następującą hierarchię katalogów:

  • {Nazwa projektu}
    • Wwwroot
    • Obszary
      • Sesje
        • Strony
          • _ViewStart.cshtml
          • Index.cshtml
          • Index.cshtml.cs
    • Strony

Znacznik do odwołowania się do strony indeksu Razor obszaru sesji to:

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

Wygenerowany kod HTML:

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

Napiwek

Aby obsługiwać obszary w Razor aplikacji Pages, wykonaj jedną z następujących czynności w Startup.ConfigureServicespliku :

Użycie w usłudze MVC

Rozważ następującą hierarchię katalogów:

  • {Nazwa projektu}
    • Wwwroot
    • Obszary
      • Blogi
        • Kontrolery
          • HomeController.cs
        • Widoki
          • Home
            • AboutBlog.cshtml
            • Index.cshtml
          • _ViewStart.cshtml
    • Kontrolery

Ustawienie asp-area na "Blogi" prefiksuje katalog Obszary/blogi na trasy skojarzonych kontrolerów i widoków dla tego tagu zakotwiczenia. Znaczniki odwołujące się do widoku AboutBlog to:

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

Wygenerowany kod HTML:

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

Napiwek

Aby obsługiwać obszary w aplikacji MVC, szablon trasy musi zawierać odwołanie do obszaru, jeśli istnieje. Ten szablon jest reprezentowany przez drugi parametr routes.MapRoute wywołania metody w pliku 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

Atrybut asp-protocol służy do określania protokołu (takiego jak https) w adresie URL. Przykład:

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

Wygenerowany kod HTML:

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

Nazwa hosta w przykładzie to localhost. Pomocnik tagów zakotwiczenia używa domeny publicznej witryny internetowej podczas generowania adresu URL.

asp-host

Atrybut asp-host służy do określania nazwy hosta w adresie URL. Przykład:

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

Wygenerowany kod HTML:

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

asp-page

Atrybut asp-page jest używany z usługą Razor Pages. Służy do ustawiania wartości atrybutu tagu href kotwicy na określoną stronę. Prefiksowanie nazwy strony za / pomocą polecenia tworzy adres URL pasującej strony z katalogu głównego aplikacji:

W przykładowym kodzie następujący znacznik tworzy link do strony uczestnika Razor :

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

Wygenerowany kod HTML:

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

Atrybut asp-page wzajemnie wyklucza się z atrybutami asp-route, asp-controlleri asp-action . Można jednak użyć polecenia w asp-route-{value} celu kontrolowania routingu, asp-page jak pokazano w poniższym znaczniku:

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

Wygenerowany kod HTML:

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

Jeśli strona, do którego odwołuje się odwołanie, zostanie wygenerowany link do bieżącej strony przy użyciu wartości otoczenia z żądania. Nie jest wskazane żadne ostrzeżenie, z wyjątkiem poziomu dziennika debugowania.

program obsługi asp-page-handler

Atrybut programu obsługi asp-page-handler jest używany z usługą Razor Pages. Jest ona przeznaczona do łączenia z określonymi procedurami obsługi stron.

Rozważmy następującą procedurę obsługi stron:

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

    // code omitted for brevity
}

Skojarzone znaczniki modelu strony łączą się z procedurą OnGetProfile obsługi stron. Zwróć uwagę, że On<Verb> prefiks nazwy metody obsługi strony zostanie pominięty w wartości atrybutu asp-page-handler . Gdy metoda jest asynchroniczna, Async sufiks zostanie również pominięty.

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

Wygenerowany kod HTML:

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

Dodatkowe zasoby