Asp net core web api

Введение в Web API

Web API представляет способ построения приложения ASP.NET, который специально заточен для работы в стиле REST (Representation State Transfer или "передача состояния представления"). REST-архитектура предполагает применение следующих методов или типов запросов HTTP для взаимодействия с сервером:

Зачастую REST-стиль особенно удобен при создании всякого рода Single Page Application, которые нередко используют специальные javascript-фреймворки типа Angular, React или Knockout. По сути Web API представляет собой веб-службу, к которой могут обращаться другие приложения. Причем эти приложения могут представлять любую технологию и платформу — это могут быть веб-приложения, мобильные или десктопные клиенты.

Создадим проект Web API. Для этого среди типов проектов выберем ASP.NET Core Web Application и далее среди шаблонов укажем Web API :

Проект, который создается в Visual Studio, будет во многом напоминать проект для MVC за тем исключением, что в нем не будет представлений:

Здесь есть один единственный контроллер ValuesConroller, который предназначен для обработки запросов:

Для контроллера определен один общий маршрут [Route("api/[controller]")] . В итоге обращение api/values будет соответствовать обращению к контроллеру ValuesCotroller, причем почти ко всем действиям сразу (кроме метода Get(int id) — так как в данном случае необходим еще идентификатор, например, api/values/2 ).

Однако к методам контроллера применяются специальные атрибуты [HttpGet] или HttpPost , которые и указывают, какой именно тип запроса будет обрабатываться методом. Так, например, запрос GET api/values будет сопоставлен с методом IEnumerable Get() и вернет в ответ клиенту коллекцию элементов string. Например, запустим проект и тогда увидим в браузере эту коллекцию строк:

В то же время если в GET-запросе будет передан параметр api/values/7 , то данному запросу будет соответствовать метод string Get(int id) , так как он принимает параметр.

Если же сервер получит запрос PUT с адресом api/values , то такой запрос будет сопоставлен с методом, к которому применяется атрибут HttpPut .

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

В этом руководстве мы создадим просто веб API для управления списком элементов “to-do”. Никакого UI здесь мы создавать не будем.

В ASP.NET Core есть встроенная поддержка MVC Web API. Унификация двух фреймворков упрощает создание приложения, которые включают в себя и UI (HTML), и API, поскольку они сейчас делят между собой и код, и поток.

Если вы портируете существующее Web API приложение в ASP.NET Core, см. Migrating from ASP.NET Web API

Обзор¶

Вот API, который мы создадим:

API Описание Тело запроса Тело ответа
GET /api/todo Получает все элементы to-do Нету Массив элементов to-do
GET /api/todo/ Получает элемент по ID Нету Элемент To-do
POST /api/todo Добавляет новый элемент Элемент To-do Элемент To-do
PUT /api/todo/ Обновляет существующий элемент Элемент To-do Нету
PATCH /api/todo/ Обновляет существующий элемент Элемент To-do Нету
DELETE /api/todo/ Удаляет элемент Нету Нету

На следующей диаграмме показан базовый дизайн приложения.

  • Клиентом является что-то, что потребляет API (браузер, мобильное приложение и тд). В этом руководстве мы не будем писать клиент. Для тестирования приложения мы будем использовать Postman.
  • Модель — это объект, который представляет в приложении данные. В данном случае единственной моделью является элемент to-do. Модели представлены как простые C# классы (POCO).
  • Контроллер — это объект, который обрабатывает HTTP запросы и создает HTTP ответы. В этом приложении будет один контроллер.
  • Для упрощения приложения мы не будем использовать БД. Элементы to-do будут храниться в памяти. Но мы включим слой доступа к данным, чтобы показать разделение между веб API и слоем данных. Если вы хотите использовать БД, просмотрите Создание первого ASP.NET Core MVC приложения с помощью Visual Studio .
Читайте также:  Имя сбойного приложения printisolationhost exe

Создание проекта¶

Запустите Visual Studio. Из меню File выберите New > Project.

Выберите шаблон ASP.NET Core Web Application (.NET Core). Назовите проект TodoApi , очистите Host in the cloud и нажмите OK.

