Результаты действий в веб-API 2

Статья
07/16/2024

Рассмотрите возможность использования веб-API ASP.NET Core. Он имеет следующие преимущества по сравнению с ASP.NET веб-API версии 4.x:

ASP.NET Core — это кроссплатформенная платформа с открытым кодом для создания современных облачных веб-приложений в Windows, macOS и Linux.
Контроллеры ASP.NET Core MVC и контроллеры веб-API унифицированы.
Разработано для тестируемости.
Возможность разработки и запуска в ОС Windows, macOS и Linux.
Открытый исходный код и ориентация на сообщество.
Интеграция современных клиентских платформ и рабочих процессов разработки.
Облачная система конфигурации на основе среды.
Встроенное введение зависимостей.
Упрощенный высокопроизводительный модульный конвейер HTTP-запросов.
Возможность размещения в Kestrel, IIS, HTTP.sys, Nginx, Apache и Docker.
Управление параллельными версиями.
Инструментарий, упрощающий процесс современной веб-разработки.

В этом разделе описывается, как веб-API ASP.NET преобразует возвращаемое значение из действия контроллера в сообщение HTTP-ответа.

Действие контроллера веб-API может возвращать любое из следующих действий:

void
HttpResponseMessage
IHttpActionResult
Другой тип

В зависимости от того, какие из них возвращаются, веб-API использует другой механизм для создания HTTP-ответа.

Возвращаемый тип	Как веб-API создает ответ
void	Возврат пустого 204 (нет содержимого)
HttpResponseMessage	Преобразуйте непосредственно в сообщение HTTP-ответа.
IHttpActionResult	Вызовите ExecuteAsync , чтобы создать httpResponseMessage, а затем преобразовать в сообщение HTTP-ответа.
Другой тип	Напишите сериализованное возвращаемое значение в текст ответа; возвращается 200 (ОК).

Остальная часть этого раздела подробно описывает каждый вариант.

void

Если возвращается тип возвращаемого значения void, веб-API просто возвращает пустой HTTP-ответ с кодом состояния 204 (нет содержимого).

Пример контроллера:

public class ValuesController : ApiController
{
    public void Post()
    {
    }
}

Отклик HTTP:

HTTP/1.1 204 No Content
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 02:13:26 GMT

HttpResponseMessage

Если действие возвращает httpResponseMessage, веб-API преобразует возвращаемое значение непосредственно в сообщение HTTP-ответа, используя свойства объекта HttpResponseMessage для заполнения ответа.

Этот параметр позволяет контролировать ответное сообщение. Например, следующее действие контроллера задает заголовок Cache-Control.

public class ValuesController : ApiController
{
    public HttpResponseMessage Get()
    {
        HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value");
        response.Content = new StringContent("hello", Encoding.Unicode);
        response.Headers.CacheControl = new CacheControlHeaderValue()
        {
            MaxAge = TimeSpan.FromMinutes(20)
        };
        return response;
    } 
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: max-age=1200
Content-Length: 10
Content-Type: text/plain; charset=utf-16
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

При передаче модели домена в метод CreateResponse веб-API использует метод форматирования мультимедиа для записи сериализованной модели в текст отклика.

public HttpResponseMessage Get()
{
    // Get a list of products from a database.
    IEnumerable<Product> products = GetProductsFromDB();

    // Write the list to the response body.
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
    return response;
}

Веб-API использует заголовок Accept в запросе для выбора метода форматирования. Дополнительные сведения см. в разделе "Согласование содержимого".

IHttpActionResult

Интерфейс IHttpActionResult появился в веб-API 2. По сути, он определяет фабрику HttpResponseMessage . Ниже приведены некоторые преимущества использования интерфейса IHttpActionResult :

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

IHttpActionResult содержит один метод ExecuteAsync, который асинхронно создает экземпляр HttpResponseMessage .

public interface IHttpActionResult
{
    Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}

Если действие контроллера возвращает IHttpActionResult, веб-API вызывает метод ExecuteAsync для создания httpResponseMessage. Затем он преобразует HttpResponseMessage в http-ответное сообщение.

Ниже приведена простая реализация IHttpActionResult , которая создает обычный текстовый ответ:

public class TextResult : IHttpActionResult
{
    string _value;
    HttpRequestMessage _request;

    public TextResult(string value, HttpRequestMessage request)
    {
        _value = value;
        _request = request;
    }
    public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        var response = new HttpResponseMessage()
        {
            Content = new StringContent(_value),
            RequestMessage = _request
        };
        return Task.FromResult(response);
    }
}

Пример действия контроллера:

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return new TextResult("hello", Request);
    }
}

Ответ:

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: text/plain; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

Чаще используются реализации IHttpActionResult, определенные в пространстве имен System.Web.Http.Results. Класс ApiController определяет вспомогательные методы, возвращающие эти встроенные результаты действий.

В следующем примере, если запрос не соответствует существующему идентификатору продукта, контроллер вызывает ApiController.NotFound для создания ответа 404 (не найден). В противном случае контроллер вызывает ApiController.OK, который создает ответ 200 (ОК), содержащий продукт.

public IHttpActionResult Get (int id)
{
    Product product = _repository.Get (id);
    if (product == null)
    {
        return NotFound(); // Returns a NotFoundResult
    }
    return Ok(product);  // Returns an OkNegotiatedContentResult
}

Другие типы возвращаемых данных

Для всех других типов возвращаемых данных веб-API использует модуль форматирования мультимедиа для сериализации возвращаемого значения. Веб-API записывает сериализованное значение в текст ответа. Код состояния ответа — 200 (ОК).

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

Недостатком этого подхода является то, что вы не можете напрямую вернуть код ошибки, например 404. Однако вы можете вызвать httpResponseException для кодов ошибок. Дополнительные сведения см. в разделе "Обработка исключений" в веб-API ASP.NET.

Пример запроса

GET http://localhost/api/products HTTP/1.1
User-Agent: Fiddler
Host: localhost:24127
Accept: application/json

Пример отклика

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT
Content-Length: 56

[{"Id":1,"Name":"Yo-yo","Category":"Toys","Price":6.95}]

Поделиться через

Результаты действий в веб-API 2

void

HttpResponseMessage

IHttpActionResult

Другие типы возвращаемых данных

Обратная связь

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