開始使用 ASP.NET Web API 2 (C#)

發行項
07/13/2023

作者：Mike Wasson

在本教學課程中，您將使用 ASP.NET Web API建立會傳回產品清單的 Web API。

HTTP 不只用於提供網頁。 HTTP 也是一個功能強大的平臺，可用來建置公開服務和資料的 API。 HTTP 是簡單、彈性且普遍的。您幾乎可以想像的任何平臺都有 HTTP 程式庫，因此 HTTP 服務可以觸達廣泛的用戶端，包括瀏覽器、行動裝置和傳統傳統型應用程式。

ASP.NET Web API是建置.NET Framework上 Web API 的架構。

教學課程中使用的軟體版本

Visual Studio 2017
Web API 2

如需本教學課程的較新版本，請參閱使用 ASP.NET Core 和 Visual Studio for Windows 建立 Web API。

建立 Web API 專案

在本教學課程中，您將使用 ASP.NET Web API建立會傳回產品清單的 Web API。前端網頁會使用 jQuery 來顯示結果。

本機主機瀏覽器視窗的螢幕擷取畫面，其中顯示範例專案，其中包含產品清單、其價格，以及依 I D 欄位和按鈕搜尋。

啟動 Visual Studio，然後從 [開始] 頁面選取 [新增專案]。或者，從 [ 檔案] 功能表中，選取 [ 新增 ]，然後選取 [ 專案]。

在 [ 範本] 窗格中，選取 [已安裝的範本 ]，然後展開 [Visual C# ] 節點。在 [Visual C#] 底下，選取 [Web]。在專案範本清單中，選取 [ASP.NET Web 應用程式]。將專案命名為「ProductsApp」，然後按一下 [ 確定]。

[新增專案] 範本選項的螢幕擷取畫面，其中醒目提示建立新專案的步驟和選取專案。

在 [ 新增 ASP.NET 專案 ] 對話方塊中，選取 [空白 ] 範本。在 [新增資料夾和核心參考] 底下，檢查 Web API。按一下 [確定]。

[新增專案] 對話方塊的螢幕擷取畫面，其中包含不同的範本選項，以及資料夾和核心參考的三個選項。

注意

您也可以使用「Web API」範本來建立 Web API 專案。 Web API 範本會使用 ASP.NET MVC 來提供 API 說明頁面。我正在使用本教學課程的空白範本，因為我想要在沒有 MVC 的情況下顯示 Web API。一般而言，您不需要知道 ASP.NET MVC 才能使用 Web API。

新增模型

「模型」是代表您應用程式中資料的物件。 ASP.NET Web API可以將模型自動序列化為 JSON、XML 或其他格式，然後將序列化的資料寫入 HTTP 回應訊息的本文。只要用戶端可以讀取序列化格式，就可以還原序列化物件。大部分用戶端都可以剖析 XML 或 JSON。此外，用戶端可以藉由在 HTTP 要求訊息中設定 Accept 標頭來指出其想要的格式。

讓我們從建立代表產品的簡單模型開始。

如果沒有顯示 [方案總管]，請按一下 [檢視] 功能表，然後選取 [方案總管]。在 [方案總管] 中，於 Models 資料夾上按一下滑鼠右鍵。從操作功能表中，選取 [新增]，然後選取 [類別]。

方案總管功能表的螢幕擷取畫面，其中顯示 models 資料夾中的選項，顯示如何新增類別。

將類別命名為「Product」。將下列屬性新增至 Product 類別。

namespace ProductsApp.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

新增控制器

在 Web API 中，控制器是處理 HTTP 要求的物件。我們將新增控制器，以傳回產品清單或識別碼所指定的單一產品。

注意

如果您已使用 ASP.NET MVC，您已經熟悉控制器。 Web API 控制器類似于 MVC 控制器，但繼承 ApiController 類別，而不是 Controller 類別。

在 [方案總管] 中，於 Controllers 資料夾上按一下滑鼠右鍵。選取 [新增]，然後選取 [控制器]。

方案總管功能表的螢幕擷取畫面，其中顯示將控制器類別新增至專案的視覺指引。

在 [新增 Scaffold] 對話方塊中，選取 [Web API 控制器 - 空白]。按一下 [新增] 。

顯示 [新增 Scaffold] 對話方塊功能表選項的螢幕擷取畫面，其中醒目提示 Web A P I 控制器 - 空白選項。

在 [ 新增控制器] 對話方塊中，將控制器命名為「ProductsController」。按一下 [新增] 。

[新增控制器] 對話方塊的螢幕擷取畫面，將欄位方塊中的「產品控制器」一詞後，以及其下方的 [新增] 按鈕。

Scaffolding 會在 Controllers 資料夾中建立名為 ProductsController.cs 的檔案。

方案總管功能表選項的螢幕擷取畫面，將新建立的選項串連在 [控制器] 資料夾中，稱為「產品控制器點 C S」。

注意

您不需要將控制器放入名為 Controllers 的資料夾。資料夾名稱只是組織來源檔案的便利方式。

如果此檔案尚未開啟，請按兩下檔案將它開啟。將此檔案中的程式碼取代為下列專案：

using ProductsApp.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Web.Http;

namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, 
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, 
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } 
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

為了保持範例簡單，產品會儲存在控制器類別內的固定陣列中。當然，在實際應用程式中，您會查詢資料庫或使用一些其他外部資料源。

控制器會定義兩個傳回產品的方法：

方法 GetAllProducts 會將整個產品清單傳回為IEnumerable < Product >類型。
方法 GetProduct 會依識別碼查閱單一產品。

就這麼簡單！您有運作中的 Web API。控制器上的每個方法都會對應至一或多個 URI：

Controller 方法	URI
GetAllProducts	/api/products
GetProduct	/api/products/id

GetProduct針對方法，URI 中的識別碼是預留位置。例如，若要取得識別碼為 5 的產品，URI 為 api/products/5 。

如需 Web API 如何將 HTTP 要求路由至控制器方法的詳細資訊，請參閱ASP.NET Web API 中的路由。

使用 JAVAscript 和 jQuery 呼叫 Web API

在本節中，我們將新增使用 AJAX 來呼叫 Web API 的 HTML 頁面。我們將使用 jQuery 進行 AJAX 呼叫，以及以結果更新頁面。

在方案總管中，以滑鼠右鍵按一下專案，然後選取 [新增]，然後選取 [新增專案]。

方案總管功能表的螢幕擷取畫面，其中醒目提示 [產品] 應用程式選項以顯示其功能表選取專案以新增專案。

在 [新增專案] 對話方塊中，選取[Visual C#] 下的[Web] 節點，然後選取[HTML 頁面]專案。將頁面命名為「index.html」。

[新增專案] 功能表選項的螢幕擷取畫面，其中顯示 Web 選取專案及其內可用的選項。

將此檔案中的所有內容取代為下列專案：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>

  <div>
    <h2>All Products</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>Search by ID</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>

  <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';

    $(document).ready(function () {
      // Send an AJAX request
      $.getJSON(uri)
          .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
              // Add a list item for the product.
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });

    function formatItem(item) {
      return item.Name + ': $' + item.Price;
    }

    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
          });
    }
  </script>
