Вспомогательная функция тега привязки в ASP.NET Core MVC

  • Статья

Авторы: Питер Кельнер (Peter Kellner) и Скотт Эдди (Scott Addie).

Вспомогательная функция тега привязки повышает эффективность стандартного тега привязки HTML (<a ... ></a>) путем добавления новых атрибутов. Как правило, все имена атрибутов начинаются с asp-. Отображаемое значение атрибута href элемента привязки определяется значениями атрибутов asp-.

Общие сведения о вспомогательных функциях тегов см. в разделе Вспомогательные функции тегов в ASP.NET Core.

Просмотреть или скачать образец кода (описание загрузки)

В примерах в этом документе используется SpeakerController

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

Атрибуты вспомогательной функции тега привязки

asp-controller

Атрибут asp-controller назначает контроллер, используемый для создания URL-адреса. Следующий элемент перечисляет всех говорящих:

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

Созданный HTML:

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

Если атрибут asp-controller указан, а атрибут asp-action — нет, действием контроллера, связанным с выполняющимся представлением, будет заданное по умолчанию значение asp-action. Если asp-action опущен из предыдущей разметки, а вспомогательный элемент тега привязки используется в Homeпредставлении индекса контроллера (/Home), созданный HTML-код:

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

asp-action

Значение атрибута asp-action представляет имя действия контроллера, включенное в созданный атрибут href. Следующий элемент задает созданное значение атрибута href на странице динамика оценок:

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

Созданный HTML:

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

Если атрибут asp-controller не указан, будет использоваться контроллер по умолчанию, вызывающий представление при выполнении текущего представления.

Если атрибут asp-action имеет значение Index, действия не добавляются к URL-адресу и вызывается метод Index по умолчанию. В контроллере, на который есть ссылка в asp-controller, должно существовать указанное действие (или заданное по умолчанию).

asp-route-{value}

Атрибут asp-route-{value} включает подстановочный префикс маршрута. Любое значение, подставляемое вместо {value}, рассматривается как потенциальный параметр маршрута. Если маршрут по умолчанию не найден, этот префикс маршрута будет добавлен к созданному атрибуту href в виде параметра запроса и значения. В противном случае он будет заменен в шаблоне маршрута.

Рассмотрим следующее действие контроллера:

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

С шаблоном маршрута по умолчанию, определенным в 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?}");
});

Представление MVC использует модель, предоставляемую действием:

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

Заполнитель {id?} маршрута по умолчанию соответствует требуемому. Созданный HTML:

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

Предположим, префикс маршрута не входит в состав соответствующего шаблона маршрутизации, как в случае со следующим представлением 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>

Следующий код HTML будет создан, так как элемент speakerid не найден в соответствующем маршруте:

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

Если атрибут asp-controller или asp-action не указан, применяется та же обработка по умолчанию, что и в атрибуте asp-route.

asp-route

Атрибут asp-route используется для связывания URL-адреса непосредственно с именованным маршрутом. С помощью атрибутов маршрутизации маршруту можно присвоить имя, как показано в классе SpeakerController и используется в его действии Evaluations:

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

В следующем элементе атрибут asp-route ссылается на именованный маршрут:

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

Вспомогательная функция тега привязки создает маршрут непосредственно к этому методу контроллера, используя /Speaker/Evaluations URL-адреса. Созданный HTML:

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

Если наряду с атрибутом asp-route указаны атрибут asp-controller или asp-action, созданный маршрут может отличаться от ожидаемого. Во избежание конфликта маршрута asp-route нельзя использовать вместе с атрибутами asp-controller или asp-action.

asp-all-route-data

Атрибут asp-all-route-data поддерживает создание словаря пар "ключ-значение". Ключ является именем параметра, а значение — значением параметра.

В следующем примере словарь инициализируется и передается в Razor представление. Кроме того, данные могут быть переданы с помощью модели.

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

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

Предыдущий код вызывает следующий код HTML:

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

Словарь asp-all-route-data предназначен для создания строки запроса, соответствующей требованиям перегруженного действия Evaluations:

public IActionResult Evaluations() => View();

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

Если ключи в словаре совпадают с параметрами маршрута, эти значения будут соответствующим образом заменены в маршруте. В качестве параметров запроса будут созданы другие несовпадающие значения.

asp-fragment

Атрибут asp-fragment определяет фрагмент URL-адреса, добавляемый к URL-адресу. Вспомогательная функция тега привязки добавляет символ решетки (#). Рассмотрим следующую разметку :

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

Созданный HTML:

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

Хэштеги полезны при создании приложений на стороне клиента. Например, их можно использовать для простоты пометки и поиска на языке JavaScript.

asp-area

Атрибут asp-area указывает имя области, используемое платформой для определения соответствующего маршрута. Ниже приведен пример того, как атрибут asp-area приводит к повторному сопоставлению маршрутов.

Использование в Razor страницах

Razor Области страниц поддерживаются в ASP.NET Core 2.1 или более поздней версии.

Пусть имеется следующая иерархия каталогов:

  • {Имя проекта}
    • wwwroot
    • Области
      • Сеансы
        • Страницы
          • _ViewStart.cshtml
          • Index.cshtml
          • Index.cshtml.cs
    • Страницы

Разметка для ссылки на страницу индексаRazor области сеансов:

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

Созданный HTML:

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

Совет

Чтобы обеспечить поддержку областей в Razor приложении Pages, выполните одно из следующих Startup.ConfigureServicesдействий:

Использование в MVC

Пусть имеется следующая иерархия каталогов:

  • {Имя проекта}
    • wwwroot
    • Области
      • Блоги
        • Контроллеры
          • HomeController.cs
        • Представления
          • Home
            • AboutBlog.cshtml
            • Index.cshtml
          • _ViewStart.cshtml
    • Контроллеры

При установке для атрибута asp-area значения Blogs перед маршрутами связанных контроллеров и представлений для этого тега привязки добавляется каталог Areas/Blogs. Исправления для ссылки на представление AboutBlog:

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

Созданный HTML:

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

Совет

Для поддержки областей в приложении MVC в шаблон маршрута необходимо включить ссылку на область, если она существует. Этот шаблон представлен вторым параметром вызова метода routes.MapRoute в 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

Атрибут asp-protocol предназначен для указания протокола (например, https) в URL-адресе. Например:

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

Созданный HTML:

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

Имя узла в примере — localhost. При формировании URL-адреса вспомогательная функция тега привязки использует общедоступный домен веб-сайта.

asp-host

Атрибут asp-host предназначен для определения имени узла в URL-адресе. Например:

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

Созданный HTML:

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

asp-page

Атрибут asp-page используется с Razor Pages. Используйте его для определения значения атрибута href тега привязки для определенной страницы. Префикс имени страницы / с помощью создания URL-адреса для соответствующей страницы из корневого каталога приложения:

В примере кода следующая разметка создает ссылку на страницу участника Razor :

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

Созданный HTML:

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

Атрибут asp-page является взаимоисключающим с атрибутами asp-route, asp-controller и asp-action. Тем не менее asp-page можно использовать с asp-route-{value} для управления маршрутизацией, как показано в следующем элементе:

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

Созданный HTML:

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

Если ссылка на не существует, ссылка на текущую страницу создается с помощью внешнего значения из запроса. Предупреждение не указано, кроме отладочного уровня журнала.

asp-page-handler

Атрибут asp-page-handler используется с Razor Pages. Он предназначен для связывания с обработчиками определенных страниц.

Рассмотрим следующий обработчик страниц:

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

    // code omitted for brevity
}

Связанный элемент модели страницы ссылается на обработчик страниц OnGetProfile. Обратите внимание, что префикс On<Verb> имени метода обработчика страниц опущен в значении атрибута asp-page-handler. Когда метод является асинхронным, суффикс Async также опускается.

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

Созданный HTML:

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

Дополнительные ресурсы