WCF Web HTTP 程式設計模型概觀

發行項
01/29/2025

Windows Communication Foundation （WCF） WEB HTTP 程式設計模型提供使用 WCF 建置 WEB HTTP 服務所需的基本元素。 WCF WEB HTTP 服務的設計目的是要由最廣泛的可能用戶端存取，包括網頁瀏覽器，並具有下列獨特的需求：

URI 和 URI 處理 URI 在 WEB HTTP 服務的設計中扮演著核心角色。 WCF WEB HTTP 程式設計模型會使用 UriTemplate 和 UriTemplateTable 類別來提供 URI 處理功能。
支援 GET 和 POST 作業 WEB HTTP 服務利用 GET 動詞進行數據擷取，並使用各種用於數據修改和遠端調用的動詞。 WCF WEB HTTP 程式設計模型會使用 WebGetAttribute 和 WebInvokeAttribute，將服務作業與 PUT、POST 和 DELETE 等其他 HTTP 動詞命令產生關聯。
除了 SOAP 訊息之外，多個數據格式 Web 樣式服務會處理許多種類的數據。 WCF WEB HTTP 程式設計模型會使用 WebHttpBinding 和 WebHttpBehavior 來支援許多不同的數據格式，包括 XML 檔、JSON 資料物件，以及二進位內容的數據流，例如影像、視訊檔案或純文本。

WCF WEB HTTP 程式設計模型延伸 WCF 的範圍，以涵蓋 Web HTTP 服務、AJAX 和 JSON 服務，以及新聞訂閱（ATOM/RSS）摘要的 Web 樣式案例。如需 AJAX 和 JSON 服務的詳細資訊，請參閱 AJAX 整合和 JSON 支援。如需有關內容分發的詳細資訊，請參閱 WCF 內容分發概觀。

可從 WEB HTTP 服務傳回的資料類型沒有額外限制。任何可串行化類型都可以從 WEB HTTP 服務作業傳回。因為網頁瀏覽器可以叫用 WEB HTTP 服務作業，因此 URL 中可以指定哪些資料類型有限制。如需默認支援哪些類型的詳細資訊，請參閱下方的 UriTemplate 查詢字串參數和 URL 一節。您可以藉由提供您自己的 T：System.ServiceModel.Dispatcher.QueryStringConverter 實作來變更預設行為，以指定如何將 URL 中指定的參數轉換成實際參數類型。如需詳細資訊，請參閱 QueryStringConverter

謹慎

使用 WCF WEB HTTP 程式設計模型撰寫的服務不會使用 SOAP 訊息。因為未使用SOAP，所以無法使用WCF所提供的安全性功能。不過，您可以使用 HTTPS 裝載服務，以使用傳輸型安全性。如需 WCF 安全性的詳細資訊，請參閱安全性概觀。

警告

安裝 IIS 的 WebDAV 擴充功能可能會導致 Web HTTP 服務在 WebDAV 擴充功能嘗試處理所有 PUT 要求時傳回 HTTP 405 錯誤。若要解決此問題，您可以卸載 WebDAV 擴充功能，或停用網站的 WebDAV 擴充功能。如需詳細資訊，請參閱 IIS 和 WebDav。

URITemplate 和 UriTemplateTable 的 URI 處理

URI 範本提供有效率的語法來表達大型結構上類似的 URI 集合。例如，下列範本會表達以「a」開頭且結尾為「c」的所有三段 URI 集合，而不考慮中繼區段的值：a/{segment}/c

此樣本描述如下的 URI：

a/x/c
a/y/c
a/z/c
等等。

在此範本中，大括號表示法（“{segment}”）表示變數區段，而不是常值。

.NET Framework 提供 API，以使用稱為 UriTemplate的 URI 範本。 UriTemplates 可讓您執行下列動作：

您可以使用一組參數呼叫其中一個 Bind 方法，以產生符合範本的 完全封閉 URI。這表示 URI 範本中的所有變數都會取代為實際值。
您可以提供一個候選 URI 來呼叫 Match（），該函數會利用範本將候選 URI 分解成其組成部分，並回傳一個字典，其中包含依據範本中變數標記的不同 URI 部分。
Bind（）和 Match（）是反向的，所以您可以呼叫 Match（Bind（x）），並回到您開始使用的相同環境。

有許多情況（特別是在伺服器上，需要根據 URI 將要求分派至服務作業）中，您會希望在一種數據結構中追蹤一組 UriTemplate 物件，該結構能夠對每個包含的範本單獨進行尋址。 UriTemplateTable 代表一組 URI 範本，並選取一組範本和候選 URI 的最佳比對。這與任何特定的網路堆疊（WCF 包含）無關，因此您可以視需要使用它。

WCF 服務模型會利用 UriTemplate 和 UriTemplateTable，將服務作業與一組由 UriTemplate所描述的 URI 產生關聯。服務作業與 UriTemplate相關聯，使用 WebGetAttribute 或 WebInvokeAttribute。如需 UriTemplate 和 UriTemplateTable的詳細資訊，請參閱 UriTemplate 和 UriTemplateTable。

WebGet 和 WebInvoke 屬性

WCF WEB HTTP 服務除了各種叫用動詞（例如 HTTP POST、PUT 和 DELETE）之外，還利用擷取動詞（例如 HTTP GET）。 WCF WEB HTTP 程式設計模型可讓服務開發人員控制其服務操作所用的 URI 範本和動詞，這些與 WebGetAttribute 和 WebInvokeAttribute有關聯。 WebGetAttribute 和 WebInvokeAttribute 可讓您控制個別作業如何系結至 URI 和與這些 URI 相關聯的 HTTP 方法。例如，在下列程式代碼中新增 WebGetAttribute 和 WebInvokeAttribute。

[ServiceContract]
interface ICustomer
{
  //"View It"

  [WebGet]
  Customer GetCustomer():

  //"Do It"
    [WebInvoke]
  Customer UpdateCustomerName( string id,
                               string newName );
}

上述程式代碼可讓您提出下列 HTTP 要求。

GET /GetCustomer

POST /UpdateCustomerName

WebInvokeAttribute 預設為 POST，但您也可以將其用於其他動詞。

[ServiceContract]
interface ICustomer
{
  //"View It" -> HTTP GET
    [WebGet( UriTemplate="customers/{id}" )]
  Customer GetCustomer( string id ):

  //"Do It" -> HTTP PUT
  [WebInvoke( UriTemplate="customers/{id}", Method="PUT" )]
  Customer UpdateCustomer( string id, Customer newCustomer );
}

如需使用 WCF WEB HTTP 程式設計模型之 WCF 服務的完整範例，請參閱如何：建立基本 WCF Web HTTP 服務。

UriTemplate 查詢字串參數與網址

您可以輸入與服務作業相關聯的 URL，從網頁瀏覽器呼叫 Web 樣式服務。這些服務作業可能會採用必須在 URL 內以字串形式指定的查詢字串參數。下表顯示可在 URL 內傳遞的類型，以及所使用的格式。

類型	格式
Byte	0 - 255
SByte	-128 - 127
Int16	-32768 - 32767
Int32	-2,147,483,648 - 2,147,483,647
Int64	-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807
UInt16	0 - 65535
UInt32	0 - 4,294,967,295
UInt64	0 - 18,446,744,073,709,551,615
Single	-3.402823e38 - 3.402823e38 （不需要指數表示法）
Double	-1.79769313486232e308 - 1.79769313486232e308 （不需要指數表示法）
Char	任何單一字元
Decimal	標準表示法中的任何十進位數（無指數）
Boolean	True 或 False （不區分大小寫）
String	任何字串（不支援空字串，而且不進行跳脫）
DateTime	MM/DD/YYYY MM/DD/YYYY HH:MM:SS [上午\|下午] 月/日/年月日年 HH：MM：SS [上午\|下午]
TimeSpan	DD.HH：MM：SS 其中 DD = Days， HH = Hours， MM = minutes， SS = Seconds
Guid	GUID，例如： 936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset	MM/DD/YYYY HH：MM：SS MM：SS 其中 DD = Days， HH = Hours， MM = minutes， SS = Seconds
枚舉	例如，列舉值會定義列舉，如下列程式代碼所示。 `public enum Days{ Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday };` 任何個別列舉值（或其對應的整數值）都可以在查詢字串中指定。
具有 `TypeConverterAttribute` 的型別可以在型別與字串表示形式之間進行轉換。	取決於類型轉換器。

格式和 WCF WEB HTTP 程式設計模型

WCF WEB HTTP 程式設計模型包含可支援多種不同數據格式的新功能。在繫結層，WebHttpBinding 可以讀取和寫入下列不同類型的數據：

XML
JSON
不透明的二進位數據流

這表示 WCF WEB HTTP 程式設計模型可以處理任何類型的數據，但您可能會對 Stream進行程式設計。

.NET Framework 3.5 提供 JSON 數據（AJAX）的支援，以及新聞訂閱摘要（包括 ATOM 和 RSS）。如需這些功能的詳細資訊，請參閱 WCF Web HTTP 格式設定、WCF 新聞訂閱概觀和 AJAX 整合和 JSON 支援。

WCF WEB HTTP 程式設計模型和安全性

因為 WCF WEB HTTP 程式設計模型不支援 WS-* 通訊協定，因此保護 WCF WEB HTTP 服務的唯一方法是使用 SSL 透過 HTTPS 公開服務。如需使用 IIS 7.0 設定 SSL 的詳細資訊，請參閱如何在 IIS 中實作 SSL。

針對 WCF WEB HTTP 程式設計模型進行疑難解答

使用 ChannelFactoryBase<TChannel> 呼叫 WCF WEB HTTP 服務以建立通道時，WebHttpBehavior 會使用組態檔中設定的 EndpointAddress，即使將不同的 EndpointAddress 傳遞至 ChannelFactoryBase<TChannel>也一樣。

共用方式為