Ćwiczenie — tworzenie projektu internetowego interfejsu API

8 min

W tym module jest używany zestaw .NET 8.0 SDK. Upewnij się, że masz zainstalowany program .NET 8.0, uruchamiając następujące polecenie w preferowanym terminalu poleceń:

dotnet --list-sdks

Zostanie wyświetlone dane wyjściowe podobne do następującego przykładu:

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

Upewnij się, że na liście znajduje się wersja rozpoczynająca się od 8 . Jeśli żadna z nich nie znajduje się na liście lub polecenie nie zostanie znalezione, zainstaluj najnowszy zestaw SDK platformy .NET 8.0.

Tworzenie i eksplorowanie projektu internetowego interfejsu API

Aby skonfigurować projekt platformy .NET do pracy z internetowym interfejsem API, używamy programu Visual Studio Code. Program Visual Studio Code zawiera zintegrowany terminal, który ułatwia tworzenie nowego projektu. Jeśli nie chcesz używać edytora kodu, możesz uruchomić polecenia w tym module w terminalu.

W programie Visual Studio Code wybierz pozycję File (Plik)>Open Folder (Otwórz folder).
Utwórz nowy folder o nazwie ContosoPizza w wybranej lokalizacji, a następnie wybierz pozycję Wybierz folder.
Otwórz zintegrowany terminal z programu Visual Studio Code, wybierając pozycję View (Widok)>Terminal z menu głównego.
Skopiuj następujące polecenie i wklej je w oknie terminalu:
```
dotnet new webapi -controllers -f net8.0
```
To polecenie tworzy pliki dla podstawowego projektu internetowego interfejsu API, który używa kontrolerów wraz z plikiem projektu C# o nazwie ContosoPizza.csproj , który zwraca listę prognoz pogody. Jeśli wystąpi błąd, upewnij się, że masz zainstalowany zestaw .NET 8 SDK .

Ważne

Projekty internetowego interfejsu API są domyślnie zabezpieczone https . Jeśli masz problemy, skonfiguruj certyfikat dewelopera ASP.NET Core HTTPS.

Może zostać wyświetlony monit z programu Visual Studio Code o dodanie zasobów w celu debugowania projektu. Wybierz pozycję Tak w oknie dialogowym.

Polecenie używa aliasu szablonu projektu ASP.NET Core jako webapi szkieletu projektu internetowego interfejsu API opartego na języku C#. Zostanie ContosoPizza utworzony katalog. Ten katalog zawiera projekt ASP.NET Core uruchomiony na platformie .NET. Nazwa projektu jest zgodna z nazwą katalogu ContosoPizza.

Teraz należy mieć dostęp do tych plików i katalogów:
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

Przyjrzyj się następującym plikom i katalogom:

Nazwa/nazwisko	opis
Controllers/	Zawiera klasy z metodami publicznymi uwidocznionymi jako punkty końcowe HTTP.
Program.cs	Konfiguruje usługi i potok żądania HTTP aplikacji oraz zawiera zarządzany punkt wejścia aplikacji.
ContosoPizza.csproj	Zawiera metadane konfiguracji projektu.
ContosoPizza.http	Zawiera konfigurację do testowania interfejsów API REST bezpośrednio z poziomu programu Visual Studio Code.

Kompilowanie i testowanie internetowego interfejsu API

Uruchom następujące polecenie interfejsu wiersza polecenia platformy .NET Core w powłoce poleceń:
```
dotnet run
```
Poprzednie polecenie:
- Lokalizuje plik projektu w bieżącym katalogu.
- Pobiera i instaluje wszystkie wymagane zależności projektu dla tego projektu.
- Kompiluje kod projektu.
- Hostuje internetowy interfejs API za pomocą serwera internetowego ASP.NET Core Kestrel zarówno w punkcie końcowym HTTP, jak i HTTPS.
Port z zakresu od 5000 do 5300 jest wybierany dla protokołu HTTP, a od 7000 do 7300 dla protokołu HTTPS po utworzeniu projektu. Porty używane podczas programowania można łatwo zmienić, edytując plik launchSettings.json projektu. W tym module jest używany bezpieczny localhost adres URL rozpoczynający się od https.

Powinny zostać wyświetlone dane wyjściowe podobne do następujących, co wskazuje, że aplikacja jest uruchomiona:
```
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        
```
Jeśli używasz tej aplikacji na własnej maszynie, możesz kierować przeglądarkę do linku HTTPS wyświetlanego w danych wyjściowych (w poprzednim przypadku https://localhost:7294), aby wyświetlić wynikową stronę. Pamiętaj ten port, ponieważ używasz go w całym module, w którym {PORT} jest używany.

Ważne

Sprawdź dane wyjściowe terminalu, jeśli wystąpi nieoczekiwane zachowanie. Jeśli kompilacja zakończy się niepowodzeniem lub wystąpią inne błędy, informacje pliku dziennika ułatwiają rozwiązywanie problemów. Podczas wprowadzania zmian w kodzie należy zatrzymać internetowy interfejs API, wybierając CTRL+C na klawiaturze i ponownie uruchamiając dotnet run polecenie.

Otwórz przeglądarkę internetową i przejdź do:

https://localhost:{PORT}/weatherforecast

Powinny zostać wyświetlone dane wyjściowe JSON podobne do tego przykładu:

[
    {
    "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"
    },
    // ...
]

Opcjonalnie: Eksplorowanie za pomocą `.http` plików

W projekcie znajduje się contosoPizza.http , plik używany do testowania punktów końcowych interfejsu API za pomocą standardowego formatu. .http pliki są obsługiwane w kilku zintegrowanych środowiskach projektowych (IDE), w tym w programie Visual Studio i w programie Visual Studio Code z zainstalowanym rozszerzeniem klienta REST.

Otwórz plik ContosoPizza.http.

W niektórych środowiskach IDE ten plik jest wstępnie skonfigurowany za pomocą zmiennych @ContosoPizza_HostAddress i polecenia GET wywołującego polecenie /weatherforecast/ , które akceptuje plik application/json.

Jeśli znajduje się on w pliku, wybierz polecenie Wysłane żądanie powyżej polecenia GET , które wysyła żądanie do uruchomionej usługi.

Wywołanie tego polecenia otwiera okno odpowiedzi z danymi wyjściowymi podobnymi do tego, co widzieliśmy w przeglądarce:

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"
    },
    // ..
]

Opcjonalnie: Eksplorowanie interfejsów API przy użyciu protokołu REPL HTTP wiersza polecenia

Otwórz nowy zintegrowany terminal z programu Visual Studio Code, wybierając pozycję Terminal>Nowy terminal z menu głównego, a następnie uruchom następujące polecenie:
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
Poprzednie polecenie instaluje narzędzie wiersza polecenia .NET HTTP Read-Eval-Print Loop (REPL) używane do wykonywania żądań HTTP do internetowego interfejsu API.
Połącz się z internetowym interfejsem API, uruchamiając następujące polecenie:
```
httprepl https://localhost:{PORT}
```
Alternatywnie uruchom następujące polecenie w dowolnym momencie, gdy HttpRepl jest uruchomione:
```
connect https://localhost:{PORT}
```
Napiwek

HttpRepl Jeśli narzędzie wyświetli ostrzeżenie Nie można odnaleźć opisu interfejsu OpenAPI, najbardziej prawdopodobną przyczyną jest niezaufany certyfikat programowania. HttpRepl wymaga zaufanego połączenia. Przed kontynuowaniem należy skonfigurować system tak, aby ufał certyfikatowi deweloperskiemudotnet dev-certs https --trust
Zapoznaj się z dostępnymi punktami końcowymi, uruchamiając następujące polecenie:
```
ls
```
Poprzednie polecenie wykrywa wszystkie interfejsy API dostępne w połączonym punkcie końcowym i wyświetla je w następujący sposób:
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
Przejdź do punktu końcowego WeatherForecast , uruchamiając następujące polecenie:
```
cd WeatherForecast
```
Poprzednie polecenie przedstawia dane wyjściowe dostępnych interfejsów API dla punktu końcowego WeatherForecast :
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

GET Utwórz żądanie za HttpRepl pomocą następującego polecenia:

get

Poprzednie polecenie wysyła GET żądanie podobne do przechodzenia do punktu końcowego w przeglądarce:

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"
    },
    // ..
]

Zakończ bieżącą HttpRepl sesję przy użyciu następującego polecenia:
```
exit
```
Wróć do terminalu na dotnet liście rozwijanej w programie Visual Studio Code. Zamknij internetowy interfejs API, wybierając CTRL+C na klawiaturze.

Po utworzeniu internetowego interfejsu API możemy zmodyfikować go tak, aby spełniał wymagania internetowego interfejsu API pizzy.

Ćwiczenie — tworzenie projektu internetowego interfejsu API

Tworzenie i eksplorowanie projektu internetowego interfejsu API

Kompilowanie i testowanie internetowego interfejsu API

Opcjonalnie: Eksplorowanie za pomocą .http plików

Opcjonalnie: Eksplorowanie interfejsów API przy użyciu protokołu REPL HTTP wiersza polecenia

Opinia

Opcjonalnie: Eksplorowanie za pomocą `.http` plików