Partilhar via

Apoio a políticas

  • Artigo

O Wsutil processa a política especificada nos metadados de entrada e gera rotinas auxiliares para suporte ao modelo de serviço.

Como usar o suporte a políticas no wsutil

Os desenvolvedores devem seguir as seguintes etapas para usar o suporte à política no compilador wsutil:

  • Colete todos os arquivos de metadados de entrada necessários para o serviço Web de destino.
  • Compile todos os arquivos WSDL/XSD/policy coletados usando wsutil.exe. Wsutil gera um conjunto de arquivo stub e arquivo de cabeçalho para cada entrada WSDL e XSD arquivos.
  • Inspecione o arquivo de cabeçalho gerado, todos os nomes de rotina do auxiliar de política são listados na seção de comentários no início do arquivo de cabeçalho.
  • Use bindingName_CreateServiceProxy rotina auxiliar para criar proxy de serviço.
  • Use bindingName_CreateServiceEndpoint rotina auxiliar para criar o ponto de extremidade de serviço.
  • Preencha WS_bindingTemplateType_BINDING_TEMPLATE estrutura especificada na assinatura do método. Os desenvolvedores podem fornecer propriedades de canal adicionais e/ou propriedades de segurança, conforme necessário.
  • Chame as rotinas auxiliares, quando o proxy de serviço de retorno bem-sucedido ou o ponto de extremidade do serviço for criado.

As seções a seguir descrevem tópicos relacionados em detalhes.

Manipular a entrada de políticas

A seguir estão opções do compilador relacionadas ao processamento de políticas.

Por padrão, o wsutil sempre gerará modelos de política, a menos que seja chamado com a opção "/nopolicy". A política pode ser incorporada como parte de um arquivo WSDL ou pode ser criada separadamente como um arquivo de metadados de política que o wsutil usa como entrada. A opção do compilador "/wsp:" é usada para indicar que os metadados de entrada especificados são um arquivo de política. Wsutil gera potenciais auxiliares relacionados à política com a seguinte compilação:

wsutil /wsdl:trusted.wsdl /wsdl:trusted1.wsdl

wstuil /wsdl:input.wsdl /wsp:policy.wsp

Nenhum auxiliar de política é gerado quando a opção "/nopolicy" é usada, como no exemplo a seguir.

wsutil /nopolicy /wsdl:trusted.wsdl /wsdl:trusted1.wsdl

página de de mapeamento de metadados detalha o mapeamento entre construções de metadados com diferentes tipos de ligação.

Três categorias de configurações de política podem ser especificadas nas configurações de política:

Tipo de modelo de vinculação

Há um número limitado de ligações que são suportadas no wsutil. Todas as combinações suportadas dessas ligações estão listadas em WS_BINDING_TEMPLATE_TYPE definição. Por exemplo, para a seguinte ligação em wsdl

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

Wsutil gera WS_HTTP_BINDING_TEMPLATE_TYPE tipo de modelo de vinculação para essa ligação.

Descrições das políticas

Com a configuração da política de entrada, o wsutil gera um conjunto de descrições de política que descrevem a política de entrada, incluindo o tipo de modelo, bem como os valores especificados na política. Por exemplo, para entrada

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

wsutil gera descrição da propriedade do canal como:

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

Todas as configurações de política (propriedades de canal, propriedades de segurança e propriedades de vinculação de segurança) em uma associação são agregadas em uma estrutura WS_bindingTemplateType_POLICY_DESCRIPTION. WS_BINDING_TEMPLATE_TYPE especifica as diferentes combinações de políticas de vinculação suportadas pelo WSUTIL.

Estrutura do modelo a preencher por candidatura

A descrição da política contém todas as informações de política especificadas em metadados de entrada para uma determinada associação, mas há informações que não podem ser representadas na política, mas exigem a entrada do usuário ao usar essas configurações de políticas para criar proxy de serviço e/ou ponto de extremidade de serviço. Por exemplo, o aplicativo deve fornecer credenciais para autenticação de cabeçalho HTTP.

O aplicativo precisa preencher a estrutura do modelo, nomeada WS_bindingTemplateType_BINDING_TEMPLATE para cada tipo de modelo de vinculação diferente, definido em webservices.h:

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

A lista de modelos de vinculação de segurança é opcional depende da associação de segurança correspondente. Por exemplo, WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE campo é apresentado em WS_HTTP_SSL_BINDING_TEMPLATE para que o aplicativo forneça informações de vinculação de segurança relacionadas ao SSL, incluindo as informações de credencial.

O aplicativo precisa preencher todos os campos nessa estrutura antes de chamar APIs de modelo de webservices. Propriedades de segurança adicionais, bem como propriedades de vinculação de segurança que não são representáveis na política precisam ser preenchidas, e as APIs de webservices mesclam os dois conjuntos de propriedades em tempo de execução. Os campos podem ser zerados se não for aplicável. Por exemplo, securityProperties pode ser zerado se nenhuma propriedade de segurança adicional for necessária.

Rotinas auxiliares e declaração de descrição de política em arquivos de cabeçalho

O WSUTIL cria uma rotina auxiliar para facilitar um melhor suporte na camada de modelo de serviço, de modo que o aplicativo possa criar proxy de serviço e ponto de extremidade de serviço mais facilmente. A descrição da política também é exposta de tal forma que o aplicativo pode usá-los diretamente. Uma rotina de ajuda do CreateSerivceProxy se parece com:

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);

Os desenvolvedores são incentivados a usar essas rotinas auxiliares, embora também possam usar diretamente a rotina de tempo de execução abaixo fornecida pelo webservices.dll. Os desenvolvedores não são incentivados a usar as descrições de política diretamente ao programar usando camada de modelo de serviço.

As referências de descrição da política também são geradas no cabeçalho para usuário avançado. Se os desenvolvedores não usarem funcionalidades de modelo de serviço, eles poderão usar as descrições de política diretamente.

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

Definição de protótipos em arquivos stub

Um único campo de estrutura de descrição de política por vinculação e suas descrições auxiliares referenciadas internamente são criadas na estrutura de protótipo local. As descrições da política são geradas no arquivo onde o WS_CONTRACT_DESCRIPTION é gerado. Geralmente, os desenvolvedores não precisam inspecionar o arquivo de stub durante o desenvolvimento, embora o arquivo de stub contenha todos os detalhes sobre as especificações da política.

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

Implementação de rotinas auxiliares nos arquivos stub

O Wsutil gera rotinas auxiliares para simplificar as chamadas de aplicativos para WsCreateServiceProxy e criar WS_SERVICE_ENDPOINT base nas informações fornecidas nas configurações de política.

Depende das restrições de vinculação especificadas para a porta dada, o primeiro argumento é diferente de acordo com a estrutura do modelo. O exemplo a seguir pressupõe que o transporte HTTP, a assinatura para a criação de proxy de serviço é semelhante com um parâmetro de tipo de canal adicional.

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

Configurações de política suportadas

A tabela a seguir lista todos os tipos de modelo de vinculação suportados, as associações de segurança correspondentes necessárias no tipo, a estrutura do modelo a ser preenchida pelo aplicativo para o tipo e o tipo de descrição correspondente. O aplicativo precisa preencher a estrutura do modelo, enquanto o desenvolvedor do aplicativo deve entender quais são as ligações de segurança necessárias na política dada.

WS_BINDING_TEMPLATE_TYPE Combinações de vinculação de segurança estrutura do modelo a preencher por candidatura Descrição da política
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 e 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 e 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 e 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 e 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 e 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING com WS_USERNAME_MESSAGE_SECURITY_BINDING no canal de bootstrap 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING com WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING no canal de bootstrap 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING com WS_USERNAME_MESSAGE_SECURITY_BINDING no canal Bootstrap 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING com WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING no canal de bootstrap WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

Por exemplo, WS_HTTP_SSL_BINDING_TEMPLATE_TYPE indica a política de entrada para a associação, especifica o transporte HTTP e WS_SSL_TRANSPORT_SECURITY_BINDING. O aplicativo precisa preencher WS_HTTP_SSL_BINDING_TEMPLATE estrutura antes de chamar as rotinas auxiliares, e a descrição da política correspondente é WS_HTTP_SSL_POLICY_DESCRIPTION. Mais especificamente, a seção de vinculação no WSDL contém os seguintes segmentos:

<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>

Suporte de contexto de segurança

Em de contexto de segurança, o canal de inicialização é criado para estabelecer a conversa segura no canal de serviço. O Wsutil suporta apenas o cenário em que o canal de bootstrap é o mesmo que o canal de serviço, com as mesmas propriedades de canal e propriedades de segurança. A segurança de transporte é necessária para a vinculação de mensagens de contexto de segurança; O WSUTIL suporta canais de bootstrap com outras ligações de segurança de mensagem, mas suporta apenas o contexto de segurança como a única ligação de segurança de mensagem no canal de serviço, sem combinação com outras ligações de segurança de mensagem. Os desenvolvedores podem oferecer suporte a essas combinações fora do suporte ao modelo de política.

A enumeração a seguir faz parte do suporte à política:

As seguintes funções fazem parte do suporte a políticas:

Fazem parte do apoio político as seguintes estruturas: