Язык программирования C#9 и платформа .NET5

Троелсен Эндрю

WeatherForecastController.cs:30

На заметку! Нововведением в версии ASP.NET Core 5 является то, что Swagger по умолчанию включается в шаблон API. Инструменты Swagger будут подробно исследованы в следующей главе.

Резюме

В главе была представлена инфраструктура ASP.NET Core. Глава начиналась с краткого обзора истории появления ASP.NET, после чего были рассмотрены функциональные средства из классических инфраструктур ASP.NET MVC и ASP.NET Web API, которые присутствуют в ASP.NET Core.

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

способов запуска и отладки приложений ASP.NET Core вы создали решение с двумя проектами ASP.NET Core — для общей библиотеки прикладных служб и для уровня доступа к данным AutoLot (из главы 23). Наконец, вы заменили в обоих проектах стандартное средство ведения журнала ASP.NET Core инфраструктурой Serilog.

В следующей главе приложение

AutoLot.Api

будет завершено.

Глава 30

Создание служб REST с помощью ASP.NET Core

В предыдущей главе была представлена инфраструктура ASP.NET Core, обсуждались ее новые возможности, были созданы проекты, а также обновлен код в AutoLot.Mvc и

AutoLot.Api

для включения

AutoLot.Dal

и ведения журнала Serilog.

Внимание в текущей главе будет сосредоточено на завершении работы над REST-службой

AutoLot.Api

.

На заметку! Исходный код, рассматриваемый в этой главе, находится в папке

Chapter_30

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

Введение в REST-службы ASP.NET Core

Инфраструктура ASP.NET MVC начала набирать обороты почти сразу после своего выхода, а в составе версий ASP.NET MVC 4 и Visual Studio 2012 компания Microsoft выпустила ASP.NET Web API. Версия ASP.NET Web API 2 вышла вместе c Visual Studio 2013 и затем с выходом Visual Studio 2013 Update 1 была модернизирована до версии 2.2.

Продукт ASP.NETWeb API с самого начала разрабатывался как основанная на службах инфраструктура для построения служб REST (REpresentational State Transfer — передача состояния представления), которая базируется на инфраструктуре MVC минус "V" (представление) с рядом оптимизаций, направленных на создание автономных служб. Такие службы могут вызываться с применением любой технологии, а не только тех, которые производит Microsoft. Обращения к службе Web API основаны на базовых HTTP-методах (

GET

,

PUT

,

POST

,

DELETE

) осуществляются через универсальный идентификатор ресурса (uniform resource identifier — URI), например:

http://www.skimedic.com:5001/api/cars

Он похож на унифицированный указатель ресурса (uniform resource locator — URL), поскольку таковым и является! Указатель URL — это просто идентификатор URI, который указывает на физический ресурс в сети.

При вызове служб Web API используется схема HTTP (Hypertext Transfer Protocol — протокол передачи гипертекста) на конкретном хосте (в приведенном выше примере

www.skimedic.com

) и специфическом порте (5001), за которыми указывается путь (

api/cars

), а также необязательные запрос и фрагмент (в примере отсутствуют). Обращение к службе Web API может также содержать текст в теле сообщения, как вы увидите далее в этой главе. Из предыдущей главы вы узнали, что ASP.NET Core объединяет Web API и MVC в одну инфраструктуру.

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

Вспомните, что действия возвращают тип

IActionResult

(или

Task<IActionResult>

для асинхронных операций). Кроме вспомогательных

методов в

ControllerBase

, возвращающих специфические коды состояния HTTP методы действий способны возвращать содержимое как ответы в формате JSON (JavaScript Object Notation — запись объектов JavaScript).

На заметку! Строго говоря, методы действий могут возвращать широкий диапазон форматов. Формат JSON рассматривается в книге из-за своей популярности.

Результаты ответов в формате JSON

Большинство служб REST получают и отправляют данные клиентам с применением формата JSON. Ниже приведен простой пример данных JSON, состоящих из двух значений:

[

"value1",

"value2"

]

На заметку! Сериализация JSON с использованием

System.Text.Json

подробно обсуждалась в главе 20.

Службы API также применяют коды состояния HTTP для сообщения об успехе или неудаче. Некоторые вспомогательные методы для возвращения кодов состояния HTTP, доступные в классе

ControllerBase

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

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

AutoLot.Api

новый контроллер, добавив в каталог

Controllers

новый файл по имени

ValuesController.cs

с показанным ниже кодом:

using System.Collections.Generic;

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]

[ApiController]

public class ValuesController : ControllerBase

{

}

На заметку! В среде Visual Studio для контроллеров предусмотрены шаблоны. Чтобы получить к ним доступ, щелкните правой кнопкой мыши на имени каталога

Controllers

в проекте

AutoLot.Api

, выберите в контекстном меню пункт Add?Controller (Добавить?Контроллер) и укажите шаблон MVC Controller — Empty (Контроллер MVC — Пустой).

В коде устанавливается маршрут для контроллера с использованием значения (

api

) и маркера (

[controller]

). Такой шаблон маршрута будет соответствовать URL наподобие

www.skimedic.com/api/values

. Атрибут

ApiController

выбирает несколько специфичных для API средств (раскрываются в следующем разделе). Наконец, класс контроллера наследуется от

ControllerBase

. Как обсуждалось в главе 29, в инфраструктуре ASP.NET Core все типы контроллеров, доступные в классической версии ASP.NET, были объединены в один класс по имени

Controller

с базовым классом

ControllerBase

. Класс

Controller

обеспечивает функциональность, специфичную для представлений ("V" в MVC), тогда как

ControllerBase

предлагает оставшуюся базовую функциональность для приложений в стиле MVC.