Поделиться через

Поддержка политик

  • Статья

Wsutil обрабатывает политику, указанную в входных метаданных, и создает вспомогательные подпрограммы для поддержки модели служб.

Использование поддержки политик в wsutil

Разработчики должны выполнить следующие действия, чтобы использовать поддержку политики в компиляторе wsutil:

  • Соберите все входные файлы метаданных, необходимые для целевой веб-службы.
  • Скомпилируйте все собранные файлы WSDL/XSD/policy с помощью wsutil.exe. 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.

Приложению необходимо заполнить структуру шаблона с именем WS_bindingTemplateType_BINDING_TEMPLATE для каждого разного типа шаблона привязки, определенного в webservices.h:

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, включая учетные данные.

Приложению необходимо заполнить все поля в этой структуре перед вызовом API-интерфейсов шаблонов веб-служб. Дополнительные свойства безопасности, а также свойства привязки безопасности, которые не представляются в политике, должны быть заполнены, а 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_SSL_TRANSPORT_SECURITY_BINDING и WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING с WS_USERNAME_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_SSL_TRANSPORT_SECURITY_BINDING и WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING с WS_KERBEROS_APREQ_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_TCP_SSPI_TRANSPORT_SECURITY_BINDING и WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING с WS_USERNAME_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_TCP_SSPI_TRANSPORT_SECURITY_BINDING и WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING с WS_KERBEROS_APREQ_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 поддерживает каналы начальной загрузки с другими привязками безопасности сообщений, но поддерживает только контекст безопасности в качестве единственной привязки безопасности сообщений в канале службы без сочетания с другими привязками безопасности сообщений. Разработчики могут поддерживать эти сочетания за пределами поддержки шаблона политики.

Следующее перечисление является частью поддержки политики:

Следующие функции являются частью поддержки политики:

Следующие структуры являются частью поддержки политики: