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

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

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

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

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

• Объясняет взаимодействие между MVC и маршрутизацией:
  • Как типичные приложения MVC используют функции маршрутизации.
  • Охватывает оба:
    • Обычная маршрутизация обычно используется с контроллерами и представлениями.
    • Маршрутизация атрибутов , используемая с API. Если вы в первую очередь заинтересованы в маршрутизации для API, перейдите к разделу "Маршрутизация атрибутов для 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();

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

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

Шаблон маршрута:

• Соответствует пути URL, похожему на

• Извлекает значения маршрута путем маркеризации пути. Извлечение значений маршрута приводит к совпадению, если у приложения есть контроллер с именем и действием :

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

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

• модель привязывает значение для задания параметра . Дополнительную информацию см. в разделе "Привязка модели".

• определяется как значение по умолчанию .

• определяется как значение по умолчанию .

• Символ в [контексте] определяет его как необязательный.

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

• Соответствует этому пути URL.

• Создает параметры маршрутизации.

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

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

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

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

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

Удобный метод

app.MapDefaultControllerRoute();

Replaces:

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

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

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

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

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

• Первый сегмент пути сопоставляется с именем контроллера.
• Второй сегмент, сопоставляется с именем действия .
• Третий сегмент используется для необязательного параметра. В < > делает его необязательным. сопоставляется с сущностью модели.

Используя этот маршрут, путь в URL-адресе:

• соотносится с действием.
• сопоставляется с моделью и обычно привязывает параметр к 17.

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

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

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

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

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

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

и :

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

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

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

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

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

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

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

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

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

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

Так как шаблон маршрута не включает и в качестве параметров:

• Они могут иметь только значения по умолчанию.
• Этот маршрут всегда сопоставляется с действием .

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

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

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

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

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

public static void Main(string[] args)
{
   AppContext.SetSwitch("Microsoft.AspNetCore.Routing.UseCorrectCatchAllBehavior", 
                         true);
   CreateHostBuilder(args).Build().Run();
}
// Remaining code removed for brevity.

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

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

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

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

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-адреса
• Данные маршрута.

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

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

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

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

Параметр , предоставляется для маршрутизации, чтобы он смог выбрать в зависимости от метода HTTP запроса. Содержит лучшее совпадение, чем .

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

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

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

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

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.

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

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

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

В приведенном выше коде вы вызываете сопоставление контроллеров, маршрутизируемых по атрибутам.

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

• соответствует набору URL-адресов, аналогичных тому, что соответствует стандартному маршруту по умолчанию.

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

Действие выполняется для любого из следующих путей URL-адресов: , , , или .

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

При атрибутивной маршрутизации имена контроллеров и действий не играют никакой роли в определении того, какое действие сопоставляется, если не используется замена токенов. Следующий пример соответствует тем же 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);
    }
}

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

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]")]
public class HomeController : Controller
{
    [Route("~/")]
    [Route("/Home")]
    [Route("~/Home/Index")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

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

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

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

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

Следующие ключевые слова — зарезервированные имена параметров маршрута при использовании контроллеров или страниц:

• action
• area
• controller
• handler
• page

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

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

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

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

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

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

• Каждое действие содержит атрибут, который ограничивает соответствие только HTTP-запросам GET.
• Действие включает шаблон, поэтому добавляется к шаблону на контроллере. Шаблон метода . Поэтому это действие соответствует только запросам GET для формы , и т. д.

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

• Действие содержит шаблон. Часть шаблона ограничивает значения маршрута строками, которые можно преобразовать в целое число. Запрос GET:
  • Не соответствует этому действию.
  • Возвращает ошибку 404 Not Found .

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

• Действие содержится в шаблоне, но не ограничивает значения, которые можно преобразовать в целое число. Запрос GET к:
  • Соответствует этому маршруту.
  • Привязка модели не может преобразовать значение в целое число. Параметр метода является целым числом.
  • Возвращает ошибку 400: Неверный запрос, так как привязка модели не смогла преобразовать значение в целое число.

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

Маршрутизация атрибутов может использовать такие атрибуты, как , и . Все атрибуты команды 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-адреса:

• Действие запускается, когда используется HTTP-метод.
• Действие выполняется, когда используется HTTP-глагол [здесь должен быть глагол].

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

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

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

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

Действие :

• Выполняется с URL-адресом, например
• Не запускается с путем URL.

Атрибут [Consumes] позволяет выполнять действие для ограничения поддерживаемых типов содержимого запросов. Для получения дополнительной информации см. раздел "Определение поддерживаемых типов контента запроса" с атрибутом "Consumes".

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

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

Имя маршрута

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

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

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

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

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

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

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

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

[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-адреса может совпадать
• Путь URL-адреса может совпадать .

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

Шаблоны маршрутов, применяемые к действию, и которые начинаются или не объединяются с шаблонами маршрутов, применяемыми к контроллеру. Следующий пример соответствует набору путей 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();
    }
}

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

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

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

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

Например, маршрут атрибута, такой как <маршрут_1>, более конкретный, чем маршрут атрибута, такой как <маршрут_2>. По умолчанию маршрут имеет более высокий приоритет, так как он более конкретный. Используя обычную маршрутизацию, разработчик отвечает за размещение маршрутов в нужном порядке.

Маршруты атрибутов могут настраивать порядок с помощью свойства. Все предоставленные атрибуты маршрута фреймворка включают . Маршруты обрабатываются в порядке возрастания значения свойства . Порядок по умолчанию — . Установка маршрута с использованием запусков перед маршрутами, которые не задают порядок. Настройка маршрута с помощью запусков после упорядочивания маршрутов по умолчанию.

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

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

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

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

AmbiguousMatchException: The request matched multiple endpoints. Matches:

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

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

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

В приведенном выше коде запускается конечная точка. Чтобы перейти к , запросите . Note:

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

Сведения о порядке маршрутов в Pages см. в разделе о маршрутах Pages и соглашениях о приложениях: Порядок маршрута.

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

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

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

[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();
}

• Матчи

[HttpGet("{id}")]
public IActionResult Edit(int id)
{
    return ControllerContext.MyDisplayRouteInfo(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);
    }
}

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

Кроме того, можно объединить атрибутивные маршруты с наследованием. Эта комбинация мощна при использовании замены токенов. Замена токенов также применяется к именам маршрутов, определенным в атрибутных маршрутах. создает уникальное имя маршрута для каждого действия:

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

Для сопоставления с литеральным разделителем замены токенов или его следует экранировать путем повтора символа ( или ).

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

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

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

Конвенция модели приложения, которая:

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

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

Предыдущий метод соответствует.

Зарегистрировано как опция:

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.

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

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

[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-команды реализуются.

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

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

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

В приведенном выше коде применяется ограничение маршрута. Действие сопоставляется только по путям URL-адресов, например . Часть шаблона маршрута ограничивает сегмент только целыми числами.

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

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

Все атрибуты маршрута реализуют [некоторую функциональность]. Среда выполнения ASP.NET Core:

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

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

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

Предыдущий метод возвращает [значение/результат].

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

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

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

Модель приложения включает все данные, собранные из атрибутов маршрута. Данные об атрибутах маршрута предоставляются системой реализации. 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()
            };
        }
    }
}

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

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

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

[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}");
    }
}

Метод :

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

Его можно применить в :

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

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

• База — это .
• Полное имя предыдущего контроллера .
• Задает для шаблона контроллеров значение .

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

[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-страницы в браузерах, и маршрутизацию атрибутов для контроллеров, обслуживающих 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;
}

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

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

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

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

Интерфейс — это базовый элемент инфраструктуры между MVC и маршрутизацией для создания 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-адреса, объединяя:

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

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

result: /UrlGeneration/Destination

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

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

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

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

• Значения маршрута используются для расширения шаблона.
• Значения маршрута для и обычно отображаются в этом шаблоне. Это работает, так как 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();
    }
}

Действие, приведенное в предыдущем коде, создает .

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

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

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

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

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

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

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

Если добавляется значение :

• Значение игнорируется.
• Путь к созданному URL-адресу .

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

• Оба значения игнорируются.
• Больше нет значения, и создание URL-адресов не удаётся.
• Необходимо указать требуемые значения и создать URL-адрес.

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

Несколько перегрузок Url.Action принимают объект значений маршрута, чтобы предоставить значения для параметров маршрута, отличных от и. Объект значений маршрута часто используется с . Например, . Объект значений маршрута:

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

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

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

Предыдущий код создает .

Следующий код создает абсолютный 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-адрес, используйте один из следующих параметров:

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

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

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

• Указывает имя маршрута для создания 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();
    }

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

<h1>Test Links</h1>

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

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

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

Для формирования URL-адресов используются вспомогательные функции тегов AnchorTagHelper и LinkTagHelper. Обе они используются для реализации. Дополнительные сведения см. в разделе "Вспомогательные функции тегов" в формах.

В представлениях приложения это свойство доступно для создания произвольных URL-адресов, не охватываемых предыдущими методами.

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

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

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

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

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

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

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

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-адресов не удаётся при использовании, так как значения не совпадают. После этого система маршрутизации попробует использовать другой маршрут, который завершится успешно.

Areas

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

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

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

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

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

В приведенном выше коде функция/метод вызывается для создания объекта/элемента. Второй параметр — это имя области.

При сопоставлении пути URL, например <пример>, маршрут генерирует маршрутные значения. Значение маршрута поступает из значения по умолчанию для параметра. Созданный маршрут эквивалентен следующему коду:

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

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

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

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

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] — это то, что обозначает контроллер как часть области. Этот контроллер находится в области. Контроллеры без атрибута не являются членами какой-либо области и не совпадают, если значение маршрута предоставляется маршрутизацией. В приведенном ниже примере только первый контроллер может соответствовать значениям маршрута .

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.

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

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

При выполнении действия внутри области значение маршрута доступно в качестве внешнего значения для маршрутизации, используемой для создания 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-адрес для :

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": {
      "Default": "Information",
      "Microsoft": "Debug",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

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

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

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

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

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

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

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

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

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

Шаблон маршрута:

• Соответствует пути URL, похожему на

• Извлекает значения маршрута путем маркеризации пути. Извлечение значений маршрута приводит к совпадению, если у приложения есть контроллер с именем и действием :

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

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

• модель привязывает значение для задания параметра . Дополнительную информацию см. в разделе "Привязка модели".

• определяется как значение по умолчанию .

• определяется как значение по умолчанию .

• Символ в [контексте] определяет его как необязательный.

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

• Соответствует этому пути URL.

• Создает параметры маршрутизации.

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

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

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

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

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

Удобный метод :

endpoints.MapDefaultControllerRoute();

Replaces:

endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");

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

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

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

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

• Первый сегмент пути сопоставляется с именем контроллера.
• Второй сегмент, , соотносится с именем действия .
• Третий сегмент используется для необязательной опции. Делает его необязательным. сопоставляется с сущностью модели.

Используя этот маршрут, путь URL-адреса:

• сопоставляется с действием .
• сопоставляется с моделью и обычно привязывает параметр к 17.

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

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

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

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

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

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

и :

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

Маршрутизация конечных точек в ASP.NET Core 3.0 или более поздней версии:

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

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

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

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

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

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

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

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

Так как шаблон маршрута не включает и в качестве параметров:

• Они могут иметь только значения по умолчанию.
• Этот маршрут всегда сопоставляется с действием .

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

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

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

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

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

public static void Main(string[] args)
{
   AppContext.SetSwitch("Microsoft.AspNetCore.Routing.UseCorrectCatchAllBehavior", 
                         true);
   CreateHostBuilder(args).Build().Run();
}
// Remaining code removed for brevity.

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

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

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

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

    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-адреса
• Данные маршрута.

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

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

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

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

Параметр , предоставляется для маршрутизации, чтобы он смог выбрать в зависимости от метода HTTP запроса. Содержит лучшее совпадение, чем .

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

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

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

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

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

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

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

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

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

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

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

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

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

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

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

• соответствует набору URL-адресов, аналогичных тому, что соответствует стандартному маршруту по умолчанию.

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

Действие выполняется для любого из следующих путей URL-адресов: , , , или .

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

При атрибутивной маршрутизации имена контроллеров и действий не играют никакой роли в определении того, какое действие сопоставляется, если не используется замена токенов. Следующий пример соответствует тем же 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);
    }
}

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

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]")]
public class HomeController : Controller
{
    [Route("~/")]
    [Route("/Home")]
    [Route("~/Home/Index")]
    public IActionResult Index()
    {
        return ControllerContext.MyDisplayRouteInfo();
    }

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

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

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

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

Следующие ключевые слова — зарезервированные имена параметров маршрута при использовании контроллеров или страниц:

• action
• area
• controller
• handler
• page

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

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

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

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

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

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

• Каждое действие содержит атрибут, который ограничивает соответствие только HTTP-запросам GET.
• Действие включает шаблон, поэтому добавляется к шаблону на контроллере. Шаблон метода . Поэтому это действие соответствует только запросам GET для формы , и т. д.

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

• Действие содержит шаблон. Часть шаблона ограничивает значения маршрута строками, которые можно преобразовать в целое число. Запрос GET:
  • Не соответствует этому действию.
  • Возвращает ошибку 404 Not Found .

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

• Действие содержится в шаблоне, но не ограничивает значения, которые можно преобразовать в целое число. Запрос GET:
  • Соответствует этому маршруту.
  • Привязка модели не может преобразовать значение в целое число. Параметр метода является целым числом.
  • Возвращает ошибку 400: Неверный запрос, так как привязка модели не смогла преобразовать значение в целое число.

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

Маршрутизация атрибутов может использовать такие атрибуты, как , и . Все атрибуты команды 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-адреса:

• Действие выполняется, когда используется HTTP-глагол [здесь должен быть глагол].
• Действие выполняется, когда используется HTTP-глагол [здесь должен быть глагол].

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

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

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

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

Действие :

• Выполняется с URL-адресом, например
• Не запускается с путем URL.

Атрибут [Consumes] позволяет выполнять действие для ограничения поддерживаемых типов содержимого запросов. Для получения дополнительной информации см. раздел "Определение поддерживаемых типов контента запроса" с атрибутом "Consumes".

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

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

Имя маршрута

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

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

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

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

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

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

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

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

[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-адреса может совпадать
• Путь URL-адреса может совпадать .

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

Шаблоны маршрутов, применяемые к действию, и которые начинаются или не объединяются с шаблонами маршрутов, применяемыми к контроллеру. Следующий пример соответствует набору путей 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();
    }
}

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

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

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

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

Например, маршрут атрибута, такой как <маршрут_1>, более конкретный, чем маршрут атрибута, такой как <маршрут_2>. По умолчанию маршрут имеет более высокий приоритет, так как он более конкретный. Используя обычную маршрутизацию, разработчик отвечает за размещение маршрутов в нужном порядке.

Маршруты атрибутов могут настраивать порядок с помощью свойства. Все предоставленные атрибуты маршрута фреймворка включают . Маршруты обрабатываются в порядке возрастания значения свойства . Порядок по умолчанию — . Установка маршрута с использованием запусков перед маршрутами, которые не задают порядок. Настройка маршрута с помощью запусков после упорядочивания маршрутов по умолчанию.

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

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

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

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

AmbiguousMatchException: The request matched multiple endpoints. Matches:

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

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

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

В приведенном выше коде запускается конечная точка. Чтобы перейти к , запросите . Note:

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

Для получения информации о порядке маршрутов со Страницами см. раздел «Маршруты со Страницами и соглашения о приложениях: Порядок маршрутов».

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

Замена токенов в шаблонах маршрутов [контроллер], [действие], [область]

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

[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();
}

• Совпадения

[HttpGet("{id}")]
public IActionResult Edit(int id)
{
    return ControllerContext.MyDisplayRouteInfo(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);
    }
}

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

Кроме того, можно объединить маршрутизацию атрибутов с наследованием. Эта комбинация мощна при использовании замены токена. Замена токенов также применяется к именам маршрутов, задаваемым атрибутными маршрутами. создает уникальное имя маршрута для каждого действия:

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