В диалоговом окне New ASP.NET Core Web Application (.NET Core) — TodoApi выберите шаблон Web API. Нажмите OK.

Добавление класса модели¶

Модель — это объект, который представляет в приложении данные. В данном случае модель — это элемент to-do.

Добавьте папку “Models”. В Solution Explorer кликните правой клавишей мышки по проекту. Выберите Add > New Folder. Назовите папку Models.

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

Добавьте класс TodoItem . Кликните правой клавишей мышки по папке Models и выберите Add > > TodoItem и нажмите Add.

Замените сгенерированный код следующим:

Добавления класса репозитория¶

Репозиторий — это объект, который инкапсулирует слой данных и содержит логику для получения данных и приведения их к модели. Хотя мы не используем БД, полезно посмотреть, как внедрять репозиторий в контроллеры. Создайте код для репозитория в папке Models.

Определите интерфейс репозитория с именем ITodoRepository . Используйте шаблон (Add New Item > Class).

Этот интерфейс определяет базовые операции CRUDы.

Далее, добавьте класс TodoRepository , который реализует ITodoRepository :

Соберите приложение, чтобы проверить, что ошибок компиляции нет.

Регистрация репозитория¶

При определении интерфейса репозитория мы можем отделить класс репозитория от MVC контроллера, который его использует. Вместо создания экземпляра TodoRepository внутри контроллера мы внедрим ITodoRepository , используя встроенную поддержку ASP.NET Core для DI .

Такой подход упрощает модульное тестирование контроллеров. Юнит тесты используют “mock” или “stub” версию ITodoRepository . Тогда тесты нацелены на логику контроллера, а не на слой доступа к данным.

Чтобы внедрить репозиторий в контроллер, нам нужно зарегистрировать его с помощью DI контейнера. Откройте файл Startup.cs. Добавьте следующую директиву using:

В метод ConfigureServices добавьте выделенный код:

Добавление контроллера¶

В Solution Explorer кликните правой клавишей мышки по папке Controllers. Выберите Add > New Item. В диалоговом окне Add New Item выберите шаблон Web API Controller > TodoController .

Замените сгенерированный код следующим:

Это определит класс контроллера. В следующем разделе мы добавим методы, чтобы реализовать API.

Получение элементов to-do¶

Чтобы получить элементы to-do, добавьте следующие методы в класс TodoController .

Эти методы реализуют два метода GET:

Вот пример HTTP ответа для метода GetAll :

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Server: Microsoft-IIS/10.0 Date: Thu, 18 Jun 2015 20:51:10 GMT Content-Length: 82

Далее в руководстве я покажу, как просмотреть HTTP ответ с помощью инструмента Postman.

Роутинг и URL пути¶

Microsoft.AspNetCore.Mvc.HttpGetAttribute` ) указывает, что это HTTP GET методы. URL путь для каждого метода построен следующим образом:

  • Возьмите строку шаблона из атрибута route контроллера, [Route("api/[controller]")]
  • Замените “[Controller]” именем контроллера, что является именем класса контроллера минус суффикс “Controller”. В данном примере именем класса контроллера является TodoController, а именем коревой директории — “todo”. ASP.NET MVC Core роутинг не чувствителен к регистру.
  • Если у атрибута [HttpGet] также есть строка шаблона, добавьте ее к пути. В данном примере не используется строка шаблона.

Для метода GetById “ < >todo . В рантайме, когда MVC вызывает GetById , он присваивает значение “ < >id .

В методе GetById :

"" — это переменная-заменитель для > todo . Когда вызывается GetById , он присваивает значение “ < >id .

Name = "GetTodo" создает именованный роут и позволяет вам ссылаться на этот роут в HTTP ответе. Позже я это поясню.

Возвращаемые значения¶

Метод GetAll возвращает IEnumerable . MVC автоматически сериализует объект в JSON и записывает JSON в тело ответа. Кодом ответа для этого метода является 200, если нет необработанных исключений. (Необработанные исключения переводятся в ошибки 5xx).

Метод GetById наоборот возвращает более общий тип IActionResult , который представляет широкий спектр возвращаемых типов. У GetById есть два возвращаемых типа:

  • Если ни один элемент не соответствует запрашиваемому > NotFound .
  • Иначе метод возвращает 200 с телом ответа JSON путем возвращения :dn:cls:`

