原則支援

  • 發行項

Wsutil 會處理輸入中繼資料中指定的原則，並產生服務模型支援的協助程式常式。

如何在 wsutil 中使用原則支援

開發人員應遵循下列步驟，在 wsutil 編譯器中使用原則支援：

  • 收集目標 Web 服務所需的所有輸入中繼資料檔案。
  • 使用 wsutil.exe 編譯所有收集的 WSDL/XSD/原則檔案。 Wsutil 會為每個輸入 WSDL 和 XSD 檔案產生一組存根檔案和標頭檔。
  • 檢查產生的標頭檔，所有原則協助程式常式名稱都會列在標頭檔開頭的批註區段中。
  • 使用bindingName_CreateServiceProxy協助程式常式來建立服務 Proxy。
  • 使用bindingName_CreateServiceEndpoint協助程式常式來建立服務端點。
  • 填入方法簽章中指定的WS_bindingTemplateType_BINDING_TEMPLATE結構。 開發人員可以視需要提供其他通道屬性和/或安全性屬性。
  • 在成功傳回服務 Proxy 或服務端點時，呼叫協助程式常式。

下列各節將詳細說明相關主題。

處理原則輸入

以下是與原則處理相關的 編譯器選項 。

根據預設，除非使用 「/nopolicy」 選項呼叫 wsutil，否則一律會產生原則範本。 原則可以內嵌為 WSDL 檔案的一部分，也可以個別建立為 wsutil 作為輸入的原則中繼資料檔案。 編譯器選項 「/wsp：」 用來指出指定的輸入中繼資料是原則檔。 Wsutil 會產生具有下列編譯的潛在原則相關協助程式：

wsutil /wsdl：trusted.wsdl /wsdl：trusted1.wsdl

wstuil /wsdl：input.wsdl /wsp：policy.wsp

使用 「/nopolicy」 選項時，不會產生任何原則協助程式，如下列範例所示。

wsutil /nopolicy /wsdl：trusted.wsdl /wsdl：trusted1.wsdl

[中繼資料對應] 頁面詳細說明具有不同系結類型之中繼資料建構之間的對應。

您可以在原則設定中指定三種原則設定類別：

系結範本類型

wsutil 中支援的系結數目有限。 這些系結支援的所有組合都會列在 WS_BINDING_TEMPLATE_TYPE 定義中。 例如，針對 wsdl 中的下列系結

<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />

Wsutil 會為此系結產生 WS_HTTP_BINDING_TEMPLATE_TYPE 系結範本類型。

原則描述

使用輸入原則設定時，wsutil 會產生一組描述輸入原則的原則描述，包括範本類型，以及原則中指定的值。 例如，針對輸入

<wsdl:binding...>
  <soap11:binding.../> =< WS_ENVELOPE_VERSION_SOAP_1_1
</wsdl:binding>

wsutil 會產生通道屬性描述，例如：

WS_ENVELOPE_VERSION_SOAP_1_1,
{
  WS_CHANNEL_PROPERTY_ENVELOPE_VERSION,
  (void*)&locaDefinitions.policies.bindHostedClientSoap.envelopeVersion, //points to the WS_ENVELOPE_VERSION_SOAP_1_1 value above
  sizeof(&localDefinitions.policies.bindHostedClientSoap.envelopeVersion),
},

(通道屬性、安全性屬性和安全性系結屬性) 的所有原則設定都會匯總成一個WS_bindingTemplateType_POLICY_DESCRIPTION結構。 WS_BINDING_TEMPLATE_TYPE 指定 wsutil 支援的不同系結原則組合。

應用程式要填入的範本結構

原則描述包含指定系結之輸入中繼資料中指定的所有原則資訊，但原則中有資訊在使用這些原則設定來建立服務 Proxy 和/或服務端點時，仍需要使用者輸入。 例如，應用程式必須提供 HTTP 標頭驗證的認證。

