ASP.NET Core Web API. Работа с запросом пользователя (объект HttpRequest)

При разработке приложений ASP.NET Core Web API на основе контроллеров платформа позволяет нам максимально лаконично и удобно работать с запросами пользователя и ответами сервера. По сути, в большинстве случаев, для формирования ответа пользователю, нам требуется создать какой-либо объект, содержащий данные для ответа и передать его в результате выполнения метода контроллера. Далее, ASP.NET Core задействует встроенные механизмы сериализации объекта в JSON, добавит необходимые заголовки ответа и т.д. Чаще нам потребуется работа с параметрами запроса пользователя, которые в объекте HttpContext содержатся в свойстве Request. Рассмотрим это свойство подробнее, прежде, чем рассмотрим ещё один пример использования middleware в своих приложениях.

Общие сведения о HTTP-сообщениях и URI

Несмотря на то, что изучение темы разработки Web API подразумевается наличие у нас знаний о работе протокола HTTP, нелишним будет вспомнить из чего состоят HTTP-сообщения. Клиент и сервер «общаются» между собой при помощи HTTP-сообщений: клиент отправляет на сервер запрос, сервер отправляет клиенту ответ. HTTP-сообщение состоит из трех частей:

1. Стартовая строка
2. Заголовки сообщения
3. Тело сообщения. Тело сообщения может отсутствовать. Тело сообщения отделяется от заголовком пустой строкой.

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

Метод URI HTTP/Версия

• Метод — определяет тип запроса и выглядит как одно слово, записанное заглавными буквами. Также, методы HTTP часто называют HTTP-глаголами так как в качестве методов часто выступают именно глаголы — GET, POST, PUT, DELETE. Однако, в качестве методов могут выступать и существительные, например, HEAD или OPTIONS, но, при разработке Web API эти методы, если и используются, то достаточно редко.
• URI — строка, определяющая путь к ресурсу. Например, /index.html или / и так далее
• Версия — строка, определяющая версию протокола. Например, 0.9, 1.0, 1.1, 2.

Пример стартовой строки:

GET /index.html HTTP/1.0

Заголовки сообщения — строка вида «ключ: значение«. Заголовки могут подразделяться на основные, заголовки запроса и заголовки сущности. Заголовки сущности используются в том случае, если HTTP-сообщение содержит тело. Например, заголовок Content-Length относится к заголовкам сущности и указывает на размер тела сообщения.

Чтобы запросить главную страницу сайта example.com мы могли бы отправить на сервер следующее HTTP-сообщение:

GET /index.html HTTP/1.0
Host: example.com

здесь мы используем всего один заголовок Host, содержащий имя хоста. Конечно, в повседневной жизни мы не создаем HTTP-сообщения вручную — обычно, мы указываем в адресной строке браузера URI и браузер отправляет запрос GET на сервер, самостоятельно формируя необходимую стартовую строку, заголовки и т.д., а в ответ получает HTTP-сообщение, представляющее ответ сервера, разбирает это сообщение и предоставляет нам уже готовый результат.

В случае с взаимодействием с каким-либо Web API, наша работа несколько усложняется — здесь нам уже необходимо самостоятельно указывать метод запроса, а также, при необходимости, добавить необходимые заголовки или тело сообщения. Но, опять же, в большинстве случае, нам не требуется вручную формировать HTTP-сообщение — эту работу выполняют классы и объекты C#, отвечающие за работу с протоколом HTTP. Так или иначе, взаимодействуем ли мы с сервером через браузер или же самостоятельно формируем и отправляем запросы, используя свои приложения, ключевым элементом в таком взаимодействии выступает URI (Uniform Resource Identifier) или, если использовать устоявшееся определение — URL (Uniform Resource Locator). URI также состоит из нескольких элементов, которые схематично можно представить следующим образом:

Например, мы могли бы использовать следующий URI для запроса главной страницы сайта — http://example.com/index.html. Здесь:

• http — элемент SCHEME на рисунке. Схема запроса
• example.com — элемент host на схеме. Имя хоста
• /index.html — элемент PATH на схеме. Путь к ресурсу

Теперь, немного вспомнив основные моменты по протоколу HTTP и URI, рассмотрим свойства класса HttpRequest, представляющего запрос пользователя.

Свойства класса HttpRequest

У объекта HttpRequest определены следующие свойства:

Примеры использования HttpRequest

Воспользуемся некоторыми свойствами объекта HttpRequest. Так как данные контекста запроса мы можем получить непосредственно в контроллере, то для демонстрации свойств HttpRequest нам не обязательно создавать свой компонент middleware и встраивать его в конвейер запроса. Воспользуемся контроллером WeatherForecastController, который уже имеется в шаблоне приложения ASP.NET Core Web API, но перепишем его метод Get() следующим образом:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }


    [HttpGet]
    public string Get()
    {
       return $"{HttpContext.Request.Method} {HttpContext.Request.Path} {HttpContext.Request.Protocol}";
    }
}

Здесь, в методе Get(), мы, по сути, воспроизводим стартовую строку HTTP-запроса — получаем названием метода, путь к ресурсу и версию протокола, используемые для выполнения запроса. Теперь запустим приложение и посмотрим на результат выполнения запроса к контроллеру:

Также, можно получить и проанализировать заголовки запроса. Например, так

[HttpGet(Name = "GetWeatherForecast")]
public IHeaderDictionary Get()
{
    return HttpContext.Request.Headers;
}

мы можем получить имена и значения всех заголовков запроса. Результат выполнения метода Get() будет следующим:

Соответственно, в браузере количество заголовков будет больше:

Если же нам необходимо получить значения конкретных заголовков, то можно воспользоваться свойствами HttpRequest, например, HttpContext.Request.ContentType вернет значение заголовка Content-Type. Или же воспользоваться свойством Headers объекта HttpRequest так:

HttpContext.Request.Headers["User-Agent"]

В данном случае мы получим значение заголовка User-Agent, если он определен в запросе.

Аналогичным образом мы можем использовать свойства HttpRequest для получения информации об URI. Выше, мы уже получали значение пути к ресурсу. Если нам необходимо получить значения параметров запроса, то мы можем воспользоваться свойство Query или QueryString.

Вообще, параметры запроса и работа с ними занимает немаловажное место при разработке приложения Web API — именно через параметры запроса мы можем передавать, например, значения для фильтрации данных, их упорядочивания, поиска и так далее. В дальнейшем, мы обязательно вернемся к этим полезным свойствам и рассмотрим их более подробно.

Итого

При разработке приложений Web API мы можем использовать параметры запроса пользователя для выстраивания логики работы своего приложения. Для получения параметров запроса, например, используемого метода HTTP, пути к ресурсу, заголовков запроса и так далее используется свойство Request объекта HttpContext. Свойство Request представляет собой объект типа HttpRequest, который содержит исчерпывающую информацию о запросе пользователя.