Запуск приложения¶

В Visual Studio нажмите CTRL+F5, чтобы запустить приложение. Visual Studio запускает браузер и переходит по http://localhost:port/api/values , где port — это случайно выбранный номер порта. Если вы используете Chrome, Edge или Firefox, будут отображены данные. Если вы используете IE, IE предложит вам открыть или сохранить файл values.json.

Реализация других операций CRUD¶

Наконец, нам надо добавить в контроллер методы Create , Update и Delete . Я просто покажу вам код и выделю главные отличия. Соберите проект после добавления или изменения кода.

Читайте также:  Сталкер как пройти лабиринт

Create¶

Это метод HTTP POST, указанный атрибутом [HttpPost]. Атрибут [FromBody] говорит MVC, чтобы он получил значение элемента to-do из тела HTTP запроса.

Метод CreatedAtRoute возвращает ответ 201, являющимся стандартным ответом для метода HTTP POST, который создает новый источник на сервере. CreateAtRoute также добавляет в ответ заголовок Location. Заголовок Location определяет URI нового элемента to-do. См. 10.2.2 201 Created.

Использование Postman для отправки Create запроса¶

Вы можете использовать заголовка Location, чтобы получить доступ к ресурсу, который создали. Снова вызовите метод GetById , созданный именованным роутом "GetTodo" :

Update¶

Update похож на Create , но он использует HTTP PUT. Ответом является 204 (No Content). В соответствии со HTTP спецификацией, запросу PUT требуется, чтобы клиент отправлял полностью обновленные данные, а не только дельты. Для частичных обновлений используется HTTP PATCH.

Обновление с Patch¶

Этот вариант похож на Update , но здесь используется HTTP PATCH. Ответом является 204 (No Content).

Вступление

Данная статья рассчитана на новичков, которые делают первые шаги в изучении Angular в связке с .NET Core.

Если вы используете Visual Studio для разработки, то наверное уже встречались с готовыми шаблонами проектов с подключенным Angular. Данные шаблоны позволяют в пару кликов создать приложение, которое уже имеет настроенный роутер и несколько готовых компонент. Вам не нужно тратить время на минимальную настройку рабочего приложения: вы уже имеете рабочий WebPack, отдельный модуль для общих компонент, настроенный роутер, подключенный Bootstrap. Возможно, вы подумаете: «Супер! Круто! Половина дела сделана!». Но на самом деле все немного сложнее…

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

  1. Жесткая связь веб-интерфейса с серверной часть
  2. Сильно усложненная минимально рабочая версия приложения
  3. Отсутствие возможности использовать Angular CLI
  4. Лишние предустановленные пакеты
  5. Нарушение некоторых принципов из Angular Style Guide

  1. Два независимых друг от друга проекта, что позволит нам в дальнейшем реализовать альтернативный интерфейс, не трогая проект с серверной частью
  2. Суженный глобальный search scope, что позволяет эффективнее и проще производить поиск
  3. Абстрагированность от рабочего окружения, в котором разрабатывается серверная часть, Visual Studio например — мы можем использовать VS Code, Sublime Text, Atom или другой удобный для вас редактор

  1. Вы хостите веб-интерфейс на одном адресе, а сервер — на другом
  2. Либо собираете магическим образом проекты в один и хостите только его

Моей задачей являлся как раз второй сценарий, так был он был более предпочтительным по экономическим соображениям. И вот, когда я пытался разобраться с тем, каким же все-таки образом подружить .NET Core Web API проект с Angular проектом, так, чтобы во время разработки у нас было два отдельных проекта, а в продакшене — всего один, а конкретно .NET Core веб-сайт, то я так и не смог найти полноценного руководства «с нуля до рабочего приложения». Пришлось собирать по кусочкам решения с англоговорящих форумов и блогов. Если у вас вдруг появилась такая же задача, то достаточно будет прочитать мою статью.

