Vytvoření webového rozhraní API pomocí ASP.NET Core a MongoDB

Pratik Khandelwal a Scott Addie

Tento kurz vytvoří webové rozhraní API, na kterém běží operace Create, Read, Update a Delete (CRUD) v databázi MongoDB NoSQL.

V tomto kurzu se naučíte:

• Konfigurace MongoDB
• Vytvoření databáze MongoDB
• Definování kolekce a schématu MongoDB
• Provádění operací CRUD MongoDB z webového rozhraní API
• Přizpůsobení serializace JSON

Požadavky

• MongoDB 6.0.5 nebo novější
• Prostředí MongoDB

Visual Studio

• Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web

  

Visual Studio Code

• Visual Studio Code
• Jazyk C# pro Visual Studio Code (nejnovější verze)
• Sada .NET 8.0 SDK

V pokynech pro Visual Studio Code se pro vývojové funkce ASP.NET Core, jako je vytvoření projektu, používá .NET CLI. Podle těchto pokynů můžete postupovat v systému macOS, Linux nebo Windows a v jakémkoli editoru kódu. Pokud použijete jiný editor než Visual Studio Code, možná budete muset provést menší změny.

Visual Studio pro Mac

• Visual Studio 2022 pro Mac (nejnovější verze)

  Důležité

  Společnost Microsoft oznámila vyřazení Visual Studio pro Mac. Visual Studio pro Mac již nebudou podporovány od 31. srpna 2024. Mezi alternativy patří:

  • Visual Studio Code se sadou C# Dev Kit a souvisejícími rozšířeními, jako .NET MAUI jsou například Unity.
  • Integrované vývojové prostředí sady Visual Studio spuštěné ve Windows na virtuálním počítači na Macu
  • Integrované vývojové prostředí sady Visual Studio spuštěné ve Windows na virtuálním počítači v cloudu

  Další informace najdete v tématu Visual Studio pro Mac oznámení o vyřazení z provozu.

Konfigurace MongoDB

Povolení přístupu k Prostředí MongoDB a MongoDB odkudkoli na vývojovém počítači (Windows/Linux/macOS):

1. Stáhněte a nainstalujte prostředí MongoDB:

   • macOS/Linux: Zvolte adresář pro extrahování prostředí MongoDB. Přidejte výslednou cestu k mongosh PATH proměnné prostředí.
   • Windows: Prostředí MongoDB (mongosh.exe) je nainstalované v C:\Users<user>\AppData\Local\Programs\mongosh. Přidejte výslednou cestu k mongosh.exe PATH proměnné prostředí.

2. Stáhněte a nainstalujte MongoDB:

   • macOS/Linux: Ověřte adresář, na který se nainstaloval MongoDB, obvykle v adresáři /usr/local/mongodb. Přidejte výslednou cestu k mongodb PATH proměnné prostředí.
   • Windows: MongoDB je ve výchozím nastavení nainstalovaný v C:\Program Files\MongoDB . Do proměnné prostředí přidejte C:\Program Files\MongoDB\Server\<version_number>\binPATH.

3. Zvolte adresář úložiště dat: Vyberte adresář na vývojovém počítači pro ukládání dat. Pokud adresář neexistuje, vytvořte ho. Prostředí MongoDB nevytvoří nové adresáře:

   • macOS/Linux: Například /usr/local/var/mongodb.
   • Windows: Příklad C:\\BooksData: .

4. V příkazovém prostředí operačního systému (ne v Prostředí MongoDB) se pomocí následujícího příkazu připojte k MongoDB na výchozím portu 27017. Nahraďte <data_directory_path> adresářem zvoleným v předchozím kroku.

   mongod --dbpath <data_directory_path>
   

Pomocí dříve nainstalovaného Prostředí MongoDB v následujících krocích vytvořte databázi, vytvořte kolekce a ukládejte dokumenty. Další informace o příkazech prostředí MongoDB najdete v tématu mongosh.

1. Spuštěním příkazu mongosh.exeotevřete instanci příkazového prostředí MongoDB .

2. V příkazovém prostředí se připojte k výchozí testovací databázi spuštěním následujícího příkazu:

   mongosh
   

3. V příkazovém prostředí spusťte následující příkaz:

   use BookStore
   

   Databáze s názvem BookStore se vytvoří, pokud ještě neexistuje. Pokud databáze existuje, otevře se její připojení pro transakce.

4. Vytvořte kolekci Books pomocí následujícího příkazu:

   db.createCollection('Books')
   

   Zobrazí se následující výsledek:

   { "ok" : 1 }
   

5. Pomocí následujícího příkazu definujte schéma kolekce Books a vložte dva dokumenty:

   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" }])
   

   Zobrazí se výsledek podobný následujícímu:

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

   Poznámka:

   Zobrazené ObjectIdv předchozím výsledku se neshodují s těmi, které se zobrazují v příkazovém prostředí.

6. K zobrazení dokumentů v databázi použijte následující příkaz:

   db.Books.find().pretty()
   

   Zobrazí se výsledek podobný následujícímu:

   {
        "_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"
    }
   

   Schéma přidá automaticky vygenerovanou _id vlastnost typu ObjectId pro každý dokument.

Vytvoření projektu webového rozhraní API ASP.NET Core

Visual Studio

1. Přejděte na Soubor>nový>projekt.

2. Vyberte typ projektu základního webového rozhraní API ASP.NET a vyberte Další.

3. Pojmenujte projekt BookStoreApi a vyberte Další.

4. Vyberte architekturu .NET 8.0 (dlouhodobá podpora) a vyberte Vytvořit.

5. V okně konzoly Správce balíčků přejděte do kořenového adresáře projektu. Spuštěním následujícího příkazu nainstalujte ovladač .NET pro MongoDB:

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. V příkazovém prostředí spusťte následující příkazy:

   dotnet new webapi -o BookStoreApi
   code BookStoreApi
   

   Předchozí příkazy vygenerují nový projekt webového rozhraní API ASP.NET Core a pak projekt otevřete v editoru Visual Studio Code.

2. Jakmile se server OmniSharp spustí, dialogové okno se zeptá požadovaných prostředků, aby se sestavily a ladily, chybí v BookStoreApi. Přidejte je?. Vyberte Ano.

3. Otevřete integrovaný terminál a spuštěním následujícího příkazu nainstalujte ovladač .NET pro MongoDB:

   dotnet add package MongoDB.Driver
   

Visual Studio pro Mac

1. Vyberte Soubor>nový projekt....
2. Na bočním panelu vyberte webovou a konzolovou>aplikaci.
3. Vyberte šablonu projektu ASP.NET Core>API v jazyce C# a vyberte Další.
4. V rozevíracím seznamu Cílové rozhraní vyberte .NET 8.0 a pak vyberte Další.
5. Jako název projektu zadejte BookStoreApi a vyberte Vytvořit.
6. Na panelu Řešení klikněte pravým tlačítkem na uzel Závislosti projektu a vyberte Spravovat balíčky NuGet.
7. Do vyhledávacího pole zadejte MongoDB.Driver, vyberte balíček MongoDB.Driver a vyberte Přidat balíček.
8. V dialogovém okně Přijetí licence vyberte tlačítko Přijmout.

Přidání modelu entity

1. Přidejte adresář Models do kořenového adresáře projektu.

2. Book Do adresáře Models přidejte třídu s následujícím kódem:

   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!;
   }
   

   V předchozí třídě Id je vlastnost:

   • Vyžadováno pro mapování objektu CLR (Common Language Runtime) na kolekci MongoDB.
   • Anotováno tak, [BsonId] aby tato vlastnost byla primárním klíčem dokumentu.
   • Anotace s povolením [BsonRepresentation(BsonType.ObjectId)] předání parametru jako typu string místo objektové struktury. Mongo zpracovává převod z string na ObjectId.

   Vlastnost BookName je opatřena poznámkami atributu [BsonElement] . Hodnota atributu Name představuje název vlastnosti v kolekci MongoDB.

Přidání konfiguračního modelu

1. Přidejte následující hodnoty konfigurace databáze do appsettings.json:

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

2. BookStoreDatabaseSettings Do adresáře Models přidejte třídu s následujícím kódem:

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

   Předchozí BookStoreDatabaseSettings třída se používá k uložení appsettings.json hodnot vlastností souboru BookStoreDatabase . Názvy vlastností JSON a C# jsou pojmenované stejně, aby se usnadnil proces mapování.

3. Přidejte následující zvýrazněný kód do Program.cs:

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

   V předchozím kódu je instance konfigurace, na kterou appsettings.json se oddíl souboru BookStoreDatabase sváže, zaregistrována v kontejneru Injektáž závislostí (DI). Například vlastnost objektu BookStoreDatabaseSettings ConnectionString je naplněna BookStoreDatabase:ConnectionString vlastností v appsettings.json.

4. Na začátek Program.cs BookStoreDatabaseSettings odkazu přidejte následující kód:

   using BookStoreApi.Models;
   

Přidání služby operací CRUD

1. Přidejte adresář Služeb do kořenového adresáře projektu.

2. BooksService Do adresáře Services přidejte třídu s následujícím kódem:

   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);
   }
   

   V předchozím kódu BookStoreDatabaseSettings se instance načte z DI prostřednictvím injektáže konstruktoru. Tato technika poskytuje přístup k appsettings.json hodnotám konfigurace, které byly přidány v části Přidat konfigurační model .

3. Přidejte následující zvýrazněný kód do Program.cs:

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

   V předchozím kódu BooksService je třída registrována v di kvůli podpoře injektáže konstruktoru ve spotřebě tříd. Životnost jednoúčelové služby je nejvhodnější, protože BooksService využívá přímou závislost na MongoClient. V souladu s oficiálními pokynyMongoClient pro opakované použití klienta Mongo by se měl zaregistrovat v DI s jednou životností služby.

4. Na začátek Program.cs BooksService odkazu přidejte následující kód:

   using BookStoreApi.Services;
   

Třída BooksService používá následující MongoDB.Driver členy ke spuštění operací CRUD s databází:

• MongoClient: Načte instanci serveru pro spouštění databázových operací. Konstruktor této třídy je k dispozici v MongoDB připojovací řetězec:

  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: Představuje databázi Mongo pro spuštěné operace. Tento kurz používá obecnou metodu GetCollection<TDocument>(collection) v rozhraní k získání přístupu k datům v konkrétní kolekci. Po volání této metody spusťte operace CRUD s kolekcí. GetCollection<TDocument>(collection) Volání metody:

  • collection představuje název kolekce.
  • TDocument představuje typ objektu CLR uložený v kolekci.

GetCollection<TDocument>(collection)vrátí MongoCollection objekt představující kolekci. V tomto kurzu jsou v kolekci vyvolány následující metody:

• DeleteOneAsync: Odstraní jeden dokument odpovídající zadaným kritériím hledání.
• Najít<TDocument>: Vrátí všechny dokumenty v kolekci odpovídající zadaným kritériím hledání.
• InsertOneAsync: Vloží zadaný objekt jako nový dokument v kolekci.
• ReplaceOneAsync: Nahradí jeden dokument odpovídající zadaným kritériím hledání zadaným objektem.

Přidání kontroleru

BooksController Přidejte třídu do adresáře Controllers s následujícím kódem:

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();
    }
}

Předchozí kontroler webového rozhraní API:

• BooksService Používá třídu ke spuštění operací CRUD.
• Obsahuje metody akcí pro podporu požadavků GET, POST, PUT a DELETE HTTP.
• Volání CreatedAtAction v Create metodě akce k vrácení odpovědi HTTP 201 Stavový kód 201 je standardní odpověď pro metodu HTTP POST, která na serveru vytvoří nový prostředek. CreatedAtAction také přidá hlavičku Location do odpovědi. Hlavička Location určuje identifikátor URI nově vytvořené knihy.

Testování webového rozhraní API

1. Sestavte a spusťte aplikaci.

2. Přejděte do https://localhost:<port>/api/booksumístění , kde <port> je automaticky přiřazené číslo portu aplikace, a otestujte metodu akce bez Get parametrů kontroleru, vyberte Vyzkoušet provést>. Zobrazí se odpověď JSON podobná následující:

   [
     {
       "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. Přejděte k https://localhost:<port>/api/books/{id here} otestování přetížené Get metody akce kontroleru. Zobrazí se odpověď JSON podobná následující:

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

Konfigurace možností serializace JSON

V části Test webového rozhraní API je potřeba změnit dvě podrobnosti o odpovědích JSON:

• Výchozí velikost písmen velbloudího jména vlastností by se měla změnit tak, aby odpovídala písmenům pascalu názvů vlastností objektu CLR.
• Vlastnost bookName by měla být vrácena jako Name.

Pokud chcete splnit předchozí požadavky, proveďte následující změny:

1. V Program.cszřetězte následující zvýrazněný kód volání AddControllers metody:

   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);
   

   Při předchozí změně se názvy vlastností v serializované odpovědi JSON webového rozhraní API shodují s odpovídajícími názvy vlastností v typu objektu CLR. Book Například vlastnost třídy Author serializuje jako Author místo author.

2. V Models/Book.cs, anotace BookName vlastnost s atributem [JsonPropertyName] :

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

   Hodnota [JsonPropertyName] atributu Name představuje název vlastnosti v serializované odpovědi JSON webového rozhraní API.

3. Na začátek Models/Book.cs překladu odkazu na [JsonProperty] atribut přidejte následující kód:

   using System.Text.Json.Serialization;
   

4. Opakujte kroky definované v části Test webového rozhraní API . Všimněte si rozdílu v názvech vlastností JSON.

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identity přidává do webových aplikací ASP.NET Core funkce přihlášení uživatelského rozhraní. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

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

Duende Identity Server je architektura OpenID Connect a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

• Ověřování jako služba (AaaS)
• Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
• Řízení přístupu pro rozhraní API
• Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční využití serveru Duende Identity Server. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Identity Serveru (web Duende Software).

Další materiály

• Zobrazení nebo stažení ukázkového kódu (postup stažení)
• Vytváření webových rozhraní API pomocí ASP.NET Core
• Návratové typy akcí kontroleru ve webovém rozhraní API ASP.NET Core
• Vytvoření webového rozhraní API pomocí ASP.NET Core