Маршрутизация действий контроллера в ASP.NET Core

Авторы: Райан Новак (Ryan Nowak), Кирк Ларкин (Kirk Larkin) и Рик Андерсон (Rick Anderson)

контроллеры ASP.NET Core используют middleware для сопоставления URL-адресов входящих запросов и связывания их с действиями. Шаблоны маршрутов:

• Определяются при запуске в Program.cs или в атрибутах.
• Опишите, как пути URL сопоставляются с действиями.
• Используются для создания URL-адресов для ссылок. Созданные ссылки обычно возвращаются в ответах.

Действия либо маршрутизируются по соглашению, либо маршрутизируются с помощью атрибутов. Задание маршрута для контроллера или метода действия означает, что они используют маршрутизацию на основе атрибутов. Дополнительные сведения см. в разделе Смешанная маршрутизация.

Этот документ:

• Объясняет взаимодействие между MVC и маршрутизацией:
  • Как типичные приложения MVC используют функции маршрутизации.
  • Охватывает оба:
    • Обычная маршрутизация обычно используется с контроллерами и представлениями.
    • Маршрутизация атрибутов , используемая с REST API. Если вы в первую очередь заинтересованы в маршрутизации для API, перейдите к разделу "Маршрутизация атрибутов для RESTREST API".
  • Дополнительные сведения о маршрутизации см. в разделе "Маршрутизация ".
• Относится к системе маршрутизации по умолчанию в качестве маршрутизации конечных точек. Для обеспечения совместимости можно использовать контроллеры с предыдущей версией маршрутизации. Инструкции см. в руководстве по миграции 2.2-3.0.

Настройка обычного маршрута

Шаблон MVC ASP.NET Core создает конвенционную маршрутизацию код, аналогичный следующему примеру:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Используйте MapControllerRoute для создания одного маршрута. Единственный маршрут — default. Большинство приложений с контроллерами и представлениями используют шаблон маршрута, аналогичный маршруту default . REST API должны использовать маршрутизацию атрибутов.

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Шаблон "{controller=Home}/{action=Index}/{id?}"маршрута:

• Соответствует URL-адресу, например /Products/Details/5

• Извлекает значения { controller = Products, action = Details, id = 5 } маршрута путем маркеризации пути. Извлечение значений маршрута приводит к совпадению, если у приложения есть контроллер с именем ProductsController и действием Details :

  public class ProductsController : Controller
  {
      public IActionResult Details(int id)
      {
          return ControllerContext.MyDisplayRouteInfo(id);
      }
  }
  

  MyDisplayRouteInfo предоставляется пакетом NuGet Rick.Docs.Samples.RouteInfo и отображает информацию о маршруте.

• /Products/Details/5 модель привязывает значение id = 5 для задания id параметра 5. Дополнительные сведения см. в разделе "Привязка модели".

• {controller=Home} определяет Home как controller по умолчанию.

• {action=Index} определяет Index как action по умолчанию.

• Символ ? в {id?} указывает, что id является необязательным.

  • Параметры маршрута по умолчанию и параметры, которые не обязательны, не обязаны присутствовать в пути URL-адреса для сопоставления. Подробное описание синтаксиса шаблона маршрута см. в справочнике по шаблону маршрута.

• Соответствует URL-пути /.

• Формирует значения маршрута { controller = Home, action = Index }.

Значения для controller и action используют значения по умолчанию. id не создает значение, так как в пути URL-адреса нет соответствующего сегмента. / совпадает только в том случае, если существует HomeController и Index действие:

public class HomeController : Controller
{
    public IActionResult Index() { ... }
}

Используя предыдущее определение контроллера и шаблон маршрута, HomeController.Index действие выполняется для следующих путей URL-адресов:

• /Home/Index/17
• /Home/Index
• /Home
• /

Путь URL-адреса / использует шаблон маршрута по умолчанию Home, контроллер и действие Index. Путь URL-адреса /Home использует действие по умолчанию из шаблона маршрута Index.

Вспомогательный метод MapDefaultControllerRoute:

app.MapDefaultControllerRoute();

Replaces:

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Important

Маршрутизация настраивается с использованием ПО промежуточного слоя UseRouting и UseEndpoints. Чтобы использовать контроллеры, выполните приведенные действия.

• Вызовите MapControllers, чтобы сопоставить контроллеры с маршрутизацией по атрибутам.
• Вызовите MapControllerRoute или MapAreaControllerRoute, чтобы сопоставить маршруты как для контроллеров с обычной маршрутизацией, так и для контроллеров с маршрутизацией на основе атрибутов.

Приложениям обычно не требуется вызывать UseRouting или UseEndpoints. WebApplicationBuilder настраивает конвейер промежуточного ПО, который оборачивает компоненты промежуточного ПО, добавленные в Program.cs, с помощью UseRouting и UseEndpoints. Дополнительные сведения см. в разделе Routing в ASP.NET Core.

Обычная маршрутизация

Используйте обычную маршрутизацию с контроллерами и представлениями. Маршрут default :

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Приведенный выше код является примером обычного маршрута. Она называется обычной маршрутизацией, так как она устанавливает соглашение для путей URL-адресов:

• Первый сегмент пути, {controller=Home}, соответствует имени контроллера.
• Второй сегмент {action=Index} соответствует имени действия.
• Третий сегмент {id?} используется для необязательного id. ? в {id?} делает это необязательным. id сопоставляется с сущностью модели.

При использовании этого маршрута default, путь URL:

• /Products/List сопоставляется действию ProductsController.List.
• /Blog/Article/17 сопоставляется с BlogController.Article моделью и обычно привязывает id параметр к 17.

Это сопоставление:

• Основан только на именах контроллеров и действий.
• Не основан на пространствах имен, расположениях исходного файла или параметрах метода.

Используя обычную маршрутизацию с маршрутом по умолчанию, вам не нужно создавать новый шаблон URL-адреса для каждого действия. Для приложения с действиями в стиле CRUD важно обеспечивать единообразие URL-адресов во всех контроллерах:

• Помогает упростить код.
• Делает пользовательский интерфейс более предсказуемым.

Warning

Шаблон маршрута определяет id как необязательный. Действия могут выполняться без дополнительного идентификатора, предоставленного в качестве части URL-адреса. Как правило, если id опущен из URL-адреса:

• Привязка модели задает для id значение 0.
• В базе данных не найдена сущность, соответствующая id == 0.

Маршрутизация атрибутов обеспечивает точное управление идентификатором, необходимым для некоторых действий, а не для других. Согласно принятому соглашению в документации указываются необязательные параметры, такие как id, если они могут встречаться при корректном использовании.

Для большинства приложений следует выбрать базовую описательную схему маршрутизации таким образом, чтобы URL-адреса были удобочитаемыми и осмысленными. Традиционный маршрут по умолчанию {controller=Home}/{action=Index}/{id?}.

• Поддерживает основную и описательную схемы маршрутизации.
• Является отправной точкой для приложений на базе пользовательского интерфейса.
• Является единственным шаблоном маршрута, необходимым для многих веб-приложений пользовательского интерфейса. Для более крупных веб-приложений другой подход с использованием Areas часто оказывается вполне достаточным.

MapControllerRoute и MapAreaRoute :

• Автоматически назначать конечным точкам значение order исходя из порядка их вызова.

Маршрутизация конечных точек в ASP.NET Core:

• Не имеет концепции маршрутов.
• Не предоставляет гарантий определенного порядка выполнения расширяемости функций. Все конечные точки обрабатываются одновременно.

Включите ведение журнала, чтобы увидеть, как встроенные реализации маршрутизации, такие как Route, сопоставляют запросы.

Маршрутизация атрибутов описана далее в этом документе.

Несколько обычных маршрутов

Вы можете настроить несколько обычных маршрутов , добавив в него дополнительные вызовы MapControllerRoute и MapAreaControllerRoute. При добавлении этих вызовов можно определить несколько соглашений или добавить обычные маршруты, выделенные для определенного действия, например:

app.MapControllerRoute(name: "blog",
                pattern: "blog/{*article}",
                defaults: new { controller = "Blog", action = "Article" });
app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

Маршрут blog в предыдущем коде — это выделенный обычный маршрут. Это специальный обычный маршрут, так как:

• Он использует обычную маршрутизацию.
• Он посвящен определенному действию.

Так как шаблон "blog/{*article}" маршрута не включает controller и action в качестве параметров:

• Они могут иметь только значения { controller = "Blog", action = "Article" }по умолчанию.
• Этот маршрут всегда сопоставляется с действием BlogController.Article.

/Blog, /Blog/Articleи /Blog/{any-string} являются единственными URL-путями, которые соответствуют маршруту блога.

В предыдущем примере:

• Маршрут blog имеет более высокий приоритет при сопоставлении, чем маршрут default, поскольку вы добавляете его первым.
• Это пример маршрутизации в стиле Slug, где в URL-адрес обычно включается название статьи.

Warning

В ASP.NET Core маршрутизация не делает следующее.

• Определите концепцию, называемую маршрутом. UseRouting добавляет соответствие маршрута в конвейер ПО промежуточного слоя. ПО UseRouting промежуточного слоя проверяет набор конечных точек, определенных в приложении, и выбирает наилучшее соответствие конечной точки на основе запроса.
• Предоставьте гарантии относительно порядка выполнения механизмов расширения, таких как IRouteConstraint или IActionConstraint.

См. Маршрутизация в справочных материалах по маршрутизации.

Обычный порядок маршрутизации

Обычная маршрутизация соответствует только сочетанию действий и контроллеров, которые определяет приложение. Этот подход упрощает случаи, когда обычные маршруты перекрываются. При добавлении маршрутов с помощью MapControllerRoute, MapDefaultControllerRoute и MapAreaControllerRoute конечные точки автоматически получают значение порядка в зависимости от того, в каком порядке вызываются эти методы. Совпадения из маршрута, который отображается ранее в списке, имеют более высокий приоритет. Обычная маршрутизация зависит от порядка. Как правило, поместите маршруты с областями ранее, потому что они более конкретные, чем маршруты без области. Выделенные обычные маршруты с параметрами маршрута catch-all, например {*article}, могут сделать маршрут слишком жадным. Жадный маршрут соответствует URL-адресам, которые должны соответствовать другим маршрутам. Поместите жадные маршруты позже в таблицу маршрутов, чтобы избежать жадных совпадений.

Разрешение неоднозначных действий

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

• Выберите лучшего кандидата.
• Создание исключения.

Рассмотрим пример.

public class Products33Controller : Controller
{
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [HttpPost]
    public IActionResult Edit(int id, Product product)
    {
        return ControllerContext.MyDisplayRouteInfo(id, product.name);
    }
}

Предыдущий контроллер определяет два действия, которые соответствуют следующим:

• Путь URL /Products33/Edit/17
• Маршрутизировать данные { controller = Products33, action = Edit, id = 17 }.

Это типичный шаблон для контроллеров MVC:

• Edit(int) отображает форму для изменения продукта.
• Edit(int, Product) обрабатывает размещенную форму.

Чтобы установить правильный маршрут, выполните следующие действия.

• Edit(int, Product) выбирается, когда запрос является HTTP POST.
• Edit(int) выбирается, если http-команда — это что-либо другое. Edit(int) обычно вызывается через GET.

Параметр HttpPostAttribute, [HttpPost]предоставляется для маршрутизации, чтобы он смог выбрать в зависимости от метода HTTP запроса. HttpPostAttribute делает Edit(int, Product) более подходящим вариантом, чем Edit(int).

Важно понимать роль атрибутов, таких как HttpPostAttribute. Аналогичные атрибуты определяются для других http-команд. При традиционной маршрутизации действия часто используют одно и то же имя действия, если они являются частью процесса отображения и отправки формы. Например, ознакомьтесь с двумя методами действия "Изменить".

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

Обычные имена маршрутов

Строки "blog" и "default" в следующих примерах являются условными именами маршрутов:

app.MapControllerRoute(name: "blog",
                pattern: "blog/{*article}",
                defaults: new { controller = "Blog", action = "Article" });
app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

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

Имена маршрутов:

• Не влияет на сопоставление URL-адресов или обработку запросов.
• Используются только для создания URL-адресов.

Концепция имени маршрута представлена в маршрутизации как IEndpointNameMetadata. Термины имя маршрута и имя конечной точки:

• Взаимозаменяемы.
• Какой из них используется в документации и коде, зависит от описанного API.

Маршрутизация атрибутов для REST API

RESTAPI должны использовать маршрутизацию атрибутов для моделирования функциональных возможностей приложения в виде набора ресурсов, в которых операции представлены http-командами.

При маршрутизации с помощью атрибутов используется набор атрибутов для сопоставления действий непосредственно с шаблонами маршрутов. Следующий код типичен для API REST и используется в следующем примере:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

В приведенном выше коде вы вызываете MapControllers, чтобы сопоставить контроллеры с маршрутизацией на основе атрибутов.

В следующем примере :

• HomeController соответствует набору URL-адресов, аналогичных тому, что соответствует стандартному маршруту {controller=Home}/{action=Index}/{id?} по умолчанию.

public class HomeController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult Index(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult About(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Действие HomeController.Index выполняется для любого из путей URL-адресов/, /Home/Home/Indexили/Home/Index/3.

В этом примере выделена ключевая разница в программировании между маршрутизацией атрибутов и обычной маршрутизацией. Для маршрутизации атрибутов требуется больше входных данных для указания маршрута. Стандартный маршрут по умолчанию обрабатывает маршруты более сжато. Однако маршрутизация атрибутов позволяет и требует точного управления шаблонами маршрутов, применяемыми к каждому действию.

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

public class MyDemoController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult MyIndex(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult MyAbout(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Следующий код использует замену маркеров для action и controller:

public class HomeController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("[controller]/[action]")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [Route("[controller]/[action]")]
    public IActionResult About()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Следующий код применяет [Route("[controller]/[action]")] к контроллеру:

[Route("[controller]/[action]")]
public class HomeController : Controller
{
    [Route("~/")]
    [Route("/Home")]
    [Route("~/Home/Index")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    public IActionResult About()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

В приведённом выше коде шаблоны методов Index должны добавлять префикс / или ~/ к шаблонам маршрутов. Шаблоны маршрутов, применяемые к действию, которое начинается с символа / или ~/, не объединяются с шаблонами маршрутов, применяемыми к контроллеру.

Дополнительные сведения о выборе шаблона маршрута см. в разделе "Приоритет шаблона маршрута".

Зарезервированные имена маршрутизации

Следующие ключевые слова являются зарезервированными именами параметров маршрута при использовании объектов Controller или Razor Pages:

• action
• area
• controller
• handler
• page

Использование page в качестве параметра маршрута с маршрутизацией атрибутов является распространенной ошибкой. Этот выбор приводит к несогласованности и запутанности поведения с созданием URL-адресов.

public class MyDemo2Controller : Controller
{
    [Route("/articles/{page}")]
    public IActionResult ListArticles(int page)
    {
        return ControllerContext.MyDisplayRouteInfo(page);
    }
}

Создание URL-адресов использует эти специальные имена параметров, чтобы определить, относится ли операция создания URL-адресов к Razor странице или контроллеру.

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

• page
• using
• namespace
• inject
• section
• inherits
• model
• addTagHelper
• removeTagHelper

Не используйте эти ключевые слова для генерации ссылок, параметров, связанных с моделью, или свойств верхнего уровня.

Шаблоны глаголов HTTP

ASP.NET Core включает следующие шаблоны глаголов HTTP:

• [HttpGet]
• [HttpPost]
• [HttpPut]
• [HttpDelete]
• [HttpHead]
• [HttpPatch]

Шаблоны маршрутов

ASP.NET Core включает следующие шаблоны маршрутов:

• Все шаблоны команд HTTP — это шаблоны маршрутов.
• [Route]

Маршрутизация атрибутов с атрибутами HTTP-команд

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

[Route("api/[controller]")]
[ApiController]
public class Test2Controller : ControllerBase
{
    [HttpGet]   // GET /api/test2
    public IActionResult ListProducts()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("{id}")]   // GET /api/test2/xyz
    public IActionResult GetProduct(string id)
    {
       return ControllerContext.MyDisplayRouteInfo(id);
    }

    [HttpGet("int/{id:int}")] // GET /api/test2/int/3
    public IActionResult GetIntProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [HttpGet("int2/{id}")]  // GET /api/test2/int2/3
    public IActionResult GetInt2Product(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

В предыдущем коде:

• Каждое действие содержит [HttpGet] атрибут, который ограничивает соответствие только HTTP-запросам GET.
• Действие GetProduct включает "{id}" шаблон, поэтому id добавляется к "api/[controller]" шаблону на контроллере. Шаблон метода — "api/[controller]/{id}". Поэтому это действие соответствует только запросам GET для формы /api/test2/xyz, /api/test2/123и /api/test2/{any string}т. д.

  [HttpGet("{id}")]   // GET /api/test2/xyz
  public IActionResult GetProduct(string id)
  {
     return ControllerContext.MyDisplayRouteInfo(id);
  }
  

• Действие GetIntProduct содержит шаблон "int/{id:int}". Часть :int шаблона ограничивает id значения маршрута строками, которые можно преобразовать в целое число. GET-запрос к /api/test2/int/abc:
  • Не соответствует этому действию.
  • Возвращает ошибку 404 Not Found .

    [HttpGet("int/{id:int}")] // GET /api/test2/int/3
    public IActionResult GetIntProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
    

• Действие GetInt2Product содержит {id} в шаблоне, но не ограничивает id значениями, которые можно преобразовать в целое число. GET-запрос к /api/test2/int2/abc:
  • Соответствует этому маршруту.
  • Привязка модели не может преобразовывать abc в целое число. Параметр id метода является целым числом.
  • Возвращает ошибку 400 Bad Request, поскольку при привязке модели не удалось преобразовать abc в целое число.

    [HttpGet("int2/{id}")]  // GET /api/test2/int2/3
    public IActionResult GetInt2Product(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
    

При маршрутизации на основе атрибутов можно использовать такие атрибуты, как HttpMethodAttributeHttpPostAttribute, HttpPutAttribute и HttpDeleteAttribute. Все атрибуты команды HTTP принимают шаблон маршрута. В следующем примере показаны два действия, которые соответствуют одному шаблону маршрута:

[ApiController]
public class MyProductsController : ControllerBase
{
    [HttpGet("/products3")]
    public IActionResult ListProducts()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpPost("/products3")]
    public IActionResult CreateProduct(MyProduct myProduct)
    {
        return ControllerContext.MyDisplayRouteInfo(myProduct.Name);
    }
}

Используя путь URL /products3:

• Действие MyProductsController.ListProducts выполняется, когда HTTP-метод — GET.
• Действие MyProductsController.CreateProduct выполняется, когда HTTP-метод — POST.

При создании REST API редко необходимо использовать [Route(...)] для метода действия, так как действие принимает все методы HTTP. Используйте более конкретный атрибут http-команды , чтобы точно определить, что поддерживает API. REST Ожидается, что клиенты API-интерфейсов будут знать, какие пути и HTTP-команды сопоставляются с конкретными логическими операциями.

REST API должны использовать маршрутизацию атрибутов для моделирования функциональных возможностей приложения в виде набора ресурсов, в которых операции представлены http-командами. Это означает, что многие операции, такие как GET и POST в одном логическом ресурсе, используют один и тот же URL-адрес. Маршрутизация атрибутов обеспечивает уровень управления, необходимый для тщательного проектирования макета общедоступной конечной точки API.

Так как маршрут на основе атрибутов применяется к определенному действию, можно легко сделать параметры обязательными в рамках определения шаблона маршрута. В следующем примере id требуется в качестве части пути URL-адреса:

[ApiController]
public class Products2ApiController : ControllerBase
{
    [HttpGet("/products2/{id}", Name = "Products_List")]
    public IActionResult GetProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Действие Products2ApiController.GetProduct(int) :

• Запускается с путем URL, например, /products2/3
• Не запускается с путем URL /products2.

Атрибут [Consumes] позволяет выполнять действие для ограничения поддерживаемых типов содержимого запросов. Дополнительные сведения см. в разделе «Определение поддерживаемых типов содержимого запроса с помощью атрибута Consumes».

Полное описание шаблонов маршрутов и связанных параметров см. в статье Маршрутизация.

Дополнительные сведения о [ApiController]см. в статье Атрибут ApiController.

Имя маршрута

Следующий код определяет имя Products_Listмаршрута:

[ApiController]
public class Products2ApiController : ControllerBase
{
    [HttpGet("/products2/{id}", Name = "Products_List")]
    public IActionResult GetProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Используйте имена маршрутов для создания URL-адреса на основе определенного маршрута. Имена маршрутов:

• Не влияет на поведение маршрутизации по URL-адресу.
• Используются только для создания URL-адресов.

Имена маршрутов должны быть уникальными в пределах приложения.

Контрастирует предыдущий код с обычным маршрутом по умолчанию, который определяет id параметр как необязательный ({id?}). Возможность точно определять API дает такие преимущества, как возможность направлять /products и /products/5 к разным действиям.

Объединение маршрутов атрибутов

Чтобы сделать маршрутизацию атрибутов менее повторяющейся, объедините атрибуты маршрута на контроллере с атрибутами маршрута для отдельных действий. Шаблоны маршрутов, определенные на контроллере, предопределяются для маршрутизации шаблонов действий. При размещении атрибута маршрута на контроллере все действия в контроллере используют маршрутизацию атрибутов.

[ApiController]
[Route("products")]
public class ProductsApiController : ControllerBase
{
    [HttpGet]
    public IActionResult ListProducts()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("{id}")]
    public IActionResult GetProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

В предыдущем примере:

• Путь URL-адреса /products может совпадать ProductsApi.ListProducts
• Путь URL-адреса /products/5 может совпадать ProductsApi.GetProduct(int).

Оба этих действия соответствуют только HTTP GET , так как они помечены атрибутом [HttpGet] .

Шаблоны маршрутов, применяемые к методу действия и начинающиеся с / или ~/, не объединяются с шаблонами маршрутов, применяемыми к контроллеру. Следующий пример соответствует набору путей URL-адресов, аналогичных маршруту по умолчанию.

[Route("Home")]
public class HomeController : Controller
{
    [Route("")]
    [Route("Index")]
    [Route("/")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [Route("About")]
    public IActionResult About()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

В следующей таблице описаны [Route] атрибуты в приведенном выше коде.

Attribute	Сочетается с [Route("Home")]	Определяет шаблон маршрута
[Route("")]	Yes	"Home"
[Route("Index")]	Yes	"Home/Index"
[Route("/")]	Нет	""
[Route("About")]	Yes	"Home/About"

Порядок атрибутивной маршрутизации

Маршрутизация создает дерево и сопоставляет все конечные точки одновременно:

• Записи маршрута ведут себя так, как будто они помещаются в идеальном порядке.
• Более конкретные маршруты имеют шанс выполниться раньше, чем более общие маршруты.

Например, маршрут атрибута, такой как blog/search/{topic}, является более конкретным, чем маршрут атрибута, такой как blog/{*article}. По blog/search/{topic} умолчанию маршрут имеет более высокий приоритет, так как он более конкретный. Используя обычную маршрутизацию, разработчик отвечает за размещение маршрутов в нужном порядке.

Для маршрутов, заданных атрибутами, можно задать порядок с помощью свойства Order. Все атрибуты маршрута, предоставляемые платформой, включают Order . Маршруты обрабатываются в порядке возрастания значения свойства Order. Порядок по умолчанию — 0. Маршрут, для которого задан Order = -1, обрабатывается раньше маршрутов, для которых порядок не задан. Настройка маршрута с помощью Order = 1 выполняется после стандартного упорядочивания маршрутов.

Не полагайтесь на Order. Если пространство URL-адресов приложения требует для корректной маршрутизации явного порядка значений, то, вероятно, это запутает клиентов. Как правило, маршрутизация атрибутов выбирает правильный маршрут с сопоставлением URL-адресов. Если порядок по умолчанию, используемый для создания URL-адресов, не работает, использование имени маршрута в качестве переопределения обычно проще, чем применение Order свойства.

Рассмотрим следующие два контроллера, которые оба определяют маршрут, соответствующий /home:

public class HomeController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult Index(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult About(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

public class MyDemoController : Controller
{
    [Route("")]
    [Route("Home")]
    [Route("Home/Index")]
    [Route("Home/Index/{id?}")]
    public IActionResult MyIndex(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }

    [Route("Home/About")]
    [Route("Home/About/{id?}")]
    public IActionResult MyAbout(int? id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Запрос /home с помощью предыдущего кода вызывает исключение, аналогичное следующему:

AmbiguousMatchException: The request matched multiple endpoints. Matches:

 WebMvcRouting.Controllers.HomeController.Index
 WebMvcRouting.Controllers.MyDemoController.MyIndex

Добавление Order к одному из атрибутов маршрута разрешает неоднозначность:

[Route("")]
[Route("Home", Order = 2)]
[Route("Home/MyIndex")]
public IActionResult MyIndex()
{
    return ControllerContext.MyDisplayRouteInfo();
}

В приведенном выше коде /home запускает конечную точку HomeController.Index. Чтобы перейти к MyDemoController.MyIndex, запросите /home/MyIndex. Примечание.

• Приведенный выше код является примером плохой структуры маршрутизации. Иллюстрирует свойство Order.
• Свойство Order разрешает только неоднозначность. Этот шаблон не может быть сопоставлен. Лучше удалить [Route("Home")] шаблон.

Сведения о порядке маршрутов при использовании Razor Pages см. в разделе Razor«Соглашения Pages для маршрутов и приложений: порядок маршрутов».

В некоторых случаях ошибка HTTP 500 возвращается с неоднозначными маршрутами. Используйте ведение журнала , чтобы узнать, какие конечные точки вызвали AmbiguousMatchException.

Замена токенов в шаблонах маршрутов [controller], [action], [area]

Для удобства маршруты на основе атрибутов поддерживают замену токенов, если заключить токен в квадратные скобки ([, ]). Маркеры [action][area]и [controller] заменяются значениями имени действия, имени области и имени контроллера из действия, в котором определяется маршрут:

[Route("[controller]/[action]")]
public class Products0Controller : Controller
{
    [HttpGet]
    public IActionResult List()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }


    [HttpGet("{id}")]
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

В предыдущем коде:

[HttpGet]
public IActionResult List()
{
    return ControllerContext.MyDisplayRouteInfo();
}

• Совпадения /Products0/List

[HttpGet("{id}")]
public IActionResult Edit(int id)
{
    return ControllerContext.MyDisplayRouteInfo(id);
}

• Совпадения /Products0/Edit/{id}

Замена маркеров происходит в качестве последнего шага построения маршрутов атрибутов. В предыдущем примере выполняется то же самое, что и следующий код:

public class Products20Controller : Controller
{
    [HttpGet("[controller]/[action]")]  // Matches '/Products20/List'
    public IActionResult List()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("[controller]/[action]/{id}")]   // Matches '/Products20/Edit/{id}'
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Если вы читаете это на языке, отличном от английского, сообщите нам об этом в данном вопросе для обсуждения на GitHub, если хотите видеть комментарии кода на своем языке.

Кроме того, можно объединить атрибутивные маршруты с наследованием. Эта комбинация мощна при использовании замены токенов. Замена токенов также применяется к именам маршрутов, определенным в атрибутных маршрутах. [Route("[controller]/[action]", Name="[controller]_[action]")]создает уникальное имя маршрута для каждого действия:

[ApiController]
[Route("api/[controller]/[action]", Name = "[controller]_[action]")]
public abstract class MyBase2Controller : ControllerBase
{
}

public class Products11Controller : MyBase2Controller
{
    [HttpGet]                      // /api/products11/list
    public IActionResult List()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

    [HttpGet("{id}")]             //    /api/products11/edit/3
    public IActionResult Edit(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

Чтобы сопоставить буквальный разделитель замены токенов [ или ], экранируйте его, повторив символ ([[ или ]]).

Использование преобразователя параметров для настройки замены токенов

Вы можете настроить замену маркеров с помощью преобразователя параметров. Преобразователь параметров реализует IOutboundParameterTransformer и преобразует значения параметров. Например, пользовательский SlugifyParameterTransformer преобразователь параметров изменяет значение маршрута SubscriptionManagement на subscription-management:

using System.Text.RegularExpressions;

public class SlugifyParameterTransformer : IOutboundParameterTransformer
{
    public string? TransformOutbound(object? value)
    {
        if (value == null) { return null; }

        return Regex.Replace(value.ToString()!,
                             "([a-z])([A-Z])",
                             "$1-$2",
                             RegexOptions.CultureInvariant,
                             TimeSpan.FromMilliseconds(100)).ToLowerInvariant();
    }
}

RouteTokenTransformerConvention является соглашением для модели приложения, которое:

• Примените преобразователь параметров ко всем маршрутам атрибутов в приложении.
• Настраивает значения токена маршрутизации атрибута в процессе их замены.

public class SubscriptionManagementController : Controller
{
    [HttpGet("[controller]/[action]")]
    public IActionResult ListAll()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Предыдущий ListAll метод совпадает с /subscription-management/list-all.

RouteTokenTransformerConvention зарегистрирован как параметр:

using Microsoft.AspNetCore.Mvc.ApplicationModels;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews(options =>
{
    options.Conventions.Add(new RouteTokenTransformerConvention(
                                 new SlugifyParameterTransformer()));
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Определение slug см. в веб-документации MDN в Slug.

Warning

При использовании System.Text.RegularExpressions для обработки ненадежных входных данных передайте время ожидания. Злонамеренный пользователь может предоставить входные данные для RegularExpressions, что делает возможными атаки типа "отказ в обслуживании". API платформы ASP.NET Core, которые используют RegularExpressions, передают таймаут.

Несколько атрибутивных маршрутов

Маршрутизация с помощью атрибутов поддерживает определение нескольких маршрутов к одному и тому же действию. Наиболее распространенный способ использования этого — имитация поведения маршрута по умолчанию, как показано в следующем примере:

[Route("[controller]")]
public class Products13Controller : Controller
{
    [Route("")]     // Matches 'Products13'
    [Route("Index")] // Matches 'Products13/Index'
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

Размещение нескольких атрибутов маршрута на контроллере означает, что каждая из них объединяется с каждым из атрибутов маршрута в методах действия:

[Route("Store")]
[Route("[controller]")]
public class Products6Controller : Controller
{
    [HttpPost("Buy")]       // Matches 'Products6/Buy' and 'Store/Buy'
    [HttpPost("Checkout")]  // Matches 'Products6/Checkout' and 'Store/Checkout'
    public IActionResult Buy()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Все ограничения маршрута для HTTP-метода реализуют IActionConstraint.

Если к действию применяется несколько атрибутов маршрута, реализующих IActionConstraint:

• Каждое ограничение действия объединяется с шаблоном маршрута, примененным к контроллеру.

[Route("api/[controller]")]
public class Products7Controller : ControllerBase
{
    [HttpPut("Buy")]        // Matches PUT 'api/Products7/Buy'
    [HttpPost("Checkout")]  // Matches POST 'api/Products7/Checkout'
    public IActionResult Buy()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Использование нескольких маршрутов для действий может показаться полезным и мощным, лучше сохранить пространство URL-адресов вашего приложения базовым и хорошо определенным. Используйте несколько маршрутов для действий только там, где это необходимо, например, для поддержки существующих клиентов.

Задание необязательных параметров, значений по умолчанию и ограничений для маршрутов на основе атрибутов

Маршруты на основе атрибутов поддерживают тот же встроенный синтаксис, что и маршруты на основе соглашений, для указания необязательных параметров, значений по умолчанию и ограничений.

public class Products14Controller : Controller
{
    [HttpPost("product14/{id:int}")]
    public IActionResult ShowProduct(int id)
    {
        return ControllerContext.MyDisplayRouteInfo(id);
    }
}

В приведенном выше коде [HttpPost("product14/{id:int}")] применяется ограничение маршрута. Действие Products14Controller.ShowProduct сопоставляется только с путями URL, такими как /product14/3. Часть шаблона маршрута ограничивает сегмент {id:int} только целыми числами.

Подробное описание синтаксиса шаблона маршрута см. в справочнике по шаблону маршрута.

Настраиваемые атрибуты маршрута с помощью IRouteTemplateProvider

Все атрибуты маршрута реализуютIRouteTemplateProvider. Среда выполнения ASP.NET Core:

• Ищет атрибуты для классов контроллеров и методов действий при запуске приложения.
• Использует атрибуты, реализующие IRouteTemplateProvider для создания начального набора маршрутов.

Реализуйте IRouteTemplateProvider, чтобы определить пользовательские атрибуты маршрута. Каждый IRouteTemplateProvider позволяет задать один маршрут с настраиваемым шаблоном маршрута, порядком и именем:

public class MyApiControllerAttribute : Attribute, IRouteTemplateProvider
{
    public string Template => "api/[controller]";
    public int? Order => 2;
    public string Name { get; set; } = string.Empty;
}

[MyApiController]
[ApiController]
public class MyTestApiController : ControllerBase
{
    // GET /api/MyTestApi
    [HttpGet]
    public IActionResult Get()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Get Предыдущий метод возвращаетOrder = 2, Template = api/MyTestApi.

Использование модели приложения для настройки маршрутов атрибутов

Модель приложения:

• Это объектная модель, созданная при запуске в Program.cs.
• Содержит все метаданные, используемые ASP.NET Core для маршрутизации и выполнения действий в приложении.

Модель приложения включает все данные, собранные из атрибутов маршрута. Данные из атрибутов маршрута предоставляются реализацией IRouteTemplateProvider. Conventions:

• Может быть написан код для изменения модели приложения и настройки поведения маршрутизации.
• Считываются при запуске приложения.

В этом разделе показан базовый пример настройки маршрутизации с помощью модели приложения. Следующий код создает маршруты примерно в соответствии со структурой папок проекта.

public class NamespaceRoutingConvention : Attribute, IControllerModelConvention
{
    private readonly string _baseNamespace;

    public NamespaceRoutingConvention(string baseNamespace)
    {
        _baseNamespace = baseNamespace;
    }

    public void Apply(ControllerModel controller)
    {
        var hasRouteAttributes = controller.Selectors.Any(selector =>
                                                selector.AttributeRouteModel != null);
        if (hasRouteAttributes)
        {
            return;
        }

        var namespc = controller.ControllerType.Namespace;
        if (namespc == null)
            return;
        var template = new StringBuilder();
        template.Append(namespc, _baseNamespace.Length + 1,
                        namespc.Length - _baseNamespace.Length - 1);
        template.Replace('.', '/');
        template.Append("/[controller]/[action]/{id?}");

        foreach (var selector in controller.Selectors)
        {
            selector.AttributeRouteModel = new AttributeRouteModel()
            {
                Template = template.ToString()
            };
        }
    }
}

Следующий код предотвращает применение соглашения namespace к контроллерам, использующим маршрутизацию на основе атрибутов:

public void Apply(ControllerModel controller)
{
    var hasRouteAttributes = controller.Selectors.Any(selector =>
                                            selector.AttributeRouteModel != null);
    if (hasRouteAttributes)
    {
        return;
    }

Например, следующий контроллер не использует NamespaceRoutingConvention:

[Route("[controller]/[action]/{id?}")]
public class ManagersController : Controller
{
    // /managers/index
    public IActionResult Index()
    {
        var template = ControllerContext.ActionDescriptor.AttributeRouteInfo?.Template;
        return Content($"Index- template:{template}");
    }

    public IActionResult List(int? id)
    {
        var path = Request.Path.Value;
        return Content($"List- Path:{path}");
    }
}

Метод NamespaceRoutingConvention.Apply:

• Не делает ничего, если контроллер маршрутизирован с использованием атрибутов.
• Задает шаблон контроллеров на основе namespace, удаляя базовый namespace.

NamespaceRoutingConvention можно применять в Program.cs:

using My.Application.Controllers;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews(options =>
{
    options.Conventions.Add(
     new NamespaceRoutingConvention(typeof(HomeController).Namespace!));
});

var app = builder.Build();

Например, рассмотрим следующий контроллер:

using Microsoft.AspNetCore.Mvc;

namespace My.Application.Admin.Controllers
{
    public class UsersController : Controller
    {
        // GET /admin/controllers/users/index
        public IActionResult Index()
        {
            var fullname = typeof(UsersController).FullName;
            var template = 
                ControllerContext.ActionDescriptor.AttributeRouteInfo?.Template;
            var path = Request.Path.Value;

            return Content($"Path: {path} fullname: {fullname}  template:{template}");
        }

        public IActionResult List(int? id)
        {
            var path = Request.Path.Value;
            return Content($"Path: {path} ID:{id}");
        }
    }
}

В предыдущем коде:

• База namespace — это My.Application.
• Полное имя предыдущего контроллера My.Application.Admin.Controllers.UsersController.
• NamespaceRoutingConvention задает шаблон контроллеров как Admin/Controllers/Users/[action]/{id?.

Его NamespaceRoutingConvention также можно применить в качестве атрибута на контроллере:

[NamespaceRoutingConvention("My.Application")]
public class TestController : Controller
{
    // /admin/controllers/test/index
    public IActionResult Index()
    {
        var template = ControllerContext.ActionDescriptor.AttributeRouteInfo?.Template;
        var actionname = ControllerContext.ActionDescriptor.ActionName;
        return Content($"Action- {actionname} template:{template}");
    }

    public IActionResult List(int? id)
    {
        var path = Request.Path.Value;
        return Content($"List- Path:{path}");
    }
}

Смешанная маршрутизация: маршрутизация атрибутов против традиционной маршрутизации

ASP.NET Core приложения могут использовать обычную маршрутизацию и маршрутизацию атрибутов. Как правило, вы используете обычные маршруты для контроллеров, обслуживающих HTML-страницы в браузерах, и маршрутизацию атрибутов для контроллеров, обслуживающих REST API.

Действия маршрутизируются либо по стандартным маршрутам, либо с использованием атрибутов. Когда маршрут размещается на контроллере или действии, он становится маршрутизированным через атрибут. Вы не можете достичь действий, определяющих маршруты атрибутов через обычные маршруты, и наоборот. Любой атрибут маршрута на контроллере выполняет все действия в перенаправленном атрибуте контроллера.

Маршрутизация атрибутов и обычная маршрутизация используют тот же механизм маршрутизации.

Маршрутизация с особыми символами

Маршрутизация со специальными символами может привести к непредвиденным результатам. Например, рассмотрим контроллер со следующим методом действия:

[HttpGet("{id?}/name")]
public async Task<ActionResult<string>> GetName(string id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null || todoItem.Name == null)
    {
        return NotFound();
    }

    return todoItem.Name;
}

Если string id содержит следующие закодированные значения, могут возникнуть непредвиденные результаты:

ASCII	Encoded
/	%2F
	+

Параметры маршрута не всегда декодируются из URL. Эта проблема может быть решена в будущем. Дополнительные сведения см. в этом выпуске GitHub;

Создание URL-адресов и окружающих значений

Приложения могут использовать функции генерации URL-адресов маршрутизации для создания URL-ссылок к действиям. Генерация URL-адресов исключает жестко заданные URL-адреса, делая код более надежным и удобным для сопровождения. В этом разделе рассматриваются функции создания URL-адресов, предоставляемые MVC, и рассматриваются только основные сведения о том, как работает создание URL-адресов. Подробное описание формирования URL-адреса см. в статье Маршрутизация.

Интерфейс IUrlHelper — это базовый элемент инфраструктуры между MVC и маршрутизацией для создания URL-адресов. Экземпляр класса IUrlHelper доступен через свойство Url в контроллерах, представлениях и компонентах представлений.

В следующем примере интерфейс IUrlHelper используется с помощью свойства Controller.Url для создания URL-адреса другого действия.

public class UrlGenerationController : Controller
{
    public IActionResult Source()
    {
        // Generates /UrlGeneration/Destination
        var url = Url.Action("Destination");
        return ControllerContext.MyDisplayRouteInfo("", $" URL = {url}");
    }

    public IActionResult Destination()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }
}

Если приложение использует обычный маршрут по умолчанию, значением переменной url является строка пути URL /UrlGeneration/Destination. Маршрутизация создает этот путь URL-адреса, объединяя:

• Значения маршрута из текущего запроса, которые называются внешними значениями.
• Значения, передаваемые в Url.Action, и подстановка этих значений в шаблон маршрута:

ambient values: { controller = "UrlGeneration", action = "Source" }
values passed to Url.Action: { controller = "UrlGeneration", action = "Destination" }
route template: {controller}/{action}/{id?}

result: /UrlGeneration/Destination

Значение каждого параметра маршрута в шаблоне маршрута заменяется соответствующими именами с основными значениями и фоновыми значениями. Параметр маршрута, который не имеет значения, может:

• Используйте значение по умолчанию, если оно имеет одно.
• Можно пропустить, если это необязательно. Например, id из шаблона маршрута {controller}/{action}/{id?}.

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

В предыдущем примере Url.Action предполагается обычная маршрутизация. Создание URL-адресов работает аналогично с маршрутизацией атрибутов, хотя основные понятия отличаются. С обычной маршрутизацией:

• Значения маршрута используются для расширения шаблона.
• Значения маршрута для controller и action обычно отображаются в этом шаблоне. Это работает, так как URL-адреса, соответствующие маршрутизации, соответствуют соглашению.

В следующем примере используется маршрутизация атрибутов:

public class UrlGenerationAttrController : Controller
{
    [HttpGet("custom")]
    public IActionResult Source()
    {
        var url = Url.Action("Destination");
        return ControllerContext.MyDisplayRouteInfo("", $" URL = {url}");
    }

    [HttpGet("custom/url/to/destination")]
    public IActionResult Destination()
    {
       return ControllerContext.MyDisplayRouteInfo();
    }
}

Действие Source в предыдущем фрагменте кода создает custom/url/to/destination.

LinkGenerator добавлен в ASP.NET Core 3.0 в качестве альтернативы IUrlHelper. LinkGenerator предлагает аналогичные, но более гибкие функциональные возможности. Каждый метод IUrlHelper также имеет соответствующее семейство методов LinkGenerator .

Формирование URL-адресов по имени действия

Url.Action, LinkGenerator.GetPathByAction и все связанные перегрузки предназначены для создания целевой конечной точки, указав имя контроллера и имя действия.

При использовании Url.Action среда выполнения предоставляет текущие значения маршрута для controller и action:

• Значения controller и action входят как в контекстные значения, так и в значения. Метод Url.Action всегда использует текущие значения action и controller создает путь URL-адреса, который направляется к текущему действию.

Маршрутизация пытается использовать значения во внешних значениях для заполнения сведений, которые не были предоставлены при создании URL-адреса. Рассмотрим такой маршрут, как {a}/{b}/{c}/{d}, с контекстными значениями { a = Alice, b = Bob, c = Carol, d = David }:

• Маршрутизация имеет достаточно сведений, чтобы создать URL-адрес без дополнительных значений.
• Маршрутизация имеет достаточно сведений, так как все параметры маршрута имеют значение.

Если добавляется значение { d = Donovan } :

• Значение { d = David } игнорируется.
• Сгенерированный путь URL: Alice/Bob/Carol/Donovan.

Предупреждение: пути URL-адреса являются иерархическими. В предыдущем примере, если значение { c = Cheryl } добавляется:

• Оба значения { c = Carol, d = David } игнорируются.
• Для d больше нет значения, и создание URL-адреса завершается сбоем.
• Необходимо указать требуемые значения c и d создать URL-адрес.

Можно ожидать, что вы столкнетесь с этой проблемой при использовании маршрута {controller}/{action}/{id?} по умолчанию. Эта проблема является редкой в практике, так как Url.Action всегда явно указывает controller и action значение.

Несколько перегрузок Url.Action принимают объект значений маршрута, чтобы предоставить значения для параметров маршрута, отличных от controller иaction. Объект со значениями маршрута часто используется с id. Например: Url.Action("Buy", "Products", new { id = 17 }). Объект значений маршрута:

• По соглашению обычно является объектом анонимного типа.
• Может быть либо IDictionary<>, либо POCO).

Любые дополнительные значения маршрутов, которые не соответствуют параметрам маршрута, идут в строке запроса.

public IActionResult Index()
{
    var url = Url.Action("Buy", "Products", new { id = 17, color = "red" });
    return Content(url!);
}

Предыдущий код создает /Products/Buy/17?color=red.

Следующий код создает абсолютный URL-адрес:

public IActionResult Index2()
{
    var url = Url.Action("Buy", "Products", new { id = 17 }, protocol: Request.Scheme);
    // Returns https://localhost:5001/Products/Buy/17
    return Content(url!);
}

Чтобы создать абсолютный URL-адрес, используйте один из следующих параметров:

• Перегрузка, принимаюющая объект protocol. Например, предыдущий код.
• LinkGenerator.GetUriByAction, который создает абсолютные URI по умолчанию.

Создание URL-адресов по маршруту

Приведенный выше код демонстрирует создание URL-адреса путем передачи имени контроллера и действия. IUrlHelper также предоставляет семейство методов Url.RouteUrl . Эти методы похожи на Url.Action, но они не копируют текущие значения action и controller в параметры маршрута. Наиболее распространенное использование Url.RouteUrl:

• Указывает имя маршрута для создания URL-адреса.
• Как правило, не указывает имя контроллера или действия.

public class UrlGeneration2Controller : Controller
{
    [HttpGet("")]
    public IActionResult Source()
    {
        var url = Url.RouteUrl("Destination_Route");
        return ControllerContext.MyDisplayRouteInfo("", $" URL = {url}");
    }

    [HttpGet("custom/url/to/destination2", Name = "Destination_Route")]
    public IActionResult Destination()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

Razor Следующий файл создает HTML-ссылку на Destination_Route:

<h1>Test Links</h1>

<ul>
    <li><a href="@Url.RouteUrl("Destination_Route")">Test Destination_Route</a></li>
</ul>

Создание URL-адресов в HTML и Razor

IHtmlHelper HtmlHelper предоставляет методы Html.BeginForm и Html.ActionLink для создания <form> и <a> элементов соответственно. Эти методы используют метод Url.Action для создания URL-адреса и принимают аналогичные аргументы. Эквивалентами методов Url.RouteUrl для HtmlHelper являются методы Html.BeginRouteForm и Html.RouteLink, которые имеют схожие функции.

Вспомогательные классы тегов создают URL-адреса с помощью TagHelper form и TagHelper <a>. Обе они реализуются с помощью интерфейса IUrlHelper. Дополнительные сведения см. в разделе "Вспомогательные функции тегов" в формах.

Внутри представлений IUrlHelper доступен через свойство Url для специальной генерации URL-адресов в случаях, не предусмотренных предыдущими методами.

Генерация URL-адресов в результатах выполнения

В предыдущих примерах показано, как использовать IUrlHelper в контроллере. Наиболее распространенное использование в контроллере — создание URL-адреса в рамках результата действия.

Базовые классы ControllerBase и Controller предоставляют удобные методы для результатов действий, ссылающихся на другое действие. Одно из типичных способов использования — перенаправление после принятия входных данных пользователем:

[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Edit(int id, Customer customer)
{
    if (ModelState.IsValid)
    {
        // Update DB with new details.
        ViewData["Message"] = $"Successful edit of customer {id}";
        return RedirectToAction("Index");
    }
    return View(customer);
}

Методы фабрики результатов действий, такие как RedirectToAction и CreatedAtAction, следуют тому же шаблону, что и методы в IUrlHelper.

Особый случай для выделенных стандартных маршрутов

Обычная маршрутизация может использовать специальное определение маршрута, называемое выделенным обычным маршрутом. В следующем примере маршрут с именем blog является отдельным традиционным маршрутом:

app.MapControllerRoute(name: "blog",
                pattern: "blog/{*article}",
                defaults: new { controller = "Blog", action = "Article" });
app.MapControllerRoute(name: "default",
               pattern: "{controller=Home}/{action=Index}/{id?}");

На основе предыдущих определений маршрутов Url.Action("Index", "Home") создает путь URL /, используя маршрут default, но почему? Можно предположить, что значений маршрута { controller = Home, action = Index } достаточно, чтобы сгенерировать URL-адрес с помощью blog, и результатом будет /blog?action=Index&controller=Home.

Выделенные обычные маршруты зависят от специального поведения значений по умолчанию, которые не имеют соответствующего параметра маршрута, который предотвращает слишком жадный маршрут при создании URL-адресов. В этом случае значения по умолчанию — { controller = Blog, action = Article }, но параметров маршрута controller и action нет. Когда система маршрутизации производит формирование URL-адреса, предоставленные значения должны соответствовать значениям по умолчанию. Создание URL-адресов с использованием blog завершается сбоем, так как значения { controller = Home, action = Index } не соответствуют { controller = Blog, action = Article }. После этого система маршрутизации выполнит попытку использовать маршрут default, которая завершится успешно.

Areas

Области — это функция MVC, используемая для упорядочивания связанных функций в группу в виде отдельной:

• Пространство имен маршрутизации для действий контроллера.
• Структура папок для представлений.

Использование областей позволяет приложению иметь несколько контроллеров с одинаковым именем, если они имеют разные области. При использовании областей создается иерархия в целях маршрутизации. Для этого к area и controller добавляется еще один параметр маршрута, action. В этом разделе описывается взаимодействие маршрутизации с областями. См. раздел «Области» для получения дополнительных сведений о том, как области используются с представлениями.

В следующем примере MVC настроен на использование стандартного обычного маршрута, а также маршрута area для area с именем Blog:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{    
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapAreaControllerRoute("blog_route", "Blog",
        "Manage/{controller}/{action}/{id?}");
app.MapControllerRoute("default_route", "{controller}/{action}/{id?}");

app.Run();

В приведенном выше коде MapAreaControllerRoute вызывается для создания "blog_route". Второй параметр — "Blog"это имя области.

При сопоставлении пути URL, например /Manage/Users/AddUser, маршрут "blog_route" создает значения маршрута { area = Blog, controller = Users, action = AddUser }. Значение маршрута area берётся из значения по умолчанию для area. Созданный маршрут MapAreaControllerRoute эквивалентен следующему коду:

app.MapControllerRoute("blog_route", "Manage/{controller}/{action}/{id?}",
        defaults: new { area = "Blog" }, constraints: new { area = "Blog" });
app.MapControllerRoute("default_route", "{controller}/{action}/{id?}");

MapAreaControllerRoute создает маршрут, используя для area значение по умолчанию и ограничение, с использованием указанного имени области, в данном случае Blog. Значение по умолчанию гарантирует, что маршрут всегда создает { area = Blog, ... }, а ограничение требует значения { area = Blog, ... } для создания URL-адресов.

Обычное маршрутизирование зависит от порядка. Как правило, поместите маршруты с областями ранее, так как они более конкретные, чем маршруты без области.

Используя предыдущий пример, значения { area = Blog, controller = Users, action = AddUser } маршрута соответствуют следующему действию:

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace1
{
    [Area("Blog")]
    public class UsersController : Controller
    {
        // GET /manage/users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }        
    }
}

Атрибут [Area] — это то, что обозначает контроллер как часть области. Этот контроллер находится в Blog области. Контроллеры без атрибута [Area] не принадлежат ни к какой области и не будут сопоставлены, если значение маршрута area задаётся маршрутизацией. В приведенном ниже примере только первый из перечисленных контроллеров может сопоставляться со значениями маршрута { area = Blog, controller = Users, action = AddUser }.

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace1
{
    [Area("Blog")]
    public class UsersController : Controller
    {
        // GET /manage/users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }        
    }
}

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace2
{
    // Matches { area = Zebra, controller = Users, action = AddUser }
    [Area("Zebra")]
    public class UsersController : Controller
    {
        // GET /zebra/users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }        
    }
}

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace3
{
    // Matches { area = string.Empty, controller = Users, action = AddUser }
    // Matches { area = null, controller = Users, action = AddUser }
    // Matches { controller = Users, action = AddUser }
    public class UsersController : Controller
    {
        // GET /users/adduser
        public IActionResult AddUser()
        {
            var area = ControllerContext.ActionDescriptor.RouteValues["area"];
            var actionName = ControllerContext.ActionDescriptor.ActionName;
            var controllerName = ControllerContext.ActionDescriptor.ControllerName;

            return Content($"area name:{area}" +
                $" controller:{controllerName}  action name: {actionName}");
        }
    }
}

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

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

В плане сопоставления отсутствующих значений отсутствие значения area равносильно тому, как если значением area было бы NULL или пустая строка.

При выполнении действия внутри области значение area маршрута доступно в качестве внешнего значения для маршрутизации, используемой для создания URL-адресов. Это означает, что по умолчанию области являются фиксированными при формировании URL-адресов, как показано в следующем примере.

app.MapAreaControllerRoute(name: "duck_route",
                                     areaName: "Duck",
                                     pattern: "Manage/{controller}/{action}/{id?}");
app.MapControllerRoute(name: "default",
                             pattern: "Manage/{controller=Home}/{action=Index}/{id?}");

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace4
{
    [Area("Duck")]
    public class UsersController : Controller
    {
        // GET /Manage/users/GenerateURLInArea
        public IActionResult GenerateURLInArea()
        {
            // Uses the 'ambient' value of area.
            var url = Url.Action("Index", "Home");
            // Returns /Manage/Home/Index
            return Content(url);
        }

        // GET /Manage/users/GenerateURLOutsideOfArea
        public IActionResult GenerateURLOutsideOfArea()
        {
            // Uses the empty value for area.
            var url = Url.Action("Index", "Home", new { area = "" });
            // Returns /Manage
            return Content(url);
        }
    }
}

Следующий код создает URL-адрес для /Zebra/Users/AddUser:

public class HomeController : Controller
{
    public IActionResult About()
    {
        var url = Url.Action("AddUser", "Users", new { Area = "Zebra" });
        return Content($"URL: {url}");
    }

Определение действия

Общедоступные методы на контроллере, за исключением тех, которые имеют атрибут NonAction , являются действиями.

Пример кода

• MyDisplayRouteInfo предоставляется пакетом NuGet Rick.Docs.Samples.RouteInfo и отображает информацию о маршруте.
• Просмотр или скачивание примера кода (как скачать)

Диагностика отладки

Для подробного вывода диагностики построения маршрутов задайте для Logging:LogLevel:Microsoft значение Debug. В среде Development установите уровень журнала в appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Debug",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}