Creare un'API Web con ASP.NET Core e MongoDB

Di Pratik Khandelwal e Scott Addie

Questa esercitazione crea un'API Web che esegue operazioni Create, Read, Update e Delete (CRUD) in un database NoSQL mongoDB .

In questa esercitazione apprenderai a:

• Configurare MongoDB
• Creare un database MongoDB
• Definire una raccolta e uno schema MongoDB
• Eseguire operazioni CRUD di MongoDB da un'API Web
• Personalizzare la serializzazione JSON

Prerequisiti

• MongoDB 6.0.5 o versione successiva
• MongoDB Shell

Visual Studio

• Visual Studio 2022 con il carico di lavoro Sviluppo ASP.NET e Web.

  

Visual Studio Code

• Visual Studio Code
• C# Dev Kit per Visual Studio Code
• .NET 9.0 SDK

È possibile seguire le istruzioni di Visual Studio Code in macOS, Linux o Windows. Le modifiche possono essere necessarie se si usa un ambiente di sviluppo integrato (IDE) diverso da Visual Studio Code.

Configurare MongoDB

Abilitare l'accesso alla shell MongoDB e MongoDB da qualsiasi punto del computer di sviluppo (Windows/Linux/macOS):

1. Scaricare e installare MongoDB Shell:

   • macOS/Linux: scegliere una directory in cui estrarre la shell mongoDB. Aggiungere il percorso risultante per mongosh alla PATH variabile di ambiente.
   • Windows: MongoDB Shell (mongosh.exe) è installato in C:\Users<user>\AppData\Local\Programs\mongosh. Aggiungere il percorso risultante per mongosh.exe alla PATH variabile di ambiente.

2. Scaricare e installare MongoDB:

   • macOS/Linux: verificare che la directory in cui MongoDB sia installato, in genere in /usr/local/mongodb. Aggiungere il percorso risultante per mongodb alla PATH variabile di ambiente.
   • Windows: MongoDB è installato in C:\Programmi\MongoDB per impostazione predefinita. Aggiungere C:\Programmi\MongoDB\Server\<version_number>\bin alla PATH variabile di ambiente.

3. Scegliere una directory di archiviazione dati: selezionare una directory nel computer di sviluppo per l'archiviazione dei dati. Creare la directory se non esiste. La shell mongoDB non crea nuove directory:

   • macOS/Linux: ad esempio. /usr/local/var/mongodb
   • Windows: ad esempio. C:\\BooksData

4. Nella shell dei comandi del sistema operativo (non nella shell mongoDB) usare il comando seguente per connettersi a MongoDB sulla porta predefinita 27017. Sostituire <data_directory_path> con la directory scelta nel passaggio precedente.

   mongod --dbpath <data_directory_path>
   

Usare la shell MongoDB installata in precedenza nei passaggi seguenti per creare un database, creare raccolte e archiviare documenti. Per altre informazioni sui comandi della shell mongoDB, vedere mongosh.

1. Aprire un'istanza della shell dei comandi mongoDB avviando mongosh.exe.

2. Nella shell dei comandi connettersi al database di test predefinito eseguendo il comando seguente:

   mongosh
   

3. Eseguire il comando seguente nella shell dei comandi:

   use BookStore
   

   Se non esiste già, viene creato un database denominato BookStore . Se il database esiste, la connessione viene aperta per le transazioni.

4. Creare una raccolta Books tramite il comando seguente:

   db.createCollection('Books')
   

   Viene visualizzato il risultato seguente:

   { "ok" : 1 }
   

5. Definire uno schema per la raccolta Books e inserire due documenti usando il comando seguente:

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

   Viene visualizzato un risultato simile al seguente:

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

   Nota

   I ObjectIdvalori visualizzati nel risultato precedente non corrispondono a quelli visualizzati nella shell dei comandi.

6. Visualizzare i documenti nel database usando il comando seguente:

   db.Books.find().pretty()
   

   Viene visualizzato un risultato simile al seguente:

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

   Lo schema aggiunge una proprietà _id generata automaticamente di tipo ObjectId per ogni documento.

Creare il progetto per l'API Web ASP.NET Core

Visual Studio

1. Passare a File>Nuovo>Progetto.
2. Selezionare il tipo di progetto API Web core ASP.NET e selezionare Avanti.
3. Assegnare al progetto il nome BookStoreApi e selezionare Avanti.
4. Nella finestra di dialogo informazioni aggiuntive:

• Verificare che il di Framework sia .NET 9.0 (supporto standard per termini).
• Verificare che sia selezionata la casella di controllo Usa controller.
• Verificare che sia selezionata la casella di controllo per Abilitare il supporto OpenAPI.
• Selezionare Crea.

1. Nella finestra Console di Gestione pacchetti passare alla radice del progetto. Eseguire il comando seguente per installare il driver .NET per MongoDB:

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. Eseguire i comandi seguenti in una shell dei comandi:

   dotnet new webapi -o BookStoreApi --use-controllers
   code BookStoreApi
   

   I comandi precedenti generano un nuovo progetto API Web di ASP.NET Core e quindi aprono il progetto in Visual Studio Code.

2. Dopo l'avvio del server OmniSharp, una finestra di dialogo richiede che gli asset necessari per la compilazione e il debug non siano presenti in 'BookStoreApi'. Aggiungili?. Selezionare Sì.

3. Aprire il terminale integrato ed eseguire il comando seguente per installare il driver .NET per MongoDB:

   dotnet add package MongoDB.Driver
   

Aggiungere un modello di entità

1. Aggiungere una directory Models alla radice del progetto.

2. Aggiungere una classe Book alla directory Models con il codice seguente:

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

   Nella classe precedente la Id proprietà è:

   • Obbligatorio per eseguire il mapping dell'oggetto Common Language Runtime (CLR) all'insieme MongoDB.
   • Annotato con [BsonId] per impostare questa proprietà sulla chiave primaria del documento.
   • Annotato con [BsonRepresentation(BsonType.ObjectId)] per consentire il passaggio del parametro come tipo string invece di una struttura ObjectId . Mongo gestisce la conversione da string a ObjectId.

   La BookName proprietà viene annotata con l'attributo [BsonElement] . Il valore dell'attributo Name rappresenta il nome della proprietà nella raccolta MongoDB.

Aggiungere un modello di configurazione

1. Aggiungere i valori di configurazione del database seguenti a appsettings.json:

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

2. Aggiungere una classe BookStoreDatabaseSettings alla directory Models con il codice seguente:

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

   La classe precedente BookStoreDatabaseSettings viene usata per archiviare i appsettings.json valori delle proprietà del BookStoreDatabase file. I nomi delle proprietà JSON e C# sono identici per semplificare il processo di mapping.

3. Aggiungere il codice evidenziato seguente a Program.cs:

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

   Nel codice precedente, l'istanza di configurazione a cui viene associata la appsettings.json sezione del BookStoreDatabase file viene registrata nel contenitore Inserimento dipendenze . Ad esempio, la BookStoreDatabaseSettings proprietà dell'oggetto ConnectionString viene popolata con la BookStoreDatabase:ConnectionString proprietà in appsettings.json.

4. Aggiungere il codice seguente all'inizio di Program.cs per risolvere il BookStoreDatabaseSettings riferimento:

   using BookStoreApi.Models;
   

Aggiungere un servizio di operazioni CRUD

1. Aggiungere una directory Services alla radice del progetto.

2. Aggiungere una classe BooksService alla directory Services con il codice seguente:

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

   Nel codice precedente, un'istanza BookStoreDatabaseSettings viene recuperata dall'inserimento delle dipendenze tramite l'inserimento del costruttore. Questa tecnica consente di accedere ai valori di appsettings.json configurazione aggiunti nella sezione Aggiungere un modello di configurazione.

3. Aggiungere il codice evidenziato seguente a Program.cs:

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

   Nel codice precedente la classe BooksService è registrata con l'inserimento di dipendenze per supportare l'inserimento del costruttore nelle classi che la utilizzano. La durata del servizio singleton è più appropriata perché BooksService assume una dipendenza diretta a MongoClient. In base alle linee guida per il riutilizzo di Mongo Client ufficiali, MongoClient deve essere registrato nell'inserimento di dipendenze con una durata del servizio singleton.

4. Aggiungere il codice seguente all'inizio di Program.cs per risolvere il BooksService riferimento:

   using BookStoreApi.Services;
   

La BooksService classe usa i membri seguenti MongoDB.Driver per eseguire operazioni CRUD sul database:

• MongoClient: legge l'istanza del server per l'esecuzione di operazioni di database. Il costruttore di questa classe viene fornito nel stringa di connessione 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: rappresenta il database Mongo per l'esecuzione delle operazioni. Questa esercitazione usa il metodo getCollection<TDocument>(collection) generico sull'interfaccia per ottenere l'accesso ai dati in una raccolta specifica. Eseguire operazioni CRUD sulla raccolta dopo la chiamata di questo metodo. Nella chiamata del metodo GetCollection<TDocument>(collection):

  • collection rappresenta il nome della raccolta.
  • TDocument rappresenta il tipo di oggetto CLR archiviato nella raccolta.

GetCollection<TDocument>(collection) restituisce un oggetto MongoCollection che rappresenta la raccolta. In questa esercitazione, vengono richiamati i metodi seguenti sulla raccolta:

• DeleteOneAsync: elimina un singolo documento corrispondente ai criteri di ricerca specificati.
• Trova<TDocument>: restituisce tutti i documenti nella raccolta che corrispondono ai criteri di ricerca specificati.
• InsertOneAsync: inserisce l'oggetto fornito come nuovo documento nell'insieme.
• ReplaceOneAsync: sostituisce il singolo documento corrispondente ai criteri di ricerca specificati con l'oggetto specificato.

Aggiungere un controller

Aggiungere una classe BooksController alla directory Controllers con il codice seguente:

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

Il controller dell'API Web precedente:

• Usa la BooksService classe per eseguire operazioni CRUD.
• Contiene metodi di azione per supportare le richieste HTTP GET, POST, PUT e DELETE.
• Chiama CreatedAtAction nel metodo dell'azione Create per restituire una risposta HTTP 201. Il codice di stato 201 è la risposta standard per un metodo HTTP POST che crea una nuova risorsa nel server. CreatedAtAction aggiunge anche un'intestazione Location alla risposta. L'intestazione Location specifica l'URI del libro appena creato.

Testare l'API Web

1. Compilare ed eseguire l'app.

2. Passare a https://localhost:<port>/api/books, dove <port> è il numero di porta assegnato automaticamente per l'app, per testare il metodo di azione senza Get parametri del controller, selezionare Prova esegui>. Viene visualizzata una risposta JSON simile alla seguente:

   [
     {
       "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. Passare a https://localhost:<port>/api/books/{id here} per testare il metodo dell'azione Get in overload del controller. Viene visualizzata una risposta JSON simile alla seguente:

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

Configurare le opzioni di serializzazione JSON

Esistono due dettagli da modificare per le risposte JSON restituite nella sezione Testare l'API Web:

• La notazione a cammello predefinita per i nomi di proprietà deve essere modificata in modo da adottare la convenzione Pascal dei nomi di proprietà dell'oggetto CLR.
• La proprietà bookName deve essere restituita come Name.

Per soddisfare i requisiti precedenti, apportare le modifiche seguenti:

1. In Program.cs concatenare il codice evidenziato seguente alla chiamata del metodo 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);
   

   Con la modifica precedente, i nomi delle proprietà nella risposta JSON serializzata dell'API Web corrispondono ai nomi di proprietà corrispondenti nel tipo di oggetto CLR. Ad esempio, la Book proprietà della Author classe serializza come Author anziché author.

2. In Models/Book.csannotare la BookName proprietà con l'attributo [JsonPropertyName] :

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

   Il valore [JsonPropertyName] dell'attributo Name rappresenta il nome della proprietà nella risposta JSON serializzata dell'API Web.

3. Aggiungere il codice seguente all'inizio di Models/Book.cs per risolvere il riferimento all'attributo [JsonProperty] :

   using System.Text.Json.Serialization;
   

4. Ripetere i passaggi definiti nella sezione Testare l'API Web. Si noti la differenza nei nomi di proprietà JSON.

Aggiungere il supporto per l'autenticazione a un'API Web

ASP.NET Core Identity aggiunge funzionalità di accesso dell'interfaccia utente alle app Web core ASP.NET. Per proteggere le API Web e i contratti a pagina singola, usare una delle opzioni seguenti:

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

Duende Identity Server è un framework OpenID Connect e OAuth 2.0 per ASP.NET Core. Duende Identity Server abilita le funzionalità di sicurezza seguenti:

• Autenticazione come servizio (AaaS)
• Single Sign-On/off (SSO) su più tipi di applicazione
• Controllo di accesso per le API
• Gateway federativo

Importante

Duende Software potrebbe richiedere il pagamento di una tariffa di licenza per l'uso in produzione di Duende Identity Server. Per altre informazioni, vedere Eseguire la migrazione da ASP.NET Core 5.0 a 6.0.

Per altre informazioni, vedere la documentazione di Duende Server (sito Web duende Identity Software).

Risorse aggiuntive

• Visualizzare o scaricare il codice di esempio (procedura per il download)
• Creare API Web con ASP.NET Core
• Tipi restituiti dall'azione del controller nell'API Web ASP.NET Core
• Creare un'API Web con ASP.NET Core