Übung: Erstellen eines Web-API-Projekts

8 Minuten

In diesem Modul wird das .NET 8.0 SDK verwendet. Stellen Sie sicher, dass .NET 8.0 installiert ist, indem Sie in Ihrem bevorzugten Befehlsterminal den folgenden Befehl ausführen:

dotnet --list-sdks

Die daraufhin angezeigte Ausgabe sieht in etwa wie im folgenden Beispiel aus:

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

Stellen Sie sicher, dass eine Version aufgeführt wird, die mit 8 beginnt. Wenn nichts aufgeführt ist oder der Befehl nicht gefunden wurde, installieren Sie das neueste .NET 8.0 SDK.

Erstellen und Erkunden eines Web-API-Projekts

Wir verwenden Visual Studio Code, um ein .NET-Projekt so einzurichten, dass es mit der Web-API funktioniert. Visual Studio Code enthält ein integriertes Terminal, mit dem das Erstellen eines neuen Projekts ganz einfach ist. Wenn Sie keinen Code-Editor verwenden möchten, können Sie die Befehle in diesem Modul in einem Terminal ausführen.

Klicken Sie in Visual Studio Code auf Datei>Ordner öffnen.
Erstellen Sie am Speicherort Ihrer Wahl einen neuen Ordner namens ContosoPizza, und wählen Sie dann Ordner auswählen.
Öffnen Sie das integrierte Terminal über Visual Studio Code, indem Sie im Hauptmenü auf Ansicht>Terminal klicken.
Kopieren Sie den folgenden Befehl, und fügen Sie ihn in das Terminalfenster ein:
```
dotnet new webapi -controllers -f net8.0
```
Dieser Befehl erstellt die Dateien für ein einfaches Web-API-Projekt, das Controller verwendet, zusammen mit einer C#-Projektdatei namens ContosoPizza.csproj, die eine Liste mit Wettervorhersagen zurückgibt. Wenn ein Fehler auftritt, stellen Sie sicher, dass das .NET 8 SDK installiert ist.

Wichtig

Web-API-Projekte werden standardmäßig durch https geschützt. Wenn Probleme auftreten, konfigurieren Sie das ASP.NET Core HTTPS-Entwicklungszertifikat.

Möglicherweise erhalten Sie eine Aufforderung von Visual Studio Code, Objekte hinzuzufügen, um das Projekt zu debuggen. Wählen Sie im Dialogfeld Ja aus.

Der obige Befehl verwendet eine ASP.NET Core-Projektvorlage mit dem Alias webapi, um ein Gerüst für ein C#-basiertes Web-API-Projekt zu erstellen. Ein Verzeichnis ContosoPizza wird erstellt. Dieses Verzeichnis enthält ein ASP.NET Core, das unter .NET ausgeführt wird. Der Projektname stimmt mit dem Verzeichnisnamen ContosoPizza überein.

Sie sollten jetzt Zugriff auf die folgenden Dateien und Verzeichnisse haben:
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

Untersuchen Sie die folgenden Dateien und Verzeichnisse:

Name	Beschreibung
Controllers/	Enthält Klassen mit öffentlichen Methoden, die als HTTP-Endpunkte zur Verfügung gestellt werden.
Program.cs	Konfiguriert Dienste sowie die HTTP-Anforderungspipeline der App und enthält den verwalteten Einstiegspunkt der App.
ContosoPizza.csproj	Enthält Konfigurationsmetadaten für das Projekt.
ContosoPizza.http	Enthält die Konfiguration zum Testen von REST-APIs direkt aus Visual Studio Code.

Erstellen und Testen der Web-API

Führen Sie den folgenden .NET Core-CLI-Befehl in der Befehlsshell aus:
```
dotnet run
```
Der vorherige Befehl:
- Die Projektdatei wird im aktuellen Verzeichnis gesucht.
- Alle erforderlichen Projektabhängigkeiten werden abgerufen und installiert.
- Der Projektcode wird kompiliert.
- Hostet die Web-API mithilfe des Kestrel-Webservers von ASP.NET Core am HTTP- und HTTPS-Endpunkt.
Für HTTP wird ein Port zwischen 5000 und 5300 und für HTTPS zwischen 7000 und 7300 ausgewählt, wenn das Projekt erstellt wird. Sie können die während der Entwicklung verwendeten Ports problemlos ändern, indem Sie die Datei launchSettings.json des Projekts bearbeiten. Dieses Modul verwendet die sichere localhost-URL, die mit https beginnt.

Sie sollten eine ähnliche Ausgabe wie die folgende erhalten, die angibt, dass Ihre App ausgeführt wird:
```
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7294
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5118 
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development        
```
Wenn Sie diese App auf Ihrem eigenen Computer ausführen, können Sie einen Browser an den in der Ausgabe angezeigten HTTPS-Link (im Fall oben https://localhost:7294) umleiten, um die Seite anzuzeigen. Merken Sie sich diesen Port, weil Sie ihn im gesamten Modul immer dort verwenden, wo {PORT} verwendet wird.

Wichtig

Überprüfen Sie die Terminalausgabe, wenn Sie auf unerwartetes Verhalten stoßen. Wenn der Buildvorgang fehlschlägt oder andere Fehler auftreten, können die Informationen in der Protokolldatei bei der Problembehandlung helfen. Wenn Sie Änderungen am Code vornehmen, müssen Sie die Web-API beenden, indem Sie STRG+C auf der Tastatur auswählen und den Befehl dotnet run erneut ausführen.

Öffnen Sie einen Webbrowser, und navigieren Sie zu:

https://localhost:{PORT}/weatherforecast

Die JSON-Ausgabe sollte folgendem Beispiel entsprechen:

[
    {
    "date": "2021-11-09T20:36:01.4678814+00:00",
    "temperatureC": 33,
    "temperatureF": 91,
    "summary": "Scorching"
    },
    {
    "date": "2021-11-09T20:36:01.4682337+00:00",
    "temperatureC": -8,
    "temperatureF": 18,
    "summary": "Cool"
    },
    // ...
]

Optional: Erkunden mit `.http`-Dateien

Die Datei ContosoPizza.http ist im Projekt enthalten. Sie wird zum Testen von API-Endpunkten über ein Standardformat verwendet. .http-Dateien werden in mehreren integrierten Entwicklungsumgebungen (IDEs) unterstützt, einschließlich Visual Studio und Visual Studio Code, wenn die REST-Clienterweiterung installiert ist.

Öffnen Sie die Datei „ContosoPizza.http“.

Bei manchen IDEs wurde diese Datei mit den @ContosoPizza_HostAddress-Variablen und einem GET-Befehl konfiguriert, der /weatherforecast/ aufruft und application/json akzeptiert.

Wenn sie in Ihrer Datei vorhanden ist, wählen Sie den Befehl Gesendete Anforderung oberhalb des GET-Befehls aus, der eine Anforderung an den ausgeführten Dienst sendet.

Wenn Sie diesen Befehl aufrufen, wird ein Antwortfenster geöffnet, in dem eine Ausgabe angezeigt wird, die ähnlich wie im Browser aussieht:

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Jan 2024 16:46:40 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
    {
        "date": "2024-01-18",
        "temperatureC": -2,
        "temperatureF": 29,
        "summary": "Warm"
    },
    {
        "date": "2024-01-19",
        "temperatureC": 24,
        "temperatureF": 75,
        "summary": "Chilly"
    },
    // ..
]

Optional: Erkunden von APIs mit HTTP REPL der Befehlszeile

Öffnen Siein Visual Studio Code ein neues integriertes Terminal, indem Sie im Hauptmenü Terminal>Neues Terminal auswählen und den folgenden Befehl ausführen:
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
Mit dem vorherigen Befehl wird das .NET-HTTP-REPL-Befehlszeilentool installiert, mit dem HTTP-Anforderungen an die Web-API ausgegeben werden.
Stellen Sie mithilfe des folgenden Befehls eine Verbindung mit der Web-API her:
```
httprepl https://localhost:{PORT}
```
Alternativ können Sie den folgenden Befehl jederzeit ausführen, während HttpRepl ausgeführt wird:
```
connect https://localhost:{PORT}
```
Tipp

Wenn das Tool HttpRepl die Warnung Keine OpenAPI-Beschreibung gefunden ausgibt, ist die wahrscheinlichste Ursache ein nicht vertrauenswürdiges Entwicklungszertifikat. HttpRepl benötigt eine vertrauenswürdige Verbindung. Um fortfahren zu können, müssen Sie das System mit dotnet dev-certs https --trust so konfigurieren, dass das Entwicklungszertifikat als vertrauenswürdig eingestuft wird.
Untersuchen Sie die verfügbaren Endpunkte, indem Sie den folgenden Befehl ausführen:
```
ls
```
Der obige Befehl erkennt alle APIs, die am verbundenen Endpunkt verfügbar sind, und listet sie wie in der folgenden Ausgabe auf:
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
Navigieren Sie zum WeatherForecast-Endpunkt, indem Sie den folgenden Befehl ausführen:
```
cd WeatherForecast
```
Der vorherige Befehl zeigt eine Ausgabe der verfügbaren APIs für den WeatherForecast-Endpunkt an:
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

Senden Sie mithilfe des folgenden Befehls eine GET-Anforderung in HttpRepl:

get

Mit dem Befehl oben wird eine GET-Anforderung ausgegeben, vergleichbar mit dem Navigieren zum Endpunkt im Browser:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 17:31:43 GMT
Server: Kestrel
Transfer-Encoding: chunked
[
    {
    "date": 4/3/2021 10:31:44 AM,
    "temperatureC": 13,
    "temperatureF": 55,
    "summary": "Sweltering"
    },
    {
    "date": 4/4/2021 10:31:44 AM,
    "temperatureC": -13,
    "temperatureF": 9,
    "summary": "Warm"
    },
    // ..
]

Beenden Sie die aktuelle HttpRepl-Sitzung mit dem folgenden Befehl:
```
exit
```
Kehren Sie zum dotnet-Terminal in der Dropdownliste in Visual Studio Code zurück. Fahren Sie die Web-API herunter, indem Sie STRG+C auf der Tastatur drücken.

Nachdem Sie die Web-API erstellt haben, können Sie sie an die Anforderungen der Pizza-Web-API anpassen.

Weiter

Erstellen und Erkunden eines Web-API-Projekts

Erstellen und Testen der Web-API

Optional: Erkunden mit .http-Dateien

Optional: Erkunden von APIs mit HTTP REPL der Befehlszeile

Feedback

Optional: Erkunden mit `.http`-Dateien