練習 - 建立 Web API 專案

8 分鐘

本課程模組使用 .NET 8.0 SDK。確認您已在慣用的命令終端中執行下列命令來安裝 .NET 8.0：

dotnet --list-sdks

類似下列範例的輸出隨即出現：

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

確定已列出開頭為 8 的版本。如果未列出任何項目或找不到命令，請安裝最新的 .NET 8.0 SDK。

建立並探索 Web API 專案

為了設定 .NET 專案以使用 Web API，我們會使用 Visual Studio Code。 Visual Studio Code 包含整合式終端機，可讓建立新專案變得非常簡單。若不想要使用程式碼編輯器，您可以在終端機中執行本課程模組中的命令。

在 Visual Studio Code 中，選取 [檔案] > [開啟資料夾]。
在您選擇的位置中建立一個名為 ContosoPizza 的新資料夾，然後選擇 [選取資料夾]。
從 Visual Studio Code 開啟整合式終端機，做法是從主功能表中選取 [檢視]>[終端機]。
在終端視窗中，複製並貼上下列命令：
```
dotnet new webapi -controllers -f net8.0
```
此命令會為使用控制器的基本 Web API 專案建立檔案，以及名為 ContosoPizza.csproj 的 C# 專案檔，該檔案會傳回氣象預報清單。如果您收到錯誤，確保您已安裝 .NET 8 SDK。

重要

根據預設，Web API 專案會受到 https 保護。如果您有問題，請設定 ASP.NET Core HTTPS 開發憑證。

您可能會收到 Visual Studio Code 的提示，新增資產來對專案進行偵錯。在對話方塊中選取 [是]。

命令會使用 ASP.NET Core 專案範本 (別名為 webapi) 來對 C# 型 Web API 專案進行 Scaffold。隨即會建立 ContosoPizza 目錄。此目錄包含在 .NET 上執行的 ASP.NET Core 專案。專案名稱符合 ContosoPizza 目錄名稱。

您現在應該可以存取這些檔案和目錄：
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

檢查下列檔案與目錄：

名稱	描述
Controllers/	包含公用方法公開為 HTTP 端點的類別。
Program.cs	設定服務和應用程式的 HTTP 要求管線，並包含應用程式的受控進入點。
ContosoPizza.csproj	包含專案的設定中繼資料。
ContosoPizza.http	包含直接從 Visual Studio Code 測試 REST API 的組態。

建置並測試 Web API

在命令殼層中執行下列.NET Core CLI 命令：
```
dotnet run
```
上述命令會：
- 尋找目前目錄中的專案檔。
- 針對這個專案，擷取並安裝任何必要的專案相依性。
- 編譯專案程式碼。
- 在 HTTP 和 HTTPS 端點裝載具有 ASP.NET Core Kestrel Web 服務器的 Web API。
建立專案時，系統會針對 HTTP 選取從 5000 到 5300 的連接埠，並針對 HTTPS 選取從 7000 到 7300 的連接埠。您可以透過編輯專案的 launchSettings.json 檔案，輕鬆地變更您在開發期間使用的連接埠。本課程模組會使用以 https 開頭的安全 localhost URL。

您應該會收到類似下列的輸出，表示您的應用程式正在執行：
```
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        
```
如果您在自己的電腦上執行此應用程式，您可將瀏覽器導向輸出中顯示的 HTTPS 連結 (在先前案例中為 https://localhost:7294) 以檢視所產生的頁面。請記住此連接埠，因為您會在使用 {PORT} 的整個課程模組中使用。

重要

如果遇到任何非預期的行為，請檢查終端機輸出。如果建置失敗或發生其他錯誤，記錄檔的資訊可協助進行疑難排解。當您變更程式碼時，您必須在鍵盤上選取 CTRL+C，然後重新執行 dotnet run 命令，以停止 Web API。

開啟網頁瀏覽器並前往：

https://localhost:{PORT}/weatherforecast

您應該會看到如以下範例所示的 JSON 輸出：

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

選擇性：使用 `.http` 檔案探索

包含在專案中的是 ContosoPizza.http，這個檔案用於透過標準格式測試 API 端點。數個整合式開發環境 (IDE) (包括 Visual Studio) 以及已安裝 REST 用戶端延伸模組的 Visual Studio Code 內部都支援 .http 檔案。

開啟 ContosoPizza.http 檔案。

在某些 IDE 中，此檔案會預先設定 @ContosoPizza_HostAddress 變數和 GET 命令，該命令用於呼叫 /weatherforecast/ 以接受 application/json。

如果它存在於您的檔案中，請選取 GET 上方的 [傳送要求] 命令，以將要求傳送至執行中的服務。

呼叫此命令會開啟回應視窗，其輸出類似於我們在瀏覽器中看到的輸出：

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

選擇性：使用命令行 HTTP REPL 探索 API

藉由從主功能表中選取 [終端機]>[新增終端機]，然後執行下列命令，以從 Visual Studio Code 開啟新的整合式終端機：
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
上述命令會安裝 .NET HTTP「讀取、求值、輸出」迴圈 (REPL) 命令列工具，可讓您用來對 Web API 提出 HTTP 要求。
執行下列命令來連線至 Web API：
```
httprepl https://localhost:{PORT}
```
或者，也可以在 HttpRepl 執行期間的任何時候執行下列命令：
```
connect https://localhost:{PORT}
```
提示

如果 HttpRepl 工具警告找不到 OpenAPI 描述，最有可能的原因是不受信任的開發憑證。 HttpRepl 需要信任連接。您必須使用 dotnet dev-certs https --trust 先將系統設定為信任開發憑證，才能繼續執行
藉由執行下列命令來探索可用的端點：
```
ls
```
上述命令會偵測並列出連線端點上所有可用的 API，如下列輸出所示：
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
執行下列命令，以前往 WeatherForecast 端點：
```
cd WeatherForecast
```
上述命令會顯示 WeatherForecast 端點的可用 API 輸出：
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

使用下列命令，在 HttpRepl 中提出 GET 要求：

get

上述命令會提出 GET 要求，類似於在瀏覽器中前往端點：

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

使用下列命令結束目前的 HttpRepl 工作階段：
```
exit
```
返回 Visual Studio Code 中下拉式清單中的 dotnet 終端機。在鍵盤上選取 CTRL+C 以關閉 Web API。

現在您已建立 Web API，我們可以進行修改以符合披薩 Web API 的需求。

練習 - 建立 Web API 專案

建立並探索 Web API 專案

建置並測試 Web API

選擇性：使用 .http 檔案探索

選擇性：使用命令行 HTTP REPL 探索 API

意見反應

選擇性：使用 `.http` 檔案探索