Ссылка для установки ASP.NET Core Runtime, если еще не установлен (устанавливается с SDK):
Основная часть шагов создания нового проекта уже проделана, однако приведу их здесь, чтобы вы могли создать аналогичный проект по данной инструкции.
Для создания минималистичного Web-сервиса с использование ASP.NET Core необходимо выполнить несколько консольных команд:
- Создадим солюшен
dotnet new sln -o mkn-immisql
- Далее перейдем в директорию созданного солюшена и создадим проект
dotnet new webapi -minimal -o mkn-immisql
- Добавим созданный проект в солюшен
dotnet sln add ./mkn-immisql/mkn-immisql.csproj
После генерации проекта получаем такой вот сгенерированный проектный файл:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<RootNamespace>mkn_immisql</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
</ItemGroup>
</Project>
Я его немного донастроил, опираясь на наши соглашения из первого семестра, и требования для работы с ASP.NET Core. Вы можете менять эти настройки на свое усмотрение, однако если будете использовать nullable, то пишите код в соответсвующем стиле. 10-ая версия языка здесь - минимальное требование. Так же переименовал корневой нэймспейс проекта, чтобы чуть больше соответствовать стилю именования, получилось так:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
<Nullable>disable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
<RootNamespace>MknImmiSql</RootNamespace>
<LangVersion>10</LangVersion>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
</ItemGroup>
</Project>
Далее код был доработан, чтобы соответсвовать новым настройкам и продемонстировать работу с контроллерами.
- [Самостоятельно] Создайте свой проект в отдельной директории и ознакомьтесь с тем как он выглядел в самом начале.
Наш минималистичный проект готов. Можно запускать.
При запуске приложения из Rider'а или студии, оно должно автоматически запускаться в режиме разработчика, что даст вам доступ к Swagger интерфейсу, для отладки ваших endpoint'ов (или "ручек", как их часто называют) вашего web-сервиса.
При запуске из Rider'а эта страница открывается автоматически, если нет, то первым делом смотрим в консоль запущенного приложения, чтобы определить порт на котором запустился сервис:
info: Microsoft.Hosting.Lifetime[14]
Now listening on: https://localhost:7216
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5101
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: K:\.archive\СПбГУ-МКН\2023\23.Б10-МКН\ООП-2\Задания\mkn-immisql\mkn-immisql\
Копируем HTTPS ссылку и добавляем адрес swagger'а, должно получится так:
Открываем страницу в браузере и видим полный список ручек, которые поддерживает ваш сервис. При первом открытии в браузе он наверняка вам сообщит о том, что вы пытаетесь перейти на небезопасный сайт. Это происходит из-за того, что по умолчанию ваш сервис будет использовать самоподписанный сертификат для защиты сетевого подключения по протоколу HTTPS. Смело переходите на опасный сайт либо, если ваш браузер будет каждый раз вам пудрить мозг этим сообщением, тогда можно добавить сертификат разработчика в доверенные на вашей машине. Сделать это можно как описано в инструкции:
Для запуска в Development окружении из консоли необходимо передать приложению аргумент командной строки, вот так:
mkn-immisql.exe --environment Development
Тут все просто, это окружение по умолчанию, потому при запуске вашего приложения из консоли, оно запустится именно в этом режиме.
В нем не будет доступен swagger-интерфейс, что хорошо, т.к. он раскрывает информацию абсолютно по всем ручкам, что поддерживет ваш сервис, даже тех секретных, которые вы не афишируете и используете для внутренних нужд и не выносите в публичный API сервиса.
Хорошей практикой будет запрет на использование swagger-интерфейса в проде.
- Почитать про ASP.Net Core статьи с MSDN.
https://learn.microsoft.com/ru-ru/aspnet/core/getting-started
- Изучите контроллер ExampleController на предмет того, как можно реализовать штатное завершение сервиса через IHostApplicationLifetime.
- Добавьте класс, который будет представлять собой глобальный контекст сервиса. Подумайте какой шаблон проектирования подойдет для этих целей. Примените его. При создании контекста должен сгенерироваться случайный токен, получив который сервис должен завершиться. Генерировать случайные токены удобно, используя метод генерации случайных Guid'ов.
Guid.NewGuid().ToString("N") // можно использовать и другой тип форматирования- Добавить в сервис контроллер TerminateController с POST-ручкой. Данная ручка на вход должна принимать объект с единственным параметром token и типом String. Если переданный токен будет равен тому, что вы сгенерировали при запуске приложения, необходимо остановить сервис, используя способ из (2) и вернуть из ручки Ok (200). Если же токен будет отличаться необходимо вернуть ошибку Forbidden (403).
POST /api/v1/terminate
input
{
"token": "TERMINATION_TOKEN"
}
- Добавьте в ручку выдачи информации (контроллер InfoController) поле TerminationToken которое будет отдавать наружу токен который нужно передать в ручку из (4) для завершения приложения. Безусловно так делать не нужно в продакшене, и такой токен стоит прикапывать в закрытые для внешнего мира хранилища, но для образовательных целей сойдет. Тестовая среда будет использовать данный механизм для завершения сервиса.
- Удалите из приложения ExampleController.
- Перед отправкой исходных кодов на сервер измените в файле mkn-immisql.testlab.json, который размещен рядом с файлом солюшена значение поля stage на 1. Это подскажет тестовой лабе какой набор тестов запускать для вашего приложения.