Создание веб-API с помощью ASP.NET Core и MongoDB

Авторы Пратик Ханделвал (Pratik Khandelwal) и Скотт Эдди (Scott Addie).

В этом руководстве описано, как создать веб-API, который выполняет операции создания, чтения, обновления и удаления (CRUD) с базой данных NoSQL MongoDB.

В этом руководстве описано следующее:

• настроить MongoDB;
• Создание базы данных MongoDB
• определить коллекцию и схему MongoDB;
• выполнить операции CRUD MongoDB из веб-API.
• Настройка сериализации JSON

Необходимые компоненты

• MongoDB 6.0.5 или более поздней версии
• оболочка MongoDB,

Visual Studio

• Visual Studio 2022 с рабочей нагрузкой ASP.NET и веб-разработка.

  

Visual Studio Code

• Visual Studio Code
• C# для Visual Studio Code (последняя версия)
• Пакет SDK для .NET 8.0

Для функций разработки ASP.NET Core, таких как создание проекта, в инструкциях Visual Studio Code используется .NET CLI. Эти инструкции можно выполнять на macOS, Linux или Windows и в любом редакторе кода. При использовании редактора, отличного от Visual Studio Code, может потребоваться внести незначительные изменения.

Visual Studio для Mac

• Visual Studio 2022 для Mac (последняя версия)

  Внимание

  Корпорация Майкрософт объявила о прекращении работы Visual Studio для Mac. Visual Studio для Mac больше не будет поддерживаться с 31 августа 2024 г. Ниже представлены возможные альтернативы.

  • Visual Studio Code с набором средств разработки C# и связанными расширениями, такими как .NET MAUI и Unity.
  • Интегрированная среда разработки Visual Studio, запущенная в Windows на виртуальной машине Mac.
  • Интегрированная среда разработки Visual Studio, запущенная в Windows на виртуальной машине в облаке.

  Дополнительные сведения см. в Visual Studio для Mac объявлении о выходе на пенсию.

настроить MongoDB;

Включите доступ к Оболочке MongoDB и MongoDB из любого места на компьютере разработки (Windows/Linux/macOS):

1. Скачайте и установите оболочку MongoDB:

   • macOS/Linux: выберите каталог для извлечения оболочки MongoDB в. Добавьте полученный путь к mongosh переменной PATH среды.
   • Windows: Оболочка MongoDB (mongosh.exe) устанавливается в C:\Users<\user>\AppData\Local\Programs\mongosh. Добавьте полученный путь к mongosh.exe переменной PATH среды.

2. Скачайте и установите MongoDB:

   • macOS/Linux: проверьте каталог, по которому был установлен MongoDB, обычно в /usr/local/mongodb. Добавьте полученный путь к mongodb переменной PATH среды.
   • Windows: MongoDB устанавливается в C:\Program Files\MongoDB по умолчанию. Добавьте C:\Program Files\MongoDB\Server\<version_number>\bin в переменную среды PATH.

3. Выберите каталог служба хранилища данных: выберите каталог на компьютере разработки для хранения данных. Если такого каталога нет, создайте его. Оболочка MongoDB не создает новые каталоги:

   • macOS/Linux: например, /usr/local/var/mongodb.
   • Windows: например, C:\\BooksData.

4. В командной оболочке ОС (а не в оболочке MongoDB) используйте следующую команду, чтобы подключиться к MongoDB через порт 27017 по умолчанию. Замените <data_directory_path> каталог, выбранный на предыдущем шаге.

   mongod --dbpath <data_directory_path>
   

В следующих шагах используйте ранее установленный интерфейс MongoDB, чтобы создать базу данных и коллекции и сохранить документы. Дополнительные сведения о командах MongoDB: mongosh.

1. Откройте экземпляр командной оболочки MongoDB, запуская mongosh.exe.

2. В командной оболочке подключитесь к тестовой базе данных по умолчанию, выполнив следующую команду:

   mongosh
   

3. Выполните приведенную ниже команду в командной оболочке.

   use BookStore
   

   Будет создана база данных с именем BookStore, если она не существует. Если такая база данных существует, для нее уже установлено подключение для транзакций.

4. Создайте коллекцию Books с помощью такой команды:

   db.createCollection('Books')
   

   Отобразится такой результат:

   { "ok" : 1 }
   

5. Определите схему для коллекции Books и вставьте два документа, используя следующую команду:

   db.Books.insertMany([{ "Name": "Design Patterns", "Price": 54.93, "Category": "Computers", "Author": "Ralph Johnson" }, { "Name": "Clean Code", "Price": 43.15, "Category": "Computers","Author": "Robert C. Martin" }])
   

   Отобразится примерно такой результат:

   {
       "acknowledged" : true,
       "insertedIds" : [
           ObjectId("61a6058e6c43f32854e51f51"),
           ObjectId("61a6058e6c43f32854e51f52")
        ]
    }
   

   Примечание.

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

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

   db.Books.find().pretty()
   

   Отобразится примерно такой результат:

   {
        "_id" : ObjectId("61a6058e6c43f32854e51f51"),
        "Name" : "Design Patterns",
        "Price" : 54.93,
        "Category" : "Computers",
        "Author" : "Ralph Johnson"
    }
    {
        "_id" : ObjectId("61a6058e6c43f32854e51f52"),
        "Name" : "Clean Code",
        "Price" : 43.15,
        "Category" : "Computers",
        "Author" : "Robert C. Martin"
    }
   

   Схема добавляет автоматически созданное свойство _id типа ObjectId к каждому документу.

Создание проекта веб-API ASP.NET Core

Visual Studio

1. Выберите Файл>Создать>Проект.

2. Выберите тип проекта Веб-API ASP.NET Core и щелкните Далее.

3. Назовите проект BookStoreApi и щелкните Создать.

4. Выберите платформу .NET 8.0 (долгосрочная поддержка) и нажмите кнопку "Создать".

5. В окне Консоль диспетчера пакетов перейдите в корневую папку проекта. Выполните следующую команду, чтобы установить драйвер .NET для MongoDB:

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. В командной оболочке выполните такие команды:

   dotnet new webapi -o BookStoreApi
   code BookStoreApi
   

   Приведенные выше команды создают новый проект веб-API ASP.NET Core, а затем открывают проект в Visual Studio Code.

2. После запуска сервера OmniSharp диалоговое окно запрашивает отсутствие необходимых ресурсов для сборки и отладки из BookStoreApi. Добавьте их?. Выберите Да.

3. Откройте Встроенный терминал и выполните следующую команду, чтобы установить драйвер .NET для MongoDB:

   dotnet add package MongoDB.Driver
   

Visual Studio для Mac

1. Выберите в меню: File (Файл), New Project (Создать проект).
2. Выберите веб-приложение и консольное>приложение на боковой панели.
3. Выберите шаблон проекта C# ASP.NET Core>API и щелкните Далее.
4. Выберите .NET 8.0 в раскрывающемся списке Target Framework и нажмите кнопку "Далее".
5. Введите BookStoreApi в поле Имя проекта и щелкните Создать.
6. На панели решения щелкните правой кнопкой мыши узел зависимостей проекта и выберите пункт "Управление пакетами NuGet".
7. В поле поиска введите MongoDB.Driver, выберите пакет MongoDB.Driver и нажмите Добавить пакет.
8. Нажмите кнопку Принимаю в диалоговом окне Принятие условий лицензионного соглашения.

Добавление модели сущности

1. Добавьте каталог Models в корневую папку проекта.

2. Добавьте класс Book в каталог Models с помощью такого кода:

   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   
   namespace BookStoreApi.Models;
   
   public class Book
   {
       [BsonId]
       [BsonRepresentation(BsonType.ObjectId)]
       public string? Id { get; set; }
   
       [BsonElement("Name")]
       public string BookName { get; set; } = null!;
   
       public decimal Price { get; set; }
   
       public string Category { get; set; } = null!;
   
       public string Author { get; set; } = null!;
   }
   

   В классе выше свойство Id:

   • Требуется для сопоставления объекта среды CLR с коллекцией MongoDB.
   • Помечается с помощью [BsonId] для назначения этого свойства в качестве первичного ключа документа.
   • Помечается с помощью [BsonRepresentation(BsonType.ObjectId)], чтобы разрешить передачу параметра в качестве типа string вместо структуры ObjectId. Mongo обрабатывает преобразование из string в ObjectId.

   Свойство BookName помечено атрибутом [BsonElement]. Значение атрибута Name представляет имя свойства в коллекции MongoDB.

Добавление модели конфигурации

1. Добавьте в файл appsettings.json следующие значения конфигурации базы данных:

   {
       "BookStoreDatabase": {
           "ConnectionString": "mongodb://localhost:27017",
           "DatabaseName": "BookStore",
           "BooksCollectionName": "Books"
       },
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning"
           }
       },
       "AllowedHosts": "*"
   }
   

2. Добавьте класс BookStoreDatabaseSettings в каталог Models с помощью такого кода:

   namespace BookStoreApi.Models;
   
   public class BookStoreDatabaseSettings
   {
       public string ConnectionString { get; set; } = null!;
   
       public string DatabaseName { get; set; } = null!;
   
       public string BooksCollectionName { get; set; } = null!;
   }
   

   Предыдущий класс BookStoreDatabaseSettings используется для хранения значений свойств BookStoreDatabase файла appsettings.json. Свойства JSON и C# имеют одинаковые имена, что упрощает сопоставление.

3. Добавьте выделенный ниже код в Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   

   В предыдущем коде экземпляр конфигурации, к которому привязан раздел BookStoreDatabase файла appsettings.json, зарегистрирован в контейнере внедрения зависимостей (DI). Например, свойство ConnectionString объекта BookStoreDatabaseSettings заполняется свойством BookStoreDatabase:ConnectionString в appsettings.json.

4. Добавьте следующий код в самое начало файла Program.cs, чтобы разрешить ссылку BookStoreDatabaseSettings:

   using BookStoreApi.Models;
   

Добавление службы операций CRUD

1. Добавьте каталог Services в корневую папку проекта.

