Suporte à política

Artigo
06/13/2023

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 à política 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. O Wsutil gera um conjunto de arquivos stub e arquivo de cabeçalho para cada arquivo WSDL e XSD de entrada.
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 o proxy de serviço.
Use bindingName_CreateServiceEndpoint rotina auxiliar para criar um 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, em um proxy de serviço de retorno bem-sucedido ou ponto de extremidade de serviço é criado.

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

Manipular entrada de política

Veja a seguir as 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 inserida 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. O 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

A página Mapeamento de Metadados detalha o mapeamento entre constructos de metadados com tipos de associação diferentes.

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

Propriedades do Canal. Atualmente, há suporte apenas para as seguintes propriedades de canal: WS_CHANNEL_PROPERTY_ENCODING, WS_CHANNEL_PROPERTY_ADDRESSING_VERSION e WS_CHANNEL_PROPERTY_ENVELOPE_VERSION.
Propriedades de segurança. Atualmente, há suporte apenas para as seguintes propriedades de segurança: WS_SECURITY_PROPERTY_TIMESTAMP_USAGE, WS_SECURITY_PROPERTY_SECURITY_HEADER_LAYOUT, WS_SECURITY_PROPERTY_TRANSPORT_PROTECTION_LEVEL e WS_SECURITY_PROPERTY_SECURITY_HEADER_VERSION.
Associação de segurança. Atualmente, há suporte apenas para as seguintes associações de segurança: WS_HTTP_HEADER_AUTH_SECURITY_BINDING, WS_SSL_TRANSPORT_SECURITY_BINDING, WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING, WS_USERNAME_MESSAGE_SECURITY_BINDING, WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING.

Tipo de modelo de associação

Há números limitados de associações com suporte no wsutil. Todas essas combinações com suporte dessas associações são listadas em WS_BINDING_TEMPLATE_TYPE definição. Por exemplo, para a associação a seguir em wsdl

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

O Wsutil gera WS_HTTP_BINDING_TEMPLATE_TYPE tipo de modelo de associação para essa associação.

Descrições da política

Com a configuração de 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 a 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 associaçã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ítica de associação às quais o wsutil dá suporte.

Estrutura de modelo a ser preenchida pelo aplicativo

A descrição da política contém todas as informações de política especificadas nos metadados de entrada para uma determinada associação, mas há informações que não podem ser representadas na política, mas exigem 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 associaçã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 associaçã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 associação de segurança relacionadas a SSL, incluindo as informações de credencial.

O aplicativo precisa preencher todos os campos nessa estrutura antes de chamar apIs de modelo de serviços Web. As propriedades de segurança adicionais, bem como as propriedades de associação de segurança que não são representáveis na política, precisam ser preenchidas e as APIs de serviços Web mesclam os dois conjuntos de propriedades em runtime. Os campos podem ser zerados se não forem aplicáveis. Por exemplo, securityProperties poderá ser zerado se nenhuma propriedade de segurança adicional for necessária.

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

O wsutil cria uma rotina auxiliar para facilitar o melhor suporte na camada do modelo de serviço, de modo que o aplicativo possa criar proxy de serviço e ponto de extremidade de serviço mais fácil. A descrição da política também é exposta de modo que o aplicativo possa usá-las diretamente. Uma rotina de ajuda CreateSerivceProxy é semelhante a:

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 runtime abaixo fornecida pelo webservices.dll. Os desenvolvedores não são incentivados a usar as descrições da política diretamente ao programar usando a camada de modelo de serviço .

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

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

Protótipos de definição em arquivos stub

Um único campo de estrutura de descrição de política por associação e suas descrições auxiliares referenciadas internamente são criadas na estrutura de protótipo local. As descrições de política são geradas no arquivo em que o WS_CONTRACT_DESCRIPTION é gerado. Geralmente, os desenvolvedores não precisam inspecionar o arquivo stub durante o desenvolvimento, embora o arquivo stub contenha todos os detalhes sobre as especificações de 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 aplicativo para WsCreateServiceProxy e criar WS_SERVICE_ENDPOINT base nas informações fornecidas nas configurações de política.

Depende das restrições de associação especificadas para a porta especificada, o primeiro argumento é diferente de acordo com a estrutura do modelo. O exemplo a seguir pressupõe que o transporte HTTP, a assinatura para criação de proxy de serviço é semelhante a 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 com suporte

A tabela a seguir lista todos os tipos de modelo de associação com suporte, as associações de segurança correspondentes necessárias no tipo, a estrutura de 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 de aplicativos deve entender quais são as associações de segurança necessárias na política fornecida.

WS_BINDING_TEMPLATE_TYPE	Combinações de associação de segurança	estrutura de modelo a ser preenchida pelo aplicativo	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 inicialização	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 inicialização	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 de inicialização	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 inicialização	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 que 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 associaçã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 ao Contexto de Segurança

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

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

WS_BINDING_TEMPLATE_TYPE

As seguintes funções fazem parte do suporte à política:

As seguintes estruturas fazem parte do suporte à política:

Partilhar via

Suporte à política

Como usar o suporte à política no wsutil

Manipular entrada de política

Configurações de política com suporte

Suporte ao Contexto de Segurança

Comentários

Recursos adicionais

Partilhar via

Suporte à política

Como usar o suporte à política no wsutil

Manipular entrada de política

Código relacionado à política gerado pelo compilador wsutil

Configurações de política com suporte

Suporte ao Contexto de Segurança

Comentários

Recursos adicionais