練習 - 建立 Web API 專案

已完成

本課程模組使用 .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 包含整合式終端機,可讓建立新專案變得非常簡單。 若不想要使用程式碼編輯器,您可以在終端機中執行本課程模組中的命令。

  1. 在 Visual Studio Code 中,選取 [檔案] > [開啟資料夾]

  2. 在您選擇的位置中建立一個名為 ContosoPizza 的新資料夾,然後選擇 [選取資料夾]。

  3. 從 Visual Studio Code 開啟整合式終端機,做法是從主功能表中選取 [檢視]>[終端機]

  4. 在終端視窗中,複製並貼上下列命令:

    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
    
  5. 檢查下列檔案與目錄:

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

建置並測試 Web API

  1. 在命令殼層中執行下列.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。

  2. 開啟網頁瀏覽器並前往:

    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 檔案。

  1. 開啟 ContosoPizza.http 檔案。

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

  2. 如果它存在於您的檔案中,請選取 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

  1. 藉由從主功能表中選取 [終端機]>[新增終端機],然後執行下列命令,以從 Visual Studio Code 開啟新的整合式終端機:

    dotnet tool install -g Microsoft.dotnet-httprepl
    

    上述命令會安裝 .NET HTTP「讀取、求值、輸出」迴圈 (REPL) 命令列工具,可讓您用來對 Web API 提出 HTTP 要求。

  2. 執行下列命令來連線至 Web API:

    httprepl https://localhost:{PORT}
    

    或者,也可以在 HttpRepl 執行期間的任何時候執行下列命令:

    connect https://localhost:{PORT}
    

    提示

    如果 HttpRepl 工具警告找不到 OpenAPI 描述,最有可能的原因是不受信任的開發憑證。 HttpRepl 需要信任連接。 您必須使用 dotnet dev-certs https --trust 先將系統設定為信任開發憑證,才能繼續執行

  3. 藉由執行下列命令來探索可用的端點:

    ls
    

    上述命令會偵測並列出連線端點上所有可用的 API,如下列輸出所示:

    https://localhost:{PORT}/> ls
    .                 []
    WeatherForecast   [GET] 
    
  4. 執行下列命令,以前往 WeatherForecast 端點:

    cd WeatherForecast
    

    上述命令會顯示 WeatherForecast 端點的可用 API 輸出:

    https://localhost:{PORT}/> cd WeatherForecast
    /WeatherForecast    [GET]
    
  5. 使用下列命令,在 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"
        },
        // ..
    ]
    
  6. 使用下列命令結束目前的 HttpRepl 工作階段:

    exit
    
  7. 返回 Visual Studio Code 中下拉式清單中的 dotnet 終端機。 在鍵盤上選取 CTRL+C 以關閉 Web API。

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