次の方法で共有

ポリシーのサポート

  • [アーティクル]

Wsutil は、入力メタデータで指定されたポリシーを処理し、サービス モデルのサポートのためのヘルパー ルーチンを生成します。

wsutil でポリシー サポートを使用する方法

開発者は、wsutil コンパイラでポリシー サポートを使用するには、次の手順に従う必要があります。

  • 対象の Web サービスに必要なすべての入力メタデータ ファイルを収集します。
  • wsutil.exeを使用して、収集されたすべての WSDL/XSD/ポリシー ファイルをコンパイルします。 Wsutil は、入力 WSDL ファイルと XSD ファイルごとにスタブ ファイルとヘッダー ファイルのセットを 1 つ生成します。
  • 生成されたヘッダー ファイルを検査します。すべてのポリシー ヘルパー ルーチン名は、ヘッダー ファイルの先頭にあるコメント セクションに一覧表示されます。
  • ヘルパー ルーチンbindingName_CreateServiceProxy使用して、サービス プロキシを作成します。
  • ヘルパー ルーチンbindingName_CreateServiceEndpoint使用して、サービス エンドポイントを作成します。
  • メソッド シグネチャで指定WS_bindingTemplateType_BINDING_TEMPLATE構造体を入力します。 開発者は、必要に応じて追加のチャネル プロパティやセキュリティ プロパティを提供できます。
  • 正常に戻るサービス プロキシまたはサービス エンドポイントが作成されたら、ヘルパー ルーチンを呼び出します。

以下のセクションでは、関連するトピックについて詳しく説明します。

ポリシー入力の処理

ポリシー処理に関連する コンパイラ オプション を次に示します。

既定では、"/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

[メタデータ マッピング] ページでは、さまざまなバインディングの種類を持つメタデータ コンストラクト間のマッピングについて詳しく説明します。

ポリシー設定には、次の 3 つのカテゴリのポリシー設定を指定できます。

バインド テンプレートの種類

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),
},

1 つのバインド内のすべてのポリシー設定 (チャネル プロパティ、セキュリティ プロパティ、セキュリティ バインディング プロパティ) は、1 つのWS_bindingTemplateType_POLICY_DESCRIPTION構造に集約されます。 WS_BINDING_TEMPLATE_TYPE では、wsutil がサポートするさまざまなバインド ポリシーの組み合わせを指定します。

アプリケーションによって入力されるテンプレート構造

ポリシーの説明には、特定のバインディングの入力メタデータに指定されたすべてのポリシー情報が含まれますが、これらのポリシー設定を使用してサービス プロキシまたはサービス エンドポイントを作成するときに、ポリシーで表すことができない情報がユーザー入力を必要とします。 たとえば、アプリケーションは 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_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE フィールドは、資格情報を含む SSL 関連のセキュリティ バインディング情報を提供するアプリケーションの WS_HTTP_SSL_BINDING_TEMPLATE に表示されます。

アプリケーションでは、Webservices テンプレート API を呼び出す前に、この構造体内のすべてのフィールドを入力する必要があります。 追加のセキュリティ プロパティと、ポリシーで表されないセキュリティ バインド プロパティを入力する必要があります。Webservices API は、実行時に 2 つのプロパティ セットをマージします。 該当しない場合は、フィールドをゼロにできます。 たとえば、追加のセキュリティ プロパティが必要ない場合は、securityProperties をゼロにできます。

ヘッダー ファイル内のヘルパー ルーチンとポリシー記述宣言

wsutil は、アプリケーションがサービス プロキシとサービス エンドポイントをより簡単に作成できるように、サービス モデル レイヤーのサポートを向上させるヘルパー ルーチンを作成します。 ポリシーの説明は、アプリケーションが直接使用できるように公開されます。 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;
  }

スタブ ファイルの定義プロトタイプ

バインディングごとに 1 つのポリシー記述構造フィールドとその内部参照ヘルパー記述がローカル プロトタイプ構造に作成されます。 ポリシーの説明は、 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 トランスポートを想定しています。サービス プロキシ作成のシグネチャは、1 つの追加チャネル型パラメーターと似ています。

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 は、他のメッセージ セキュリティ バインドを含むブートストラップ チャネルをサポートしますが、他のメッセージ セキュリティ バインドと組み合わせずに、サービス チャネル内の唯一のメッセージ セキュリティ バインディングとしてセキュリティ コンテキストのみをサポートします。 開発者は、ポリシー テンプレートのサポートの外部でこれらの組み合わせをサポートできます。

次の列挙は、ポリシーサポートの一部です。

次の機能は、ポリシーサポートの一部です。

次の構造は、ポリシーサポートの一部です。