WCF Web HTTP 程式設計模型概觀

  • 發行項

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，將服務作業同時與 GET 及其他 HTTP 動詞 (如 PUT、POST 和 DELETE) 產生關聯。

  • 多種資料格式：Web 樣式服務能夠處理包括 SOAP 訊息在內許多種類的資料。 WCF WEB HTTP 程式設計模型運用 WebHttpBinding 和 WebHttpBehavior 以支援多種不同的資料格式，包括 XML 文件、JSON 資料物件，以及諸如影像、視訊檔或純文字之類的二進位內容資料流。

WCF WEB HTTP 程式設計模型將 WCF 的觸角延伸至擴及 Web 樣式案例，包括 WEB HTTP 服務、AJAX 和 JSON 服務，以及新聞訂閱 (ATOM/RSS) 摘要。 如需 AJAX 和 JSON 服務的詳細資訊，請參閱 AJAX 整合和 JSON 支援。 如需新聞訂閱的詳細資訊，請參閱 WCF 新聞訂閱概觀。

可從 WEB HTTP 服務傳回的資料型別沒有額外的限制。 WEB HTTP 服務作業可傳回任何可序列化型別。 因為 WEB HTTP 服務作業可由 Web 瀏覽器叫用，所以可在 URL 中指定的資料型別具有一項限制。 如需預設支援之型別的詳細資訊，請參閱下列 UriTemplate 查詢字串參數和 URL 一節。 您可以提供自己的 T:System.ServiceModel.Dispatcher.QueryStringConverter 實作來變更預設行為，其中指定如何將 URL 中指定的參數轉換成實際的參數型別。 如需詳細資訊，請參閱 QueryStringConverter

警告

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

警告

安裝適用於 IIS 的 WebDAV 延伸模組可能會導致 Web HTTP 服務傳回 HTTP 405 錯誤，因為 WebDAV 延伸模組會嘗試處理所有 PUT 要求。 若要解決此問題，您可以解除安裝 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 提供可以使用 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 程式設計模型可讓服務開發人員利用 WebGetAttribute 和 WebInvokeAttribute，同時控制 URI 範本及與其服務作業相關聯的動詞。 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

您可以輸入與服務作業關聯的 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 任何字串 (不支援 null 字串且不會進行逸出)
DateTime MM/DD/YYYY

MM/DD/YYYY HH:MM:SS [AM|PM]

月/日/年

月日年 HH:MM:SS [AM|PM]
TimeSpan DD.HH:MM:SS

其中 DD = 天數，HH = 小時，MM = 分鐘，SS = 秒數
Guid GUID，例如：

936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset MM/DD/YYYY HH:MM:SS MM:SS

其中 DD = 天數，HH = 小時，MM = 分鐘，SS = 秒數
列舉 列舉值，依下列程式碼示範的方式定義列舉。

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 程式設計模型疑難排解

當呼叫 WCF WEB HTTP 服務以使用 ChannelFactoryBase<TChannel> 建立通道時，WebHttpBehavior 會使用組態檔中設定的 EndpointAddress，即便傳遞至 EndpointAddress 的 ChannelFactoryBase<TChannel> 是另一個值亦然。

另請參閱