Как начать работу с ASP.NET для разработки API

ASP.NET — это платформа для создания веб-API с помощью C# и .NET. Он обычно используется для серверных частей приложений и может автоматически сериализовать классы в JSON. Мы рассмотрим настройку службы, которая взаимодействует с базой данных и хранит список объектов.

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

Мы будем использовать Visual Studio, так как она обеспечивает отличную поддержку .NET из коробки. Создайте новый проект, используя шаблон «ASP.NET Core Web Application»:

Дайте ему имя и выберите «API», так как здесь мы не создаем интерфейс ASP.NET.

Это инициализирует ваше решение со всеми шаблонами, необходимыми для запуска и работы базового API. Если вы нажмете кнопку запуска (с надписью IIS Express, которая запускает веб-сервер IIS), вы увидите, что API отображает некоторые фиктивные данные о погоде.

Мы будем использовать эту базу для настройки простого API, который будет подключаться к базе данных и читать и записывать пользовательские объекты. В данном случае это набор пользовательских данных, но API будет в основном работать одинаково для более сложных моделей сущностей.

Подключение базы данных

Хорошая идея — разделить логику обработки запросов и логику обращения к базе данных. Мы создадим службу базы данных с некоторыми функциями для чтения и записи, затем контроллер API, который будет отвечать на запросы, взаимодействуя со службой базы данных. Однако первое, что нужно сделать, это в первую очередь заставить ASP.NET общаться с базой данных.

Нам потребуется установить несколько пакетов для работы с базой данных. Нажмите «Инструменты» > «Диспетчер пакетов NuGet» и выберите «Управление пакетами NuGet для решения».

Если вы используете базу данных SQL, подключение к базе данных обрабатывается с помощью специальных пакетов подключаемых модулей, реализующих EntityFrameworkCore для базовой базы данных. Это платформа, которая сопоставляет объекты C# с реляционной базой данных и позволяет вам использовать запросы LINQ и другие собственные инструменты для взаимодействия с ней. Здесь вы можете найти полный список поставщиков баз данных для наиболее популярных реляционных баз данных.

Здесь мы будем использовать MongoDB, потому что базы данных документов NoSQL довольно легко преобразуются в List<Object>, а драйвер MongoDB поддерживает запросы LINQ почти так же, как EF Core.

Установите пакет MongoDB.Driver:

Создайте новую папку в корне вашего проекта под названием «Модели». В нем создайте модель объекта с именем User.cs, которая будет схемой для коллекции, сохраняемой в базе данных. Вы можете использовать атрибуты [BsonId] и [BsonRepresentation(BsonType.ObjectId)], чтобы сообщить драйверу MongoDB, что эта строка идентификатора должна интерпретироваться как идентификатор коллекции и может передаваться как тип string, хотя внутри Mongo требуется тип ObjectId.

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using System;

namespace ExampleService.Models
{
    public class User
    {
        [BsonId]
        [BsonRepresentation(BsonType.ObjectId)]
        public string Id { get; set; }
        
        [BsonElement("Name")]
        public string Name { get; set; }
        public string Email { get; set; }
        // etc...
    }
}

В этой же папке создайте файл с именем DatabaseSettings.cs, в котором будут храниться класс и интерфейс для настроек базы данных.

namespace ExampleService.Models
{
    public class ExampleDatabaseSettings : IExampleDatabaseSettings
    {
        public string ExampleCollectionName { get; set; }
        public string ConnectionString { get; set; }
        public string DatabaseName { get; set; }
    }

    public interface IExampleDatabaseSettings
    { 
        string ExampleCollectionName { get; set; }
        string ConnectionString { get; set; }
        string DatabaseName { get; set; }
    }
}

Мы можем заполнить эти значения свойств в appsettings.json, добавив следующую конфигурацию:

"ExampleDatabaseSettings": {
    "ExampleCollectionName": "Users",
    "ConnectionString": "mongodb://localhost:27017",
    "DatabaseName": "Example"
}

Вам, конечно, потребуется создать или переименовать базу данных Example, а также создать в ней коллекцию Users.

Наконец, мы добавим некоторый код в Startup.cs в методе ConfigureServices , который будет извлекать настройки из файла appsettings.json и зарегистрировать интерфейс через Dependency Injection:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<ExampleDatabaseSettings>(
      Configuration.GetSection(nameof(ExampleDatabaseSettings)));

    services.AddSingleton<IExampleDatabaseSettings>(sp =>
      sp.GetRequiredService<IOptions<ExampleDatabaseSettings>>().Value);

    services.AddControllers();
}

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

Написание службы базы данных CRUD

Как только база данных подключена, вы можете добавить службу, которая будет говорить. Следующий класс содержит коллекцию IMongoCollection, представляющую коллекцию MongoDB в формате, с которым C# может легко взаимодействовать. Чтение, запись, обновление и удаление будут напрямую влиять на базовую коллекцию.

