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

Von Tim Deschryver

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 8.0.0 oder höher
• MongoDB-Shell

Visual Studio

• Die neueste Version von Visual Studio mit der Arbeitslast ASP.NET und Webentwicklung .

  

Visual Studio Code

• Visual Studio Code
• C#Dev Kit für Visual Studio Code
• .NET 10.0 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 den resultierenden Pfad für mongosh zur Umgebungsvariablen PATH hinzu.
   • Windows: MongoDB Shell (mongosh.exe) wird bei C:\Users\{USER NAME}\AppData\Local\Programs\mongosh installiert. Fügen Sie den resultierenden Pfad für mongosh.exe zur Umgebungsvariablen 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 den resultierenden Pfad für mongodb zur Umgebungsvariablen PATH hinzu.
   • Windows: MongoDB wird standardmäßig unter C:\Programme\MongoDB installiert. Fügen Sie der Umgebungsvariable PATH 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:

• Bestätigen Sie, dass Framework.NET 10.0 (Long Term Support) ist.
• Vergewissern Sie sich, dass das Kontrollkästchen für "Controller verwenden " deaktiviert 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
   code BookStoreApi
   

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

2. Ö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 vorstehenden Code wird die Konfigurationsinstanz, an die der Abschnitt appsettings.json der Datei BookStoreDatabase gebunden wird, im Container für die Abhängigkeitsinjektion (DI) 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 Diensts für CRUD-Operationen

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(IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
   {
       private readonly IMongoCollection<Book> _booksCollection = new MongoClient(bookStoreDatabaseSettings.Value.ConnectionString)
           .GetDatabase(bookStoreDatabaseSettings.Value.DatabaseName)
           .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 Singleton-Dienstes ist am geeignetsten, da BooksService eine direkte Abhängigkeit von MongoClient hat. 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 class BooksService(IOptions<BookStoreDatabaseSettings> bookStoreDatabaseSettings)
  {
      private readonly IMongoCollection<Book> _booksCollection = new MongoClient(bookStoreDatabaseSettings.Value.ConnectionString)
          .GetDatabase(bookStoreDatabaseSettings.Value.DatabaseName)
          .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 auf der 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 die 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.

Erstellen von Endpunkten

Ersetzen Sie in der Datei Program.cs das weatherforecast-Beispiel durch die folgenden Endpunkte für Bücher:

var booksGroup = app.MapGroup("/books");

booksGroup.MapGet("/", async (BooksService booksService) =>
{
    var books = await booksService.GetAsync();
    return Results.Ok(books);
});

booksGroup.MapGet("/{id:length(24)}", async (string id, BooksService booksService) =>
{
    var book = await booksService.GetAsync(id);

    return book is null ? Results.NotFound() : Results.Ok(book);
});

booksGroup.MapPost("/", async (Book newBook, BooksService booksService) =>
{
    await booksService.CreateAsync(newBook);

    return Results.Created($"/books/{newBook.Id}", newBook);
});

booksGroup.MapPut("/{id:length(24)}", async (string id, Book updatedBook, BooksService booksService) =>
{
    var book = await booksService.GetAsync(id);

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

    updatedBook.Id = book.Id;

    await booksService.UpdateAsync(id, updatedBook);

    return Results.NoContent();
});

booksGroup.MapDelete("/{id:length(24)}", async (string id, BooksService booksService) =>
{
    var book = await booksService.GetAsync(id);

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

    await booksService.RemoveAsync(id);

    return Results.NoContent();
});

Der vorherige Code:

• Verwendet MapGroup, um alle buchbezogenen Endpunkte zu organisieren, und stellt für alle Endpunkte in der Gruppe das gemeinsame Routenpräfix /books bereit.
• Enthält Endpunkte zur Unterstützung von GET-, POST-, PUT- und DELETE-HTTP-Anforderungen.
• Verwendet die BooksService-Klasse, um CRUD-Vorgänge auszuführen.
• Ruft Created 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. Created 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. Fügen Sie in Program.csden folgenden hervorgehobenen Code hinzu:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.Configure<BookStoreDatabaseSettings>(
       builder.Configuration.GetSection("BookStoreDatabase"));
   
   builder.Services.AddSingleton<BooksService>();
   
   builder.Services.Configure<Microsoft.AspNetCore.Http.Json.JsonOptions>(options =>
   {
       options.SerializerOptions.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 [JsonPropertyName]-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/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}}/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 an, ähnlich wie das folgende:

   [
     {
       "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 /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}}/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}}/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 Antworttext ähnelt der folgenden JSON-Struktur:

   {
     "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 /booksPOST-Endpunkt , und wählen Sie "Anforderung generieren" aus.

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

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

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

    POST {{BookStoreApi_HostAddress}}/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 /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}}/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}}/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 BookStoreApi-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 GET /books-Endpunkt und klicken Sie auf die Schaltfläche 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 /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 /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 erweitern Sie zum Löschen eines Buchdatensatzes den DELETE /books/{id}-Endpunkt, klicken auf Try it out und geben eine der Buch-IDs aus der vorherigen Antwort in das id-Feld 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
• 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 Service (AaaS)
• 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 in der Dokumentation zu Duende Identity Server (Website von Duende Software).

Verwandte Inhalte

• 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 minimalen Web-API mit ASP.NET Core