</body>
</html>

您可以使用幾種方式來取得 jQuery。在此範例中，我使用了 Microsoft Ajax CDN。您也可以從 http://jquery.com/ 下載它，而 ASP.NET 「Web API」專案範本也包含 jQuery。

取得產品清單

若要取得產品清單，請將 HTTP GET 要求傳送至「/api/products」。

jQuery getJSON 函式會傳送 AJAX 要求。回應包含 JSON 物件的陣列。函 done 式會指定回呼，如果要求成功，就會呼叫該回呼。在回呼中，我們會使用產品資訊來更新 DOM。

$(document).ready(function () {
    // Send an AJAX request
    $.getJSON(apiUrl)
        .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
                // Add a list item for the product.
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

依識別碼取得產品

若要依識別碼取得產品，請將 HTTP GET 要求傳送至「/api/products/id」，其中 id 是產品識別碼。

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
        });
}

我們仍會呼叫 getJSON 來傳送 AJAX 要求，但這次我們會將識別碼放在要求 URI 中。此要求的回應是單一產品的 JSON 標記法。

執行應用程式

按 F5 開始對應用程式進行偵錯。網頁看起來應該如下所示：

網頁瀏覽器的螢幕擷取畫面，其中顯示所有產品專案符號表單及其價格，後面接著 [依 I D 搜尋] 欄位。

若要依識別碼取得產品，請輸入識別碼，然後按一下 [搜尋]：

瀏覽器的螢幕擷取畫面，其中顯示所有產品和價格、以專案符號形式顯示，以及 [依 I D 搜尋] 欄位中的數位 2。

如果您輸入不正確識別碼，伺服器會傳回 HTTP 錯誤：

瀏覽器的螢幕擷取畫面，列出所有產品及其價格，並在 [依 I D 搜尋] 欄位底下顯示「找不到」錯誤訊息。

使用 F12 檢視 HTTP 要求和回應

當您使用 HTTP 服務時，查看 HTTP 要求和回應訊息會非常有用。您可以在 Internet Explorer 9 中使用 F12 開發人員工具來執行此動作。從 Internet Explorer 9，按 F12 開啟工具。按一下 [ 網路] 索引標籤，然後按 [開始擷取]。現在返回網頁，然後按 F5 重載網頁。 Internet Explorer 會擷取瀏覽器與網頁伺服器之間的 HTTP 流量。摘要檢視會顯示頁面的所有網路流量：

H T T P 要求和回應訊息視窗的螢幕擷取畫面，其中顯示 U R L 的清單，以及所有網路流量回應。

找出相對 URI 「api/products/」的專案。選取此專案，然後按一下 [移至詳細檢視]。在詳細資料檢視中，有索引標籤可檢視要求和回應標頭和主體。例如，如果您按一下 [ 要求標頭 ] 索引標籤，您可以看到用戶端在 Accept 標頭中要求「application/json」。

H T T P 要求和回應訊息對話方塊的螢幕擷取畫面，其中顯示個別 A P I 要求回應的範例。

如果您按一下 [回應本文] 索引標籤，您可以看到產品清單如何序列化為 JSON。其他瀏覽器具有類似的功能。另一個有用的工具是 Fiddler，這是 Web 偵錯 Proxy。您可以使用 Fiddler 來檢視 HTTP 流量，以及撰寫 HTTP 要求，這可讓您完全控制要求中的 HTTP 標頭。

查看此應用程式在 Azure 上執行

您要看到以即時 Web 應用程式身分執行的已完成網站嗎？您可以將應用程式的完整版本部署至您的 Azure 帳戶。

您需要 Azure 帳戶，才能將此解決方案部署至 Azure。如果您還沒有帳戶，您有下列選項：

免費開啟 Azure 帳戶 - 您可以取得可用來試用付費 Azure 服務的點數，即使已用完，您仍可保留帳戶並使用免費的 Azure 服務。
啟用 MSDN 訂閱者權益 - 您的 MSDN 訂用帳戶每月提供您可用於付費 Azure 服務的點數。

後續步驟

如需支援 POST、PUT 和 DELETE 動作和寫入資料庫之 HTTP 服務的更完整範例，請參閱搭配 Entity Framework 6 使用 Web API 2。
如需在 HTTP 服務之上建立流暢且回應式 Web 應用程式的詳細資訊，請參閱 ASP.NET 單頁應用程式。
如需如何將 Visual Studio Web 專案部署至Azure App 服務的相關資訊，請參閱在 Azure App 服務中建立 ASP.NET Web 應用程式。