Метод конструктора принимает настройки базы данных, запускает новый клиент, извлекает базу данных, а затем инициализирует коллекцию _users.

using ExampleService.Models;
using MongoDB.Driver;
using System.Collections.Generic;
using System.Linq;

namespace ExampleService.Services
{
    public class ExampleService
    {
        private readonly IMongoCollection<User> _users;

        public UserService(IExampleDatabaseSettings settings)
        {
            var client = new MongoClient(settings.ConnectionString);
            var database = client.GetDatabase(settings.DatabaseName);

            _users = database.GetCollection<User>(settings.ExampleCollectionName);
        }

        public List<User> Get() =>
            _users.Find(user => true).ToList();

        public User Get(string id) =>
            _users.Find<User>(user => user.Id == id).FirstOrDefault();

        public User Create(User user)
        {
            _users.InsertOne(user);
            return user;
        }

        public void Update(string id, User userIn) =>
            _users.ReplaceOne(user=> user.Id == id, userIn);

        public void Remove(User userIn) =>
            _users.DeleteOne(user => user.Id == userIn.Id);

        public void Remove(string id) => 
            _users.DeleteOne(user=> user.Id == id);
    }
}

Остальная часть класса — это просто набор операций CRUD для взаимодействия с базой данных. Не стесняйтесь реализовывать здесь любую пользовательскую логику.

Вернувшись в Startup.cs, вы захотите добавить это как службу при запуске:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<ExampleDatabaseSettings>(
      Configuration.GetSection(nameof(ExampleDatabaseSettings)));

    services.AddSingleton<IExampleDatabaseSettings>(sp =>
      sp.GetRequiredService<IOptions<ExampleDatabaseSettings>>().Value);

    services.AddSingleton<ExampleService>();

    services.AddControllers();
}

Вам снова понадобится другая директива using, на этот раз для ExampleService.Services.

Настройка контроллера API

Далее вам понадобится контроллер для обработки действий API. К счастью, Visual Studio упрощает эту задачу. вы можете щелкнуть правой кнопкой мыши «Контроллеры», чтобы добавить новый контроллер с действиями чтения/записи. Это создаст новый контроллер с некоторыми основными методами.

Маршрут определяется наверху. По умолчанию установлено значение /api/controller, где контроллер — это имя контроллера (без части «Контроллер»). Вы можете изменить это, если хотите, но это хороший шаблон для большинства людей.

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

Вы захотите добавить ссылку на службу базы данных вверху класса и заполнить ее в конструкторе:

private readonly ExampleService _exampleService;

public ExampleController(ExampleService exampleService)
{
    _exampleService = exampleService;
}

Вам нужно изменить метод HttpGet, чтобы он возвращал ActionResult> схемы, которую вы сохраняете. (Конечно, вам нужно будет добавить ссылку на ваше пространство имен Models.) ActionResult — это динамический тип, который заключает в себе либо значение TValue, либо результат ответа HTTP.

[HttpGet]
public ActionResult<List<User>> Get()
{
    return _exampleService.Get();
}

Если вы хотите добавить еще один метод Get, но на другом маршруте, вы можете передать его как параметр в атрибуте:

[HttpGet("otherroute")]
public ActionResult<List<User>> GetSomeThingElse()
{
    return _exampleService.GetSomeThingElse();
}

Затем для метода HttpPost вызовите метод Create вашей службы базы данных и верните CreatedAtRoute, который отправит клиенту ответ 201, информирующий его об успешном создании объекта.

[HttpPost]
public ActionResult<User> Create(User userIn)
{
    _exampleService.Create(userIn);

    return CreatedAtRoute("GetUser", new { id = userIn.Id.ToString() }, userIn);
}

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

Однако на этом этапе вы должны иметь возможность нажать кнопку запуска IIS Express вверху и протестировать API. По умолчанию в качестве маршрута будет использоваться API погодных служб, поставляемый с шаблоном, поэтому вместо того, чтобы вводить его каждый раз, вы можете изменить маршрут отладки в разделе «Проект» > «Свойства» > «Отладка» и изменить параметр «Запуск браузера».

Если вы хотите протестировать на удаленном сервере, вы можете создать производственную сборку из Build > Publish Service. Выберите выходной файл и отредактируйте конфигурацию в соответствии с вашими потребностями. Например, вы можете выбрать автономную сборку, которая упакует все зависимости .NET вместе со сборкой, а также опубликовать ее как один исполняемый файл. Здесь также можно изменить целевую среду выполнения.

Если вы хотите опубликовать в Linux, вам нужно добавить идентификатор времени выполнения в файл .csproj .

<RuntimeIdentifier>linux-x64</RuntimeIdentifier>

Конечно, представленный здесь API не защищен. ASP.NET имеет отличную систему аутентификации, предлагающую поддержку токенов на основе JWT, и может быть настроена для работы с поставщиками OAuth, такими как Google и Facebook.