intprog/lw05/README.md

Лабораторная работа №5 - Создание веб-приложения при помощи ASP.NET Core

Цель работы

Получить навыки в создании кросс-платформенного веб-приложения в среде ASP.NET Core при помощи открытых кросс-платформенных инструментов. Освоить принцип проектирования API REST.

Ход работы

1. Установка Visual Studio Code.
2. Установка .NET (Core) SDK.
3. Настройка Visual Studio Code для работы с C# (.NET).
4. Создание ASP-NET-приложения через VS Code.
5. Запуск и отладка C#-приложения в VS Code.
6. Изучение основных концепций ASP.NET Core.
7. Изменение pipeline
8. Подключение Swagger Gen+UI для демонстрации

Прочтите внимательно перед выполнением работы

Для сдачи лабораторной работы необходимо показать работающее приложение, которое способно принимать запросы из браузера.

Установка Visual Studio Code

Visual Studio Code (VS Code) -- кросс-платформенный инструмент для разработки и не только. Очень грубо, VS Code можно считать очень прокаченным блокнотом с кучей плагинов. Плагины при этом могут быть различные: добавление иконок в дерево папок и файлов, добавление поддержки форматирования, отладки и запуска исходного кода, средства доступа к удалённым серверам, возможность работать с контейнерами и т.д.

Скачать и установить Visual Studio Code можно с официального сайта: https://code.visualstudio.com/. При установке можете отказаться от добавления VS Code в контекстное меню и т.д. Единственное, что можете оставить - это добавление в PATH, если это, конечно, будет спрашиваться при установке. Почитать подробнее про PATH можно тут: https://ru.wikipedia.org/wiki/PATH_(%D0%BF%D0%B5%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D0%BD%D0%B0%D1%8F).

Установка .NET (Core) SDK

Перед выполнением этого шага необходимо убедиться: вдруг на Вашем ПК уже установлено необходимое программное обеспечение.

Для этого в консоли или командной строке (для Windows сейчас рекомендуется использовать PowerShell) следует набрать следующую команду:

dotnet --list-sdks

Если вывод будет содержать строку наподобие 8.0.202 [C:\Program Files\dotnet\sdk] и номер версии будет из актуальных, то всё хорошо. В противном случае необходимо произвести установку.

Для этого необходимо установить .NET SDK с официального сайта: https://dotnet.microsoft.com/download.

ASP.NET Core - это платформа для создания веб-приложений, использующих .NET. C# - язык программирования, позволяющий работать с .NET.

После установки SDK под свою систему и возможной перезагрузки компьютера выполните повторно команду из начала раздела. Теперь она должна выводить данные корректно.

Настройка Visual Studio Code для работы с C# (.NET)

Для того, чтобы удобно работать в VS Code с C#, необходимо установить расширение C# Dev Kit.

После установки расширение будет отображаться что-то наподобие следующего:

Создание ASP-NET-приложения через VS Code

Создайте пустую папку где-нибудь на Вашем компьютере. Постарайтесь не использовать в пути до этой папки пробелы и отличные от английских букв и цифр символы.

Откройте эту папку в Visual Studio Code. Для этого выберите пункт меню "Открыть папку" (Open Folder) со стартовой страницы или меню "Файл" (File).

Далее для создания нового C#-приложения нажмите F1. Должна открыться строка команд по середине VC Code сверху. В появившейся строке введите .net new, а затем выберите пункт ".NET: New project..." и нажмите Enter.

После этого выберите тип проекта как "ASP.NET Core Empty".

Далее введите название проекта. Например, IntProgLw5.

На заключительном шаге выберите каталог по умолчанию.

В итоге на экране просмотра файлов в последнем блоке "Solution Explorer" должно быть видно название проекта.

Всё готово к первому запуску и отладке приложения!

Запуск и отладка C#-приложения в VS Code

Пока не вдаваясь в подробности некоторого сгенерированного кода, зайдите в Program.cs, перенесите часть строки с => "Hello world"); на новую и поставьте точку останова в это место.

Для запуска приложения и включения режима отладки необходимо нажать F5.

VS Code может спросить, какой язык и какой проект необходимо отлаживать. Выберите C# и стандартную конфигурацию вашего приложения.

В итоге должен открыться веб-браузер по ссылке http://localhost:5062/ или похожей.

localhost - это домен (адрес) локального ПК. Никто другой Ваш сайт по такому адресу не увидит.

Заметьте, что выполнение программы остановилось в точке останова:

Если у вас всё работает похожим образом, значит всё настроено правильно.

Изучение основных концепций ASP.NET Core

Перед ознакомлением с основами ASP.NET Core, необходимо ознакомиться с основами построения веб-серверов. Как минимум надо вспомнить или узнать, что такое: протокол HTTP, запрос, ответ, тип запроса (GET, POST, PUT, ...) код ответа (200 OK, 404 NOT FOUND, 500, ...), составные части URL (схема, домен, путь, query-string, hash).

После этого можно переходить к основам ASP.NET Core, которые хорошо изложены тут: https://learn.microsoft.com/ru-ru/aspnet/core/introduction-to-aspnet-core#recommended-learning-path.