應用程式必須針對 webservices.h 中定義的每個不同系結範本類型填入名為 WS_bindingTemplateType_BINDING_TEMPLATE 的範本結構：

struct WS_bindingTemplateType_BINDING_TEMPLATE
{
  WS_CHANNEL_PROPERTIES channelProperties;
  WS_SECURITY_PROPERTIES securityProperties;
  possible_list_of_SECURITY_BINDING_TEMPLATEs;
  ...
};

安全性系結範本清單是選擇性的，取決於相符的安全性系結。 例如，應用程式WS_HTTP_SSL_BINDING_TEMPLATE中會顯示WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE欄位，以提供 SSL 相關的安全性系結資訊，包括認證資訊。

應用程式必須填入此結構中的所有欄位，才能呼叫 Webservices 範本 API。 需要填入其他安全性屬性，以及原則中無法表示的安全性系結屬性，而 Webservices API 會在執行時間中合併這兩組屬性。 如果不適用，欄位可以零出。 例如，如果不需要額外的安全性屬性，則 securityProperties 可以零除。

標頭檔中的協助程式常式和原則描述宣告

wsutil 會建立協助程式常式，以協助更妥善地支援服務模型層，讓應用程式可以更輕鬆地建立服務 Proxy 和服務端點。 原則描述也會公開，讓應用程式可以直接使用這些描述。 CreateSerivceProxy 說明常式看起來像這樣：

HRESULT bindingName_CreateServiceProxy(
  __in_ecount_opt(propertyCount) const WS_PROXY_PROPERTY* properties,
  __in const ULONG propertyCount,
  __in WS_constraintName_BINDING_TEMPLATE* templateValue,
  __deref_out WS_SERVICE_PROXY** serviceProxy,
  __in_opt WS_ERROR* error);

我們鼓勵開發人員使用這些協助程式常式，但也可以直接使用webservices.dll所提供的執行時間常式底下。 使用 服務模型 層進行程式設計時，不建議開發人員直接使用原則描述。

原則描述參考也會在進階使用者的標頭中產生。 如果開發人員不使用服務模型功能，他們可以直接使用原則描述。

struct {
  ...
  struct {
    ...
    } contracts;
  struct {
    WS_bindingTemplateType_POLICY_DESCRIPTION bindingName;
    ...
    } policies;
  }

存根檔案中的定義原型

每個系結的單一原則描述結構欄位及其內部參考的協助程式描述會在本機原型結構中建立。 原則描述會在產生 WS_CONTRACT_DESCRIPTION 的檔案中產生。 一般而言，開發人員不需要在開發期間檢查存根檔案，但存根檔案包含原則規格的所有詳細資料。

struct {
  ...
  struct {
  ... } contracts;
  ...
 struct {
      struct {
        hierarchy of policy template descriptions;
        } bindingName;
      ...
      list of bindings in the input wsdl file.
  } policies;
} fileNameLocalDefinitions;

存根檔案中的協助程式常式實作

Wsutil 會產生協助程式常式，以簡化 對 WsCreateServiceProxy 的應用程式呼叫，並根據原則設定中提供的資訊建立 WS_SERVICE_ENDPOINT 。

取決於為指定埠指定的系結條件約束，第一個引數會根據範本結構而有所不同。 下列範例假設 HTTP 傳輸，建立服務 Proxy 的簽章與另一個通道類型參數類似。

HRESULT bindingName_CreateServiceProxy(
    __in WS_bindingTemplateType_BINDING_TEMPLATE* templateValue,
    __in_ecount_opt(propertyCount) const WS_PROXY_PROPERTY* properties,
    __in const ULONG propertyCount,
    __deref_out WS_SERVICE_PROXY** serviceProxy,
    __in_opt WS_ERROR* error)
{
    return WsCreateServiceProxyFromTemplate(
      WS_CHANNEL_TYPE_REQUEST,    // this is fixed for http, requires input for TCP
      properties,     
      propertyCount, 
      WS_bindingTemplateType_BINDING_TEMPLATE_TYPE,
      templateValue,
      sizeof(WS_bindingTemplateType_BINDING_TEMPLATE),  
      &fileName.policies.bindingName,   // template description as generated in the stub file
      sizeof(WS_constraintName_POLICY_DESCRIPTION),
      serviceProxy,     
      error);     
}

HRESULT bindingName_CreateServiceEndpoint(
__in WS_bindingTemplateType_BINDING_TEMPLATE* templateValue,
__in_opt const WS_STRING* addressUrl,
__in bindingNameFunctionTable* functionTable,
__in WS_SERVICE_SECURITY_CALLBACK authorizationCallback,
__in const WS_SERVICE_ENDPOINT_PROPERTY* properties,
__in ULONG propertyCount,
__in WS_HEAP* heap,
  __deref_out WS_SERVICE_ENDPOINT** serviceEndpoint,
  __in_opt WS_ERROR* error)
{
  WS_SERVICE_CONTRACT serviceContract;
  serviceContract.contractDescription = &fileName.contracts.bindingName;
  serviceContract.defaultMessageHandlerCallback = NULL;
  serviceContract.methodTable = (const void *)functionTable;

  return WsCreateServiceEndpointFromTemplate(
      properties,
      propertyCount,
      addressUrl,    // service endpoint address
      WS_CHANNEL_TYPE_RESPONSE,    // this is fixed for http, requires input for TCP
      &serviceContract,
      authorizationCallback,
      heap,
      WS_bindingTemplateType_BINDING_TEMPLATE_TYPE,
      templateValue,
      sizeof(WS_bindingTemplateType_BINDING_TEMPLATE),
      &fileName.policies.bindingName,   // template description as generated in the stub file
      sizeof(WS_bindingTemplateType_POLICY_DESCRIPTION),
      serviceEndpoint,
      error);
}

支援的原則設定

下表列出所有支援的系結範本類型、類型中所需的相符安全性系結、要由應用程式填入類型的範本結構，以及相符的描述類型。 應用程式需要填入範本結構，而應用程式開發人員應該瞭解指定原則中所需的安全性系結為何。

WS_BINDING_TEMPLATE_TYPE 安全性系結組合 要由應用程式填入的範本結構 原則描述
WS_HTTP_BINDING_TEMPLATE_TYPE WS_HTTP_BINDING_TEMPLATE WS_HTTP_POLICY_DESCRIPTION
WS_HTTP_SSL_BINDING_TEMPLATE_TYPE WS_SSL_TRANSPORT_SECURITY_BINDING WS_HTTP_SSL_BINDING_TEMPLATE WS_HTTP_SSL_POLICY_DESCRIPTION
WS_HTTP_HEADER_AUTH_BINDING_TEMPLATE_TYPE WS_HTTP_HEADER_AUTH_SECURITY_BINDING WS_HTTP_HEADER_AUTH_BINDING_TEMPLATE WS_HTTP_HEADER_AUTH_POLICY_DESCRIPTION
WS_HTTP_SSL_HEADER_AUTH_BINDING_TEMPLATE_TYPE WS_SSL_TRANSPORT_SECURITY_BINDING 和 WS_HTTP_HEADER_AUTH_SECURITY_BINDING WS_HTTP_SSL_HEADER_AUTH_BINDING_TEMPLATE WS_HTTP_SSL_HEADER_AUTH_POLICY_DESCRIPTION
WS_HTTP_SSL_USERNAME_BINDING_TEMPLATE_TYPE WS_SSL_TRANSPORT_SECURITY_BINDING和WS_USERNAME_MESSAGE_SECURITY_BINDING WS_HTTP_SSL_USERNAME_BINDING_TEMPLATE WS_HTTP_SSL_USERNAME_POLICY_DESCRIPTION
WS_HTTP_SSL_KERBEROS_APREQ_BINDING_TEMPLATE_TYPE WS_SSL_TRANSPORT_SECURITY_BINDING 和 WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING WS_HTTP_SSL_KERBEROS_APREQ_BINDING_TEMPLATE WS_HTTP_SSL_KERBEROS_APREQ_POLICY_DESCRIPTION
WS_TCP_BINDING_TEMPLATE_TYPE WS_TCP_BINDING_TEMPLATE WS_TCP_POLICY_DESCRIPTION
WS_TCP_SSPI_BINDING_TEMPLATE_TYPE WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING WS_TCP_SSPI_BINDING_TEMPLATE WS_TCP_SSPI_POLICY_DESCRIPTION
WS_TCP_SSPI_USERNAME_BINDING_TEMPLATE_TYPE WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING 和 WS_USERNAME_MESSAGE_SECURITY_BINDING WS_TCP_SSPI_USERNAME_BINDING_TEMPLATE WS_TCP_SSPI_USERNAME_POLICY_DESCRIPTION
WS_TCP_SSPI_KERBEROS_APREQ_BINDING_TEMPLATE_TYPE WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING 和 WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING WS_TCP_SSPI_KERBEROS_APREQ_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_POLICY_DESCRIPTION
WS_HTTP_SSL_USERNAME_SECURITY_CONTEXT_BINDING_TEMPLATE_TYPE 在啟動程式通道中使用WS_USERNAME_MESSAGE_SECURITY_BINDING WS_SSL_TRANSPORT_SECURITY_BINDING和WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING WS_HTTP_SSL_USERNAME_SECURITY_CONTEXT_BINDING_TEMPLATE WS_HTTP_SSL_USERNAME_SECURITY_CONTEXT_POLICY_DESCRIPTION
WS_HTTP_SSL_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE_TYPE 在啟動程式通道中使用WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING WS_SSL_TRANSPORT_SECURITY_BINDING和WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING WS_HTTP_SSL_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_HTTP_SSL_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION
WS_TCP_SSPI_USERNAME_SECURITY_CONTEXT_BINDING_TEMPLATE_TYPE 在啟動程式通道中使用WS_USERNAME_MESSAGE_SECURITY_BINDING WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING和WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING WS_TCP_SSPI_USERNAME_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_USERNAME_SECURITY_CONTEXT_POLICY_DESCRIPTION
WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE_TYPE 在啟動程式通道中使用WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING進行WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING和WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

例如， WS_HTTP_SSL_BINDING_TEMPLATE_TYPE 指出系結的輸入原則會指定 HTTP 傳輸，並 WS_SSL_TRANSPORT_SECURITY_BINDING。 應用程式必須在呼叫協助程式常式之前填入 WS_HTTP_SSL_BINDING_TEMPLATE 結構，且比對的原則描述 WS_HTTP_SSL_POLICY_DESCRIPTION。 更具體來說，WSDL 中的系結區段包含下列區段：

<wsp:Policy...>
  <sp:TransportBinding...>
    <wsp:Policy...>
      <sp:TransportToken...>
        <wsp:Policy...>
          <sp:HttpsToken.../>
        </wsp:Policy...>
      </sp:TransportToken...>
    </wsp:Policy>
  </sp:TransportBinding...>
</wsp:Policy>

<wsdl:binding...>
<soap11:binding.../> => WS_ENVELOPE_VERSION_SOAP_1_1
</wsdl:binding>

安全性內容支援

在 安全性內容中，會建立啟動程式通道，以在服務通道中建立安全對話。 Wsutil 僅支援啟動程式通道與服務通道相同的案例，其通道屬性和安全性屬性相同。 安全性內容訊息系結需要傳輸安全性;wsutil 支援具有其他訊息安全性系結的啟動程式通道，但只支援安全性內容做為服務通道中唯一的訊息安全性系結，而不與其他訊息安全性系結結合。 開發人員可以在原則範本支援之外支援這些組合。

下列列舉是原則支援的一部分：

下列函式是原則支援的一部分：

下列結構是原則支援的一部分：