2. Добавьте класс BooksService в каталог Services с помощью такого кода:

   using BookStoreApi.Models;
   using Microsoft.Extensions.Options;
   using MongoDB.Driver;
   
   namespace BookStoreApi.Services;
   
   public class BooksService
   {
       private readonly IMongoCollection<Book> _booksCollection;
   
       public BooksService(
           IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
       {
           var mongoClient = new MongoClient(
               bookStoreDatabaseSettings.Value.ConnectionString);
   
           var mongoDatabase = mongoClient.GetDatabase(
               bookStoreDatabaseSettings.Value.DatabaseName);
   
           _booksCollection = mongoDatabase.GetCollection<Book>(
               bookStoreDatabaseSettings.Value.BooksCollectionName);
       }
   
       public async Task<List<Book>> GetAsync() =>
           await _booksCollection.Find(_ => true).ToListAsync();
   
       public async Task<Book?> GetAsync(string id) =>
           await _booksCollection.Find(x => x.Id == id).FirstOrDefaultAsync();
   
       public async Task CreateAsync(Book newBook) =>
           await _booksCollection.InsertOneAsync(newBook);
   
       public async Task UpdateAsync(string id, Book updatedBook) =>
           await _booksCollection.ReplaceOneAsync(x => x.Id == id, updatedBook);
   
       public async Task RemoveAsync(string id) =>
           await _booksCollection.DeleteOneAsync(x => x.Id == id);
   }
   

   В предыдущем коде экземпляр BookStoreDatabaseSettings извлекается из DI путем внедрения конструктора. Таким образом обеспечивается доступ к значениям конфигурации в файле appsettings.json, которые были добавлены в разделе Добавление модели конфигурации.

3. Добавьте выделенный ниже код в Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   

   В предыдущем коде класс BooksService регистрируется в DI, чтобы обеспечить поддержку внедрения через конструктор в используемые классы. Время существования отдельной службы — наиболее подходящий вариант, так как BooksService имеет прямую зависимость от MongoClient. В соответствии с официальными правилами повторного использования клиента MongoMongoClient следует регистрировать в DI с использованием времени существования отдельной службы.

4. Добавьте следующий код в самое начало файла Program.cs, чтобы разрешить ссылку BooksService:

   using BookStoreApi.Services;
   

Класс BooksService использует следующие члены MongoDB.Driver для выполнения операций CRUD с базой данных:

• MongoClient — считывает экземпляр сервера для выполнения операций с базой данных. Конструктор этого класса предоставляется в строка подключения MongoDB:

  public BooksService(
      IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
  {
      var mongoClient = new MongoClient(
          bookStoreDatabaseSettings.Value.ConnectionString);
  
      var mongoDatabase = mongoClient.GetDatabase(
          bookStoreDatabaseSettings.Value.DatabaseName);
  
      _booksCollection = mongoDatabase.GetCollection<Book>(
          bookStoreDatabaseSettings.Value.BooksCollectionName);
  }
  

• IMongoDatabase — представляет базу данных Mongo для выполнения операций. В этом руководстве используется универсальный метод GetCollection<TDocument>(collection) интерфейса для получения доступа к данным в определенной коллекции. Выполняйте операции CRUD с коллекцией после вызова этого метода. В вызове метода GetCollection<TDocument>(collection):

  • collection представляет имя коллекции;
  • TDocument представляет тип объекта среды CLR, хранящегося в коллекции;

GetCollection<TDocument>(collection) возвращает объект MongoCollection, представляющий коллекцию. В этом руководстве следующие методы вызываются для коллекции:

• DeleteOne — удаляет один документ, отвечающий заданным критериям поиска.
• Find<TDocument> — возвращает все документы в коллекции, соответствующие заданным критериям поиска.
• InsertOneAsync — вставляет предоставленный объект в виде нового документа в коллекции.
• ReplaceOneAsync — заменяет один документ, отвечающий заданным критериям поиска, предоставленным объектом.

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

Добавьте класс BooksController в каталог Controllers с помощью такого кода:

using BookStoreApi.Models;
using BookStoreApi.Services;
using Microsoft.AspNetCore.Mvc;

namespace BookStoreApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private readonly BooksService _booksService;

    public BooksController(BooksService booksService) =>
        _booksService = booksService;

    [HttpGet]
    public async Task<List<Book>> Get() =>
        await _booksService.GetAsync();

    [HttpGet("{id:length(24)}")]
    public async Task<ActionResult<Book>> Get(string id)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        return book;
    }

    [HttpPost]
    public async Task<IActionResult> Post(Book newBook)
    {
        await _booksService.CreateAsync(newBook);

        return CreatedAtAction(nameof(Get), new { id = newBook.Id }, newBook);
    }

    [HttpPut("{id:length(24)}")]
    public async Task<IActionResult> Update(string id, Book updatedBook)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        updatedBook.Id = book.Id;

        await _booksService.UpdateAsync(id, updatedBook);

        return NoContent();
    }

    [HttpDelete("{id:length(24)}")]
    public async Task<IActionResult> Delete(string id)
    {
        var book = await _booksService.GetAsync(id);

        if (book is null)
        {
            return NotFound();
        }

        await _booksService.RemoveAsync(id);

        return NoContent();
    }
}

Предыдущий контроллер веб-API:

• использует класс BooksService для выполнения операций CRUD;
• содержит методы действий для поддержки запросов HTTP GET, POST, PUT и DELETE.
• Вызывает CreatedAtAction в методе действия Create для возврата ответа HTTP 201. Код состояния 201 представляет собой стандартный ответ метода HTTP POST, создающего ресурс на сервере. CreatedAtAction также добавляет заголовок Location в ответ. Заголовок Location указывает универсальный код ресурса (URI) созданной книги.

Тестирование веб-API

1. Выполните сборку и запустите приложение.

2. Перейдите к https://localhost:<port>/api/booksразделу , где <port> автоматически назначенный номер порта для приложения, чтобы проверить метод действия без параметров Get контроллера, нажмите кнопку "Попробовать выполнить".> Отобразится примерно такой ответ JSON:

   [
     {
       "id": "61a6058e6c43f32854e51f51",
       "bookName": "Design Patterns",
       "price": 54.93,
       "category": "Computers",
       "author": "Ralph Johnson"
     },
     {
       "id": "61a6058e6c43f32854e51f52",
       "bookName": "Clean Code",
       "price": 43.15,
       "category": "Computers",
       "author": "Robert C. Martin"
     }
   ]
   

3. Перейдите по адресу https://localhost:<port>/api/books/{id here}, чтобы протестировать перегруженный метод действия Get контроллера. Отобразится примерно такой ответ JSON:

   {
     "id": "61a6058e6c43f32854e51f52",
     "bookName": "Clean Code",
     "price": 43.15,
     "category": "Computers",
     "author": "Robert C. Martin"
   }
   

Настройка параметров сериализации JSON

Нужно изменить два параметра для возвращаемых ответов JSON в разделе Тестирование веб-API:

• Смешанный регистр имен свойств по умолчанию следует изменить в соответствии с регистром Pascal имен свойств объекта CLR.
• Свойство bookName должно возвращаться как Name.

Чтобы удовлетворить эти требования, внесите следующие изменения:

1. В Program.cs вставьте следующий выделенный код в вызов метода AddControllers:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   
   builder.Services.AddControllers()
       .AddJsonOptions(
           options => options.JsonSerializerOptions.PropertyNamingPolicy = null);
   

   После предыдущего изменения имена свойств в ответе сериализованного JSON веб-API соответствуют именам свойств в типе объекта CLR. Например, свойство Author класса Book сериализуется как Author, а не author.

2. В Models/Book.cs добавьте к свойству BookName атрибут [JsonPropertyName]:

   [BsonElement("Name")]
   [JsonPropertyName("Name")]
   public string BookName { get; set; } = null!;
   

   Атрибут [JsonPropertyName] со значением Name представляет имя свойства в сериализованном ответе веб-API в формате JSON.

3. Добавьте следующий код в самое начало файла Models/Book.cs, чтобы разрешить ссылку на атрибут [JsonProperty]:

   using System.Text.Json.Serialization;
   

4. Повторите действия, описанные в разделе Тестирование веб-API. Обратите внимание на различие в именах свойств JSON.

Добавление поддержки аутентификации в веб-API

ASP.NET Core Identity позволяет использовать функцию входа в пользовательском интерфейсе для веб-приложений ASP.NET Core. Чтобы защитить веб-API и одностраничные приложения, используйте один из следующих способов:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server — это платформа OpenID Connect и OAuth 2.0 для ASP.NET Core. Duende Identity Server включает следующие функции безопасности:

• Проверка подлинности как услуга (AaaS)
• Единый вход (SSO) для нескольких типов приложений
• Контроль доступа для API
• Шлюз федерации

Внимание

Компания Duende Software может потребовать лицензионный сбор за использование Duende IdentityServer в рабочей среде. Дополнительные сведения см. в статье Миграция с ASP.NET Core 5.0 на 6.0.

Дополнительные сведения см. в документации по Duende Identity Server (на веб-сайте ПО Duende).

Дополнительные ресурсы

• Просмотреть или скачать образец кода (описание загрузки)
• Создание веб-API с помощью ASP.NET Core
• Типы возвращаемых действий контроллера в веб-API ASP.NET Core
• Создание веб-API с помощью ASP.NET Core