Поехали!

Если у вас уже установлена Visual Studio 2017 и при установке вы выбирали .NET Core Development, то .NET Core SDK у вас уже есть и устанавливать его не нужно. Однако Node.js отдельно придется установить даже если был выбран Node.js Development. Npm установится вместе с Node.js. Angular CLI устанавливается глобально из командной строки через npm (инструкция есть по ссылке выше).

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

Создаем проект .NET Core Web API

В данной статье я буду выполнять все действия через командную строку и VS Code, так как он поддерживает .NET Core. Однако, если для вас предпочтительна Visual Studio 2017 для работы с .NET проектами, то можете смело создать и редактировать проект через нее.

Читайте также:  Dexp st 800 отзывы

Шаг первый

(тильда, буква ё). Пока ничего сложного:)

Шаг второй

Теперь нам нужно создать проект. Для этого выполняем команду:

Шаг третий

Проверяем все ли работает. Через терминал переходим в папку с только что созданным проектом, после выполняем команду:

Шаг четвертый

Если на прошлом шаге все прошло успешно и в консоль было выведено Now listening on: localhost:5000, значит сервер успешно запущен. Перейдем по адресу localhost:5000/api/values (тестовый контроллер, который создается автоматически). Вы должны увидеть JSON с тестовыми данными.

Шаг пятый

Возвращаемся в VS Code и в терминале нажимаем Ctrl + C, чтобы остановить работу сервера.

Создаем проект Angular

Теперь создадим проект Angular. Для этого будем использовать команды Angular CLI, VS Code и встроенный терминал.

Шаг первый

В терминале переходим в корневую папку нашего проекта Project и создаем новый проект с названием Project.Angular (придется немного подождать):

Шаг второй

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

Шаг третий

Если на прошлом шаге все прошло успешно и в консоль было выведено NG Live Development Server is listening on localhost:4200, значит сервер успешно запущен. Перейдем по адресу localhost:4200. Вы должны увидеть тестовую страничку Angular.

Шаг четвертый

Возвращаемся в VS Code и в терминале нажимаем Ctrl + C, вводим Y, чтобы остановить работу сервера.

Настраиваем проект Angular

Теперь нам нужно настроить две вещи: proxy.config.json для перенаправления запросов к серверу на нужный порт, и самое главное — настройка сборки в папку wwwroot.

Шаг первый

Создаем в корне проекта Project.Angular файл с названием proxy.config.json и добавляем в него следующее содержимое:

Данная настройка указывает на то, что все запросы начинающиеся с /api/… будут попадать на localhost:5000/. То есть результирующим запросом будет localhost:5000/api/…

Шаг второй

Укажем Angular, что в режиме разработки нам нужно использовать этот proxy.config. Для этого открываем файл package.json (который находится там же, в корне), находим команду scripts -> start и заменяем значение на:

В дальнейшем для запуска проекта Angular будем использовать команду npm start вместе ng serve. Команда npm start является сокращением для команды, которая указана у вас в package.json.

Шаг третий

Последним шагом будет простая настройка сборки (по команде) проекта в папку wwwroot .NET Core Web API проекта. В открытом файле package.json находим команду scripts -> build и заменяем значение на следующее:

Для выполнения этого действия выполните в терминале команду npm run build. Результатом будет собранные файлы проекта в папке wwwroot.

Настраиваем проект .NET Core Web API

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

Шаг первый

Открываем Startup.cs и добавляем в метод Configure строчки, позволяющие серверу обрабатывать статические файлы:

Шаг второй

В Startup.cs, в метод Configure, добавляем строку, позволяющую серверу принимать запросы с порта 4200:

Шаг третий

В методе ConfigureServices добавляем поддерку CORS:

В конечном итоге файл Startup.cs должен иметь содержимое, которое представлено ниже:

Готово! Теперь вы можете смело обращаться к вашим API контроллерам из Angular проекта. Также, вызвав команду npm run build для Angular проекта, у вас будет версия Web API приложения готовая для деплоя.

Заключение

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

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

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