Однако основные вещи изложу здесь, чтобы не заставлять вас сейчас читать столь сложный для понимания текст.

ASP.NET Core, как и другие современные платформы для построения веб-приложений, использует принцип pipeline - запрос от клиента (браузера) попадает в начало "конвейера", где затем каждый обработчик (практически любая функция на C#) может его или изменить, или пропустить без изменений, или остановить конвейер в зависимости от самого запроса. После прохождения всех обработчиков формируется ответ, который и возвращается клиенту (браузеру).

Визуально это можно изобразить так:

<запрос>         <ответ>
   ↑↑               ↓↓
------------------------
| обработчик 1         |
------------------------
   ↑↑               ↓↓
------------------------
| обработчик 2         |
------------------------
   ↑↑               ↓↓
------------------------
| обработчик 3         |
------------------------

Примеры обработчиков:

• проверка, что запрос клиентом составлен правильно;
• проверка доступа клиента к запрашиваемому ресурсу;
• если по пути из запроса найден файл на веб-сервере, то можно его вернуть;
• а если файл не найден, может какая-то подпрограмма может забрать обработку на себя?
• "Хмм, всё, что начинается с /api, отдавайте мне, остальное мне не надо";
• отрисовка красивых страниц об ошибках (например, 404, 403, 500 и т.д.), если прошлые обработчики сказали, что запрос был плохим;
• обработчик-которые складывает с специальный файл информацию о запросах (логгер или служба/подсистема логирования).

Как видите, обработчиков бывает много, но этот конвейер где-то надо настроить. В ASP.NET Core для этого существуют классы WebApplicationBuilder и WebApplication, использование которых и можно видеть в файле Program.cs нашего проекта.

В нашем простейшем приложении порядок обработчиков примерно такой:

1. (неявно) Если запрос составлен с ошибками, выводить код 400 BAD REQUEST.
2. (неявно) Если приложение выбросило исключение, выводить специальную страницу и код 500 INTERNAL SERVER ERROR.
3. Если поступил GET-запрос на главную страницу (/), то выводится строка Hello World!.

Как видите, пока ничего сложного.

Далее необходимо сопоставить наше веб-приложение (по сути это набор обработчиков запросов) с конкретным веб-сервером. Например, тем самым, что запускает ваше веб-приложение по адресу http://localhost:хххх.

А это делается в строке app.Run();.

В рамках этого руководства не будем вдаваться в подробности того, что спрятано под этой строкой, а также под командой WebApplication.CreateBuilder(args) из начала файла.

Что находится в файлах помимо Program.cs, можете изучить самостоятельно. Дам только наводку, что launchSettings необходим для запуска веб-сервера, а appsettings - для настройки веб-приложения.

Изменение pipeline

После того, как вы научились запускать простейшее веб-приложение для отладки и изучили базовые понятия конвейерной обработки в ASP.NET Core, самое время этот конвейер немного поменять.

Перед вами есть пример обработчика для GET-запросов по пути /.

Предлагается сделать ещё как минимум несколько обработчиков для GET-запросов и проверить в браузере, как они будут работать. Например:

• При GET-запросе /time (через браузер необходимо будет перейти по адресу http://localhost:5000/time) должно выводиться текущее время строкой в формате "ДД.ММ.ГГГГ ЧЧ:ММ.СС", например, "12.04.1961 09:07:00".
• При запросе /whoami должна выводиться информация о текущем браузере.
• При запросе /error должен возвращаться такой код статуса (StatusCode), который придёт из параметра обработчика [FromQuery] int status. Если не придёт, то отдавать код статуса 200 OK. Тогда запрос в адресной строке браузера будет выглядеть примерно как http://localhost:5000/error?status=403 и в этом случае выводить якобы ошибку о том, что нет доступа к ресурсу. В Панели разработчика на вкладке "Сеть" должен возвращаться код из query-параметра.

Для работы с запросом пользователя для получения информации о браузере или параметрах этого запроса следует изучить использование переменной context, которая передаётся в обработчик. Там есть свойство .Request, которое должно Вам помочь.

Подключение Swagger Gen+UI для демонстрации

Как проверить, что новые обработчики работают корректно?

Для этого необходимо установить дополнительную зависимость в приложение и добавить обработчик для отображения нового интерфейса.

Для этого в "Solution Explorer" нажмите правой кнопкой мыши на название проекта (на втором уровне вложенности!) и выберите пункт "Open In Integrated Terminal".

В появившейся командой строке введите команду dotnet add package Swashbuckle.AspNetCore.

Далее в Program.cs до построения приложения builder.Build() добавьте следующие строки:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Этот код добавляет вспомогательные службы для обработчика-генератора контракта нашего API.

Также до app.Run() добавьте следующие строки:

app.UseSwagger();
app.UseSwaggerUI();

Этот код добавляет обработчики для возврата контакта API и интерфейс для просмотра этого контракта.

Чтобы проверить наши обработчики, необходимо при отладке приложения в адресной строке добавить /swagger к адресу сайта. Должна открыться похожая страница:

Пример демонстрации работы query-параметра status в запросе кода ошибки: