Erstellen einer Web-API mit ASP.NET Core und MongoDB

Von Pratik Khandelwal und Scott Addie

Dieses Tutorial erstellt eine Web-API, die CRUD-Vorgänge (Create, Read, Update, Delete) für eine MongoDB-NoSQL-Datenbank durchführt.

In diesem Tutorial lernen Sie, wie die folgenden Aufgaben ausgeführt werden:

• Konfigurieren von MongoDB
• Erstellen einer MongoDB-Datenbank
• Definieren einer MongoDB-Sammlung und eines Schemas
• Ausführen von MongoDB-CRUD-Vorgänge über eine Web-API
• Anpassen der JSON-Serialisierung

Prerequisites

• MongoDB 6.0.5 oder höher
• MongoDB-Shell

Visual Studio

• Visual Studio 2022 mit der Workload ASP.NET und Webentwicklung

  

Visual Studio Code

• Visual Studio Code
• C#Dev Kit für Visual Studio Code
• .NET 9 SDK

Sie können den Visual Studio Code-Anweisungen unter macOS, Linux oder Windows folgen. Änderungen können erforderlich sein, wenn Sie eine andere integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) als Visual Studio Code verwenden.

Konfigurieren von MongoDB

Aktivieren Sie den Zugriff von MongoDB und MongoDB Shell von überall auf dem Entwicklungscomputer (Windows/Linux/macOS):

1. MongoDB Shell herunterladen und installieren:

   • macOS/Linux: Wählen Sie ein Verzeichnis aus, in das die MongoDB-Shell extrahiert werden soll. Fügen Sie der mongosh-Umgebungsvariablen den resultierenden Pfad für PATH hinzu.
   • Windows: MongoDB Shell (mongosh.exe) wird unter C:\Users\user<\>AppData\Local\Programs\mongosh installiert. Fügen Sie der mongosh.exe-Umgebungsvariablen den resultierenden Pfad für PATH hinzu.

2. MongoDB herunterladen und installieren:

   • macOS/Linux: Überprüfen Sie das Verzeichnis, unter dem MongoDB installiert wurde, in der Regel in /usr/local/mongodb. Fügen Sie der mongodb-Umgebungsvariablen den resultierenden Pfad für PATH hinzu.
   • Windows: MongoDB wird standardmäßig unter C:\Programme\MongoDB installiert. Fügen Sie der Umgebungsvariablen < den Pfad > hinzu.

3. Wählen Sie ein Datenspeicherverzeichnis aus: Wählen Sie ein Verzeichnis auf Ihrem Entwicklungscomputer zum Speichern von Daten aus. Erstellen Sie das Verzeichnis, falls es nicht vorhanden ist. Die MongoDB Shell erstellt keine neuen Verzeichnisse:

   • macOS/Linux: Zum Beispiel /usr/local/var/mongodb.
   • Windows: Zum Beispiel C:\\BooksData.

4. Verwenden Sie in der Befehlsshell des Betriebssystems (nicht in der MongoDB-Shell) den folgenden Befehl, um eine Verbindung mit MongoDB am Standardport 27017 herzustellen. Ersetzen Sie <data_directory_path> durch das im vorherigen Schritt ausgewählte Verzeichnis.

   mongod --dbpath <data_directory_path>
   

Verwenden Sie die zuvor installierte MongoDB-Shell in den folgenden Schritten, um eine Datenbank zu erstellen, Sammlungen durchzuführen und Dokumente zu speichern. Weitere Informationen zu MongoDB-Shell-Befehlen finden Sie unter mongosh.

1. Öffnen Sie eine MongoDB-Befehlsshellinstanz, indem Sie starten mongosh.exeoder den folgenden Befehl in der Befehlsshell ausführen:

   mongosh
   

2. Stellen Sie in der Befehlsshell eine Verbindung mit der Standardtestdatenbank her, indem Sie Folgendes ausführen:

   use BookStore
   

   Wenn nicht bereits vorhanden, wird eine Datenbank namens BookStore erstellt. Wenn die Datenbank vorhanden ist, wird die Verbindung für Transaktionen geöffnet.

3. Erstellen Sie eine Books-Sammlung mithilfe des folgenden Befehls:

   db.createCollection('Books')
   

   Das folgende Ergebnis wird angezeigt:

   { "ok" : 1 }
   

4. Definieren Sie ein Schema für die Books-Sammlung. und fügen zwei Dokumente mithilfe des folgenden Befehls ein:

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

   Das Ergebnis sieht in etwa wie folgt aus:

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

   Note

   Die im vorherigen Ergebnis angezeigten ObjectIds stimmen nicht mit denen überein, die in der Befehlsshell angezeigt werden.

5. Zeigen Sie die Dokumente in der Datenbank mithilfe des folgenden Befehls an:

   db.Books.find().pretty()
   

   Das Ergebnis sieht in etwa wie folgt aus:

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

   Das Schema fügt eine automatisch generierte _id Eigenschaft vom Typ ObjectId für jedes Dokument hinzu.

Erstellen eines ASP.NET Core-Web-API-Projektes

Visual Studio

1. Wechseln Sie zu Datei>Neu>Projekt.
2. Wählen Sie den Projekttyp ASP.NET Core-Web-API aus, und klicken Sie auf Weiter.
3. Geben Sie dem Projekt den Namen BookStoreApi, und klicken Sie auf Weiter.
4. Im Dialogfeld Zusätzliche Informationen:

• Vergewissern Sie sich, dass das Framework auf .NET 9.0 (Standard-Support) festgelegt ist.
• Vergewissern Sie sich, dass das Kontrollkästchen für "Controller verwenden" aktiviert ist.
• Stellen Sie sicher, dass das Kontrollkästchen für OpenAPI-Unterstützung aktivieren aktiviert ist.
• Wählen Sie "Erstellen" aus.

1. Navigieren Sie im Fenster Paket-Manager-Konsole zum Stammverzeichnis des Projekts. Führen Sie den folgenden Befehl aus, um den .NET-Treiber für MongoDB zu installieren:

   Install-Package MongoDB.Driver
   

Visual Studio Code

1. Führen Sie die folgenden Befehle in einer Befehlsshell aus:

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

   Die obigen Befehle generieren ein neues ASP.NET Core-Web-API-Projekt und öffnen dann das Projekt in Visual Studio Code.

2. Nachdem der OmniSharp-Server gestartet wurde, wird eine Meldung ähnlich der folgenden angezeigt: In „BookStoreApi“ fehlen erforderliche Ressourcen zum Erstellen und Debuggen. Add them? (Sollen sie hinzugefügt werden?). Wählen Sie Ja aus.

3. Öffnen Sie das integrierte Terminal, und führen Sie den folgenden Befehl aus, um den .NET-Treiber für MongoDB zu installieren:

   dotnet add package MongoDB.Driver
   

Hinzufügen eines Entitätsmodells

1. Fügen Sie zum Stammverzeichnis des Projekts ein Verzeichnis Modelle hinzu.

2. Fügen Sie eine Book-Klasse zum Verzeichnis Modelle mit dem folgenden Code hinzu:

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

   In der obigen Klasse gilt für die Id-Eigenschaft Folgendes:

   • Sie ist erforderlich, um der MongoDB-Sammlung das CLR-Objekt (Common Language Runtime) zuzuordnen.
   • Sie wird mit [BsonId] kommentiert, um diese Eigenschaft als Primärschlüssel des Dokuments festzulegen.
   • Sie wird mit [BsonRepresentation(BsonType.ObjectId)] kommentiert, um die Übergabe des Parameters als Typ string anstelle einer ObjectId-Struktur zu ermöglichen. Mongo behandelt die Konvertierung von string zu ObjectId.

   Die Eigenschaft BookName ist mit dem Attribut [BsonElement] versehen. Der Wert Name des Attributs stellt den Eigenschaftsnamen in der MongoDB-Sammlung dar.

Hinzufügen eines Konfigurationsmodells

1. Fügen Sie appsettings.json die folgenden Konfigurationswerte für die Datenbank hinzu:

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

2. Fügen Sie eine BookStoreDatabaseSettings-Klasse zum Verzeichnis Modelle mit dem folgenden Code hinzu:

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

   Mit der vorhergehenden Klasse BookStoreDatabaseSettings werden die Eigenschaftswerte appsettings.json der Datei BookStoreDatabase gespeichert. Die Namen der JSON- und der C#-Eigenschaften sind identisch, um den Zuordnungsprozess zu erleichtern.

3. Fügen Sie folgenden hervorgehobenen Code zu Program.cs hinzu:

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

   Im obigen Code wird die Konfigurationsinstanz, an die der Abschnitt appsettings.json der Datei BookStoreDatabase gebunden ist, beim DI-Container (Dependency Injection) registriert. Beispielsweise wird die Eigenschaft BookStoreDatabaseSettings des ConnectionString-Objekts mit der Eigenschaft BookStoreDatabase:ConnectionString in appsettings.json aufgefüllt.

4. Fügen Sie den folgenden Code am Anfang von Program.cs hinzu, um den Verweis BookStoreDatabaseSettings aufzulösen:

   using BookStoreApi.Models;
   

Hinzufügen eines CRUD-Vorgangsdiensts

1. Fügen Sie zum Stammverzeichnis des Projekts ein Verzeichnis Dienste hinzu.

2. Fügen Sie eine BooksService-Klasse zum Verzeichnis Dienste mit dem folgenden Code hinzu:

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

   Im vorhergehenden Code wird eine BookStoreDatabaseSettings-Instanz mittels Konstruktorinjektion über DI abgerufen. Damit kann auf die Konfigurationswerte von appsettings.json zugegriffen werden, die im Abschnitt Hinzufügen eines Konfigurationsmodells hinzugefügt wurden.

3. Fügen Sie folgenden hervorgehobenen Code zu Program.cs hinzu:

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

   Im vorhergehenden Code wird die Klasse BooksService bei DI registriert, um die Konstruktorinjektion in verarbeitenden Klassen zu unterstützen. Die Lebensdauer des Singletondiensts ist am besten geeignet, da BooksService direkt von MongoClient abhängig ist. Gemäß den offiziellen Mongo Client-Richtlinien zur Wiederverwendung (Mongo Client reuse guidelines) sollte MongoClient bei DI mit der Lebensdauer eines Singletondiensts registriert werden.

4. Fügen Sie den folgenden Code am Anfang von Program.cs hinzu, um den Verweis BooksService aufzulösen:

   using BookStoreApi.Services;
   

Die BooksService-Klasse verwendet die folgenden MongoDB.Driver-Member, um CRUD-Vorgänge für die Datenbank auszuführen:

• MongoClient: Liest die Serverinstanz zum Ausführen von Datenbankvorgängen. Der Konstruktor dieser Klasse wird in der MongoDB-Verbindungszeichenfolge bereitgestellt:

  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: Stellt die Mongo-Datenbank zum Ausführen von Vorgängen dar. In diesem Tutorial wird die generische Methode GetCollection<TDocument>(collection) für die Schnittstelle verwendet, um Zugriff auf Daten in einer bestimmten Sammlung zu erhalten. Führen Sie CRUD-Vorgänge für die Sammlung aus, nachdem diese Methode aufgerufen wurde. Rufen Sie in der GetCollection<TDocument>(collection)-Methode folgendes auf:

  • collection steht für den Sammlungsnamen.
  • TDocument steht für den in der Sammlung gespeicherten CLR-Objekttypen.

GetCollection<TDocument>(collection) gibt ein MongoCollection-Objekt zurück, das die Sammlung darstellt. In diesem Tutorial werden die folgenden Methoden für der Sammlung aufgerufen:

• DeleteOneAsync: Löscht ein einzelnes Dokument, das den angegebenen Suchkriterien entspricht.
• Find<TDocument>: Gibt alle Dokumente in der Sammlung zurück, die den angegebenen Suchkriterien entsprechen.
• InsertOneAsync: Fügt das angegebene Objekt als neues Dokument in die Sammlung ein.
• ReplaceOneAsync: Ersetzt das einzelne Dokument, das den angegebenen Suchkriterien entspricht, durch das angegebene Objekt.

Hinzufügen eines Controllers

Fügen Sie eine BooksController-Klasse zum Verzeichnis Controller mit dem folgenden Code hinzu:

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

Der oben aufgeführte Web-API-Controller:

• Verwendet die BooksService-Klasse, um CRUD-Vorgänge auszuführen.
• Enthält Aktionsmethoden zur Unterstützung von GET-, POST-, PUT- und DELETE HTTP-Anforderungen.
• Ruft CreatedAtAction in der Aktionsmethode Create auf, um eine HTTP 201-Antwort zurückzugeben. Der Statuscode 201 ist die Standardantwort für eine HTTP POST-Methode, die eine neue Ressource auf dem Server erstellt. CreatedAtAction fügt der Antwort außerdem einen Location-Header hinzu. Der Location-Header gibt den URI des neu erstellten Buchs an.

Konfigurieren von JSON-Serialisierungsoptionen

Es gibt zwei Details, die bei JSON-Antworten zu ändern sind, die im Abschnitt Testen der Web-API zurückgegeben werden:

• Die Camel-Case-Standardschreibweise von Eigenschaftsnamen sollte so geändert werden, dass sie der Pascal-Schreibweise der Eigenschaften des CLR-Objekts entspricht.
• Die Eigenschaft bookName sollte als Name zurückgegeben werden.

Um die zuvor genannten Anforderungen zu erfüllen, nehmen Sie die folgenden Änderungen vor:

1. Verketten Sie in Program.cs den folgenden hervorgehobenen Code mit dem Aufruf der AddControllers-Methode:

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

   Durch die vorherige Änderung stimmen Eigenschaftsnamen in der serialisierten JSON-Antwort der Web-API mit ihren entsprechenden Eigenschaftsnamen im CLR-Objekttyp überein. Beispielsweise wird die Eigenschaft Book der Author-Klasse als Author und nicht als author serialisiert.

2. Kommentieren Sie in Models/Book.cs die BookName-Eigenschaft mit dem [JsonPropertyName]-Attribut:

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

   Der Wert [JsonPropertyName] des Name-Attributs stellt den Eigenschaftsnamen in der serialisierten JSON-Antwort der Web-API dar.

3. Fügen Sie den folgenden Code am Anfang von Models/Book.cs hinzu, um den Verweis auf das [JsonProperty]-Attribut aufzulösen:

   using System.Text.Json.Serialization;
   

4. Wiederholen Sie die im Abschnitt Testen der Web-API definierten Schritte. Beachten Sie den Unterschied bei den JSON-Eigenschaftsnamen.

Testen der Web-API

Visual Studio

In diesem Tutorial werden der Endpoints Explorer und .http-Dateien verwendet, um die API zu testen.

1. Erstellen Sie die App, und führen Sie sie aus.

2. Klicken Sie im Endpunkt-Explorer mit der rechten Maustaste auf den ersten GET-Endpunkt/api/books, und wählen Sie "Anforderung generieren" aus.

   Der folgende Inhalt wird der BookStoreApi.http Datei hinzugefügt. Wenn dies das erste Mal ist, dass eine Anforderung generiert wird, wird die Datei im Projektstamm erstellt.

   @BookStoreApi_HostAddress = https://localhost:<port>
   
   GET {{BookStoreApi_HostAddress}}/api/books
   
   ###
   

   Die Portnummer sollte bereits auf den von der App verwendeten Port festgelegt werden, https://localhost:56874z. B. . Wenn dies nicht der Fall ist, können Sie beim Starten der App Ihre Portnummer im Ausgabefenster finden.

3. Wählen Sie den Link " Anfrage senden" oberhalb der neuen GET Anforderungszeile aus.

   Die GET-Anforderung wird an die App gesendet, und die Antwort wird im Bereich Antwort angezeigt.

4. Der Antworttext zeigt das JSON-Ergebnis mit den Bucheinträgen, ähnlich wie das Folgende, an:

   [
     {
       "Id": "61a6058e6c43f32854e51f51",
       "Name": "Design Patterns",
       "Price": 54.93,
       "Category": "Computers",
       "Author": "Ralph Johnson"
     },
     {
       "Id": "61a6058e6c43f32854e51f52",
       "Name": "Clean Code",
       "Price": 43.15,
       "Category": "Computers",
       "Author": "Robert C. Martin"
     }
   ]
   

5. Um ein einzelnes Buch abzurufen, klicken Sie mit der rechten Maustaste auf den /api/books/{id}, params (string id)GET-Endpunkt im Endpunkt-Explorer, und wählen Sie " Anforderung generieren" aus.

   Der folgende Inhalt wird an die BookStoreApi.http Datei angefügt:

   @id=string
   GET {{BookStoreApi_HostAddress}}/api/books/{{id}}
   
   ###
   

6. Ersetzen Sie id die Variable durch eine der IDs, die von der früheren Anforderung zurückgegeben werden, z. B.:

   @id="61a6058e6c43f32854e51f52"
   GET {{BookStoreApi_HostAddress}}/api/books/{{id}}
   
   ###
   

7. Wählen Sie den Link " Anfrage senden" oberhalb der neuen GET Anforderungszeile aus.

   Die GET-Anforderung wird an die App gesendet, und die Antwort wird im Bereich Antwort angezeigt.

8. Der Antwortinhalt zeigt JSON, das ähnlich wie folgt ist:

   {
     "Id": "61a6058e6c43f32854e51f52",
     "Name": "Clean Code",
     "Price": 43.15,
     "Category": "Computers",
     "Author": "Robert C. Martin"
   }
   

9. Um den POST-Endpunkt zu testen, klicken Sie mit der rechten Maustaste auf den /api/booksPOST-Endpunkt , und wählen Sie "Anforderung generieren" aus.

   Der folgende Inhalt wird der Datei BookStoreApi.http hinzugefügt:

   POST {{BookStoreApi_HostAddress}}/api/books
   Content-Type: application/json
   
   {
     //Book
   }
   
   ###
   

10. Ersetzen Sie den Book-Kommentar durch ein Buchobjekt als JSON-Anforderungstext:

    POST {{BookStoreApi_HostAddress}}/api/books
    Content-Type: application/json
    
     {
       "Name": "The Pragmatic Programmer",
       "Price": 49.99,
       "Category": "Computers",
       "Author": "Andy Hunt"
     }
    
    ###
    

11. Wählen Sie den Link " Anfrage senden" oberhalb der Anforderungszeile POST aus.

    Die POST-Anforderung wird an die App gesendet, und die Antwort wird im Antwortbereich angezeigt. Die Antwort sollte das neu erstellte Buch mit der zugewiesenen ID enthalten.

12. Zum Löschen eines Buchs klicken Sie mit der rechten Maustaste auf den /api/books/{id}, params (string id)DELETE-Endpunkt , und wählen Sie " Anforderung generieren" aus.

    Der folgende Inhalt wird an die BookStoreApi.http Datei angefügt:

    DELETE {{BookStoreApi_HostAddress}}/api/Books/{{id}}
    
    ###
    

13. Ersetzen Sie die id Variable durch eine der IDs, die von der früheren Anforderung zurückgegeben werden, und klicken Sie auf " Anforderung senden". Beispiel:

    DELETE {{BookStoreApi_HostAddress}}/api/Books/67f417517ce1b36aeab71236
    
    ###
    

Visual Studio Code

In diesem Lernprogramm werden die OpenAPI-Spezifikation (openapi.json) und die Swagger-BEnutzeroberfläche verwendet, um die API zu testen.

1. Installieren Sie die Benutzeroberfläche von Swagger, indem Sie den folgenden Befehl ausführen:

dotnet add package NSwag.AspNetCore

Der obige Befehl fügt das Paket NSwag.AspNetCore hinzu, das Tools zum Generieren von Swagger-Dokumenten und der Benutzeroberfläche enthält. Da unser Projekt OpenAPI verwendet, verwenden wir nur das NSwag-Paket, um die Swagger UI zu generieren.

1. Konfigurieren von Swagger-Middleware

Fügen Sie in Program.csden folgenden hervorgehobenen Code hinzu:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}

Der vorherige Code ermöglicht die Swagger-Middleware für die Bereitstellung des generierten JSON-Dokuments mithilfe der Swagger UI. Swagger wird nur in einer Entwicklungsumgebung aktiviert. Das Aktivieren von Swagger in einer Produktionsumgebung könnte potenziell vertrauliche Details zur Struktur und Implementierung der API offenlegen.

Die App verwendet das von OpenApi generierte OpenAPI-Dokument, das sich in /openapi/v1.jsonbefindet, um die Benutzeroberfläche zu generieren. Zeigen Sie die generierte OpenAPI-Spezifikation für die WeatherForecast-API an, während das Projekt ausgeführt wird, indem Sie zu https://localhost:<port>/openapi/v1.json in Ihrem Browser navigieren.

Die OpenAPI-Spezifikation ist ein Dokument im JSON-Format, das die Struktur und Funktionen Ihrer API beschreibt, einschließlich Endpunkten, Anforderungs-/Antwortformaten, Parametern und mehr. Es ist im Wesentlichen eine Blaupause Ihrer API, die von verschiedenen Tools verwendet werden kann, um Ihre API zu verstehen und mit ihr zu interagieren.

1. Erstellen Sie die App, und führen Sie sie aus.

2. Navigieren Sie in Ihrem Browser zu https://localhost:<port>/swagger. Swagger stellt eine Benutzeroberfläche bereit, um alle API-Endpunkte basierend auf dem OpenAPI-Dokument zu testen.

3. Erweitern Sie den Endpunkt "GET /api/books" und klicken Sie auf den Button "Ausprobieren".

4. Klicken Sie auf die Schaltfläche "Ausführen ", um die Anforderung an die API zu senden.

5. Der Abschnitt "Antworttext " zeigt ein JSON-Array mit Büchern wie den folgenden an:

   [
     {
       "Id": "61a6058e6c43f32854e51f51",
       "Name": "Design Patterns",
       "Price": 54.93,
       "Category": "Computers",
       "Author": "Ralph Johnson"
     },
     {
       "Id": "61a6058e6c43f32854e51f52",
       "Name": "Clean Code",
       "Price": 43.15,
       "Category": "Computers",
       "Author": "Robert C. Martin"
     }
   ]
   

6. Erweitern Sie als Nächstes den GET /api/books/{id} -Endpunkt, und klicken Sie auf "Ausprobieren".

7. Geben Sie eine der Buch-IDs aus der vorherigen Antwort im Id-Feld ein, und klicken Sie dann auf "Ausführen".

8. Im Abschnitt "Antworttext " wird das JSON-Objekt für das angegebene Buch angezeigt. Das Ergebnis für die ID 61a6058e6c43f32854e51f52 ähnelt z. B. folgendem:

   {
     "Id": "61a6058e6c43f32854e51f52",
     "Name": "Clean Code",
     "Price": 43.15,
     "Category": "Computers",
     "Author": "Robert C. Martin"
   }
   

9. Um das Erstellen eines neuen Buchs zu testen, erweitern Sie den POST /api/books-Endpunkt und klicken Sie auf Ausprobieren.

10. Ersetzen Sie den Standardanforderungstext durch ein neues Buchobjekt:

    {
      "Name": "The Pragmatic Programmer",
      "Price": 49.99,
      "Category": "Computers",
      "Author": "Andy Hunt"
    }
    

11. Klicken Sie auf "Ausführen" , um die Anforderung zu senden.

12. Die Antwort sollte über einen Statuscode von 201 (Erstellt) verfügen und das neu erstellte Buch mit der zugewiesenen ID im Antworttext einschließen.

13. Abschließend, um einen Buchdatensatz zu löschen, erweitern Sie den DELETE /api/books/{id} Endpunkt, klicken Sie auf "Try it out" und geben Sie eine der Buch-IDs aus der vorherigen Antwort im Feld "id" ein. Klicken Sie auf "Ausführen" , um die Anforderung zu senden.

14. Die Antwort sollte über einen Statuscode von 204 (Kein Inhalt) verfügen, der angibt, dass das Buch erfolgreich gelöscht wurde.

Hinzufügen der Authentifizierungsunterstützung zu einer Web-API

ASP.NET Core Identity fügt Benutzeroberflächen-Anmeldefunktionen zu ASP.NET Core-Web-Apps hinzu. Verwenden Sie zum Sichern von Web-APIs und SPAs eine der folgenden Optionen:

• Microsoft Entra-ID
• Der Duende Identity Server

Duende Identity Server ist ein OpenID Connect- und OAuth 2.0-Framework für ASP.NET Core. Duende Identity Server ermöglicht die folgenden Sicherheitsfeatures:

• Authentifizierung als Dienst
• Einmaliges Anmelden und einmaliges Abmelden für mehrere Anwendungstypen
• Zugriffssteuerung für APIs
• Föderationsgateway

Important

Duende Software erhebt ggf. eine Lizenzgebühr für die Nutzung von Duende Identity Server in der Produktion. Weitere Informationen finden Sie unter Migrieren von ASP.NET Core in .NET 5 zu .NET 6.

Weitere Informationen finden Sie in der Dokumentation zu Duende Identity Server (Website von Duende Software).

Weitere Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Erstellen von Web-APIs mit ASP.NET Core
• Rückgabetypen von Controlleraktion in ASP.NET Core-Web-API
• Erstellen einer Web-API mit ASP.NET Core