策略支持

  • 项目

Wsutil 处理输入元数据中指定的策略，并为服务模型支持生成帮助程序例程。

如何在 wsutil 中使用策略支持

开发人员应按照以下步骤使用 wsutil 编译器中的策略支持：

  • 收集目标 Web 服务所需的所有输入元数据文件。
  • 使用 wsutil.exe 编译收集的所有 WSDL/XSD/policy 文件。 Wsutil 为每个输入 WSDL 和 XSD 文件生成一组存根文件和头文件。
  • 检查生成的头文件，所有策略帮助程序例程名称都列在头文件开头的注释部分中。
  • 使用bindingName_CreateServiceProxy帮助程序例程创建服务代理。
  • 使用bindingName_CreateServiceEndpoint帮助程序例程创建服务终结点。
  • 填写方法签名中指定的WS_bindingTemplateType_BINDING_TEMPLATE结构。 开发人员可以根据需要提供其他通道属性和/或安全属性。
  • 在成功返回服务代理或服务终结点时调用帮助程序例程。

以下部分详细介绍了相关主题。

处理策略输入

下面是与策略处理相关的 编译器选项 。

默认情况下，wsutil 将始终生成策略模板，除非使用“/nopolicy”选项调用。 策略可以作为 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 支持的不同绑定策略组合。

要由应用程序填充的模板结构

策略说明包含在给定绑定的输入元数据中指定的所有策略信息，但有些信息不能在策略中表示，但在使用这些策略设置创建服务代理和/或服务终结点时需要用户输入。 例如，应用程序必须提供用于 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 字段显示在 WS_HTTP_SSL_BINDING_TEMPLATE 中，以便应用程序提供与 SSL 相关的安全绑定信息，包括凭据信息。

在调用 Webservices 模板 API 之前，应用程序需要填写此结构中的所有字段。 需要填充其他安全属性以及策略中不可表示的安全绑定属性，并且 Web 服务 API 在运行时中合并这两组属性。 如果不适用，则可以将字段归零。 例如，如果不需要其他安全属性，则可以将 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;
  }

定义存根文件中的原型

每个绑定及其内部引用的帮助程序说明字段都在本地原型结构中创建一个策略说明字段。 策略说明在生成 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 传输，创建服务代理的签名与另外一个通道类型参数类似。

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 支持与其他消息安全绑定一起启动通道，但仅支持安全上下文作为服务通道中唯一的消息安全绑定，而不与其他消息安全绑定结合使用。 开发人员可以在策略模板支持之外支持这些组合。

以下枚举是策略支持的一部分：

以下函数是策略支持的一部分：

以下结构是策略支持的一部分：