Маршрутизация в ASP.NET Core. Получение параметров запроса из URL

Одной из часто используемых форм передачи данных в приложение ASP.NET Core является использование параметров запросов в URL. Мы уже сталкивались с этими параметрами, когда разбирались с классом HttpRequest. Сегодня рассмотрим как использовать параметры запроса в URL для конечных точек приложения ASP.NET Core.

Схема URL и параметры запроса

Для начала вспомним, что из себя представляют параметры запроса. Ниже представлена схема URL

Параметры запроса (на схеме — это часть Query) начинаются после символа ? и представляют собой пары «ключ-значение», где ключ — это имя параметра. Каждый следующий параметр запроса отделяется от предыдущего символом &. Например,

http://localhost/add?name=Task1&owner=Tom&days=4

в этом URL передаются три параметра: name со значением Task1, owner со значением Tom и days со значением 4.

Получение параметров запроса в конечной точке

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

app.MapGet("tasks/add", (string task, int days) => 
{

    toDoList.Add(new()
    {
        Name = task,
        Start = DateTime.Now,
        End = DateTime.Now.AddDays(days)
    });
    return "Задача добавлена в список";
});

здесь добавлена конечная точка tasks/add для обработчика которой мы определили два параметра — task и days. Обработчик конечной точки добавляет новую задачу в список задач, который мы разрабатывали в этой части. Посмотрим на результат работы:

теперь задача появится в списке:

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

То ASP.NET Core вернет ошибку:

Необязательные параметры запроса

В примере выше мы задали оба параметра, как обязательные, то есть, если мы не укажем в URL хотя бы один параметр. то ASP.NET Core вернет нам ошибку вида:

Чтобы параметр был необязательным, то его необходимо передавать в обработчик конечной точки как тип, допускающий null, например:

app.MapGet("tasks/add", (int? days, string task) =>

здесь мы указали, что параметр days необязательный и, следовательно, если в URL будет опущен этот параметр, то ASP.NET Core не будет возвращать ошибку (только, если в самом обработчике не возникнет исключение)

Приоритет параметров маршрута и параметров запроса

В шаблоне маршрута могут содержаться одноименные параметры, например:

app.MapGet("/tasks/{id}", (int id) =>
{
    ToDoTask task = toDoList.Where(t => t.Id == id).FirstOrDefault();
    StringBuilder sb = new StringBuilder();
    if (task != null)
    {

        sb.AppendLine("<h1>Задача</h1>");
        sb.AppendLine($"<p>ID: {task.Id}</p>");
        sb.AppendLine($"<p>Название: {task.Name}</p>");
        sb.AppendLine($"<p>Начало: {task.Start}</p>");
        sb.AppendLine($"<p>Окончание: {task.End}</p>");
    }
    else
    {
        sb.AppendLine($"Задача с ID {id} не найдена");
    }
    return sb.ToString();
});

здесь в параметрах маршрута определен параметр id. Аналогичный параметр мы можем передать в запросе. В этом случае ASP.NET Core отдаст приоритет параметру маршрута:

Объединение параметров. Атрибут [AsParameters]

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

public class ToDoTask
{
    public int Id { get; set; } //id задачи
    public string Name { get; set; } //имя задачи
    public DateTime Start { get; set; } = DateTime.Now; //дата создания задачи
    public DateTime End { get; set; } //дата окончания задачи
}            


        app.MapGet("tasks/add", ([AsParameters] ToDoTask task) =>
        {

            toDoList.Add(task);
            return "Задача добавлена в список";
        });

В этом примере ASP.NET будет связывать свойства объекта ToDoTask task с параметрами запроса. Поэтому, запрос должен выглядеть, например, следующим образом:

Итого

Для работы с параметрами запроса необходимо передать в обработчик конечной точки параметры, которые совпадают по имени с именами параметров в URL. Параметры запроса могут быть необязательными. Также мы можем объединять параметры в сложные объекты. В этом случае, для параметра обработчика конечной точки должен использоваться атрибут [AsParameters].