Для сопоставления с буквальным разделителем замены токенов "<" или ">", его следует экранировать путем повторения символа "<" или ">".

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

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

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

Применяется конвенция модели приложения, которая:

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

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

Предыдущий метод соответствует.

Опция регистрируется в качестве параметра в .

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews(options =>
    {
        options.Conventions.Add(new RouteTokenTransformerConvention(
                                     new SlugifyParameterTransformer()));
    });
}

Для определения slug см. раздел «Slug» в веб-документации MDN.

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

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

[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-команды реализуются.

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

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

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

В приведенном выше коде применяется ограничение маршрута. Действие сопоставляется только по URL-адресам, например. Часть шаблона маршрута ограничивает сегмент только целыми числами.

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

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

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

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

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

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

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

Предыдущий метод возвращает [значение/результат].

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

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

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

Модель приложения включает все данные, собранные из атрибутов маршрута. Данные об атрибутах маршрута предоставляются системой реализации. 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()
            };
        }
    }
}

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

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

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

[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}");
    }
}

Метод :

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

Его можно применить в :

namespace My.Application
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllersWithViews(options =>
            {
                options.Conventions.Add(
                    new NamespaceRoutingConvention(typeof(Startup).Namespace));
            });
        }
        // Remaining code ommitted for brevity.

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

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

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

• База — это .
• Полное имя предыдущего контроллера .
• Задает для шаблона контроллеров значение .

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

[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-страницы в браузерах, и маршрутизацию атрибутов для контроллеров, обслуживающих API.

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

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

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

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

Интерфейс — это базовый элемент инфраструктуры между MVC и маршрутизацией для создания 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-адреса, объединяя:

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

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

result: /UrlGeneration/Destination

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

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

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

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

• Значения маршрута используются для расширения шаблона.
• Значения маршрута для и обычно отображаются в этом шаблоне. Это работает, так как 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();
    }
}

Действие, приведенное в предыдущем коде, создает .

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

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

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

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

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

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

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

Если значение добавлено:

• Значение игнорируется.
• Путь к созданному URL-адресу — .

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

• Оба значения игнорируются.
• Больше нет значения, и создание URL-адресов не удается.
• Необходимо указать требуемые значения и создать URL-адрес.

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

Несколько перегрузок Url.Action принимают объект значений маршрута, чтобы предоставить значения для параметров маршрута, отличных от и. Объект значений маршрута часто используется с . Например, . Объект значений маршрута:

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

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

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

Предыдущий код создает .

Следующий код создает абсолютный 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-адрес, используйте один из следующих параметров:

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

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

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

• Указывает имя маршрута для создания 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();
    }

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

<h1>Test Links</h1>

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

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

предоставляет методы Html.BeginForm и Html.ActionLink для создания и элементов соответственно. Эти методы используют метод Url.Action для создания URL-адреса и принимают аналогичные аргументы. Дополнительные функции для — это и , которые имеют схожую функциональность.

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

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

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

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

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

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

Методы фабрики результатов действий, такие как [FactoryMethod1] и [FactoryMethod2], следуют аналогичному шаблону, как методы на [Object].

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

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

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

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

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

Areas

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

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

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

В следующем примере MVC настраивается для использования стандартного маршрута по умолчанию и маршрута для именованного :

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

В приведенном выше коде функция вызывается для создания объекта. Второй параметр — это имя области.

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

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

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

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

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

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] — это то, что обозначает контроллер как часть области. Этот контроллер находится в области. Контроллеры без атрибута не являются членами какой-либо области и не совпадают, если значение маршрута предоставляется маршрутизацией. В приведенном ниже примере только первый контроллер может соответствовать значениям маршрута .

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.

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

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

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

app.UseEndpoints(endpoints =>
{
    endpoints.MapAreaControllerRoute(name: "duck_route", 
                                     areaName: "Duck",
                                     pattern: "Manage/{controller}/{action}/{id?}");
    endpoints.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-адрес для :

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": {
      "Default": "Information",
      "Microsoft": "Debug",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}