Compartir a través de

Compatibilidad con directivas

  • Artículo

Wsutil procesa la directiva especificada en los metadatos de entrada y genera rutinas auxiliares para la compatibilidad con el modelo de servicio.

Uso de la compatibilidad con directivas en wsutil

Los desarrolladores deben seguir los pasos siguientes para usar la compatibilidad con directivas en el compilador de wsutil:

  • Recopile todos los archivos de metadatos de entrada necesarios para el servicio web de destino.
  • Compile todos los archivos WSDL/XSD/policy recopilados mediante wsutil.exe. Wsutil genera un conjunto de archivos de código auxiliar y archivo de encabezado para cada archivo WSDL y XSD de entrada.
  • Inspeccione el archivo de encabezado generado, todos los nombres de rutina auxiliar de directiva se muestran en la sección de comentarios al principio del archivo de encabezado.
  • Use bindingName_CreateServiceProxy rutina auxiliar para crear un proxy de servicio.
  • Use bindingName_CreateServiceEndpoint rutina auxiliar para crear el punto de conexión de servicio.
  • Rellene WS_bindingTemplateType_BINDING_TEMPLATE estructura especificada en la firma del método. Los desarrolladores pueden proporcionar propiedades de canal adicionales o propiedades de seguridad según sea necesario.
  • Llame a las rutinas auxiliares, cuando se cree correctamente el proxy de servicio de devolución o el punto de conexión de servicio.

En las secciones siguientes se describen los temas relacionados con detalle.

Control de la entrada de directiva

A continuación se muestran las opciones del compilador relacionadas con el procesamiento de directivas.

De forma predeterminada, wsutil siempre generará plantillas de directiva a menos que se llame con la opción "/nopolicy". La directiva se puede incrustar como parte de un archivo WSDL o se puede crear por separado como un archivo de metadatos de directiva que wsutil toma como entrada. La opción del compilador "/wsp:" se usa para indicar que los metadatos de entrada especificados son un archivo de directiva. Wsutil genera posibles asistentes relacionados con directivas con la compilación siguiente:

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

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

No se genera ningún asistente de directivas cuando se usa la opción "/nopolicy" como en el ejemplo siguiente.

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

La página Asignación de metadatos detalla la asignación entre construcciones de metadatos con diferentes tipos de enlace.

Se pueden especificar tres categorías de configuración de directiva en la configuración de directiva:

Tipo de plantilla de enlace

Hay un número limitado de enlaces que se admiten en wsutil. Todas esas combinaciones admitidas de estos enlaces se enumeran en WS_BINDING_TEMPLATE_TYPE definición. Por ejemplo, para el siguiente enlace en wsdl

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

Wsutil genera WS_HTTP_BINDING_TEMPLATE_TYPE tipo de plantilla de enlace para este enlace.

Descripciones de directivas

Con la configuración de directiva de entrada, wsutil genera un conjunto de descripciones de directivas que describen la directiva de entrada, incluido el tipo de plantilla, así como los valores especificados en la directiva. Por ejemplo, para la entrada

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

wsutil genera una descripción de la propiedad de 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),
},

Toda la configuración de directiva (propiedades de canal, propiedades de seguridad y propiedades de enlace de seguridad) en un enlace se agrega en una estructura WS_bindingTemplateType_POLICY_DESCRIPTION. WS_BINDING_TEMPLATE_TYPE especifica las diferentes combinaciones de directivas de enlace que admite wsutil.

Estructura de plantilla que rellenará la aplicación

La descripción de la directiva contiene toda la información de directiva especificada en los metadatos de entrada para un enlace determinado, pero hay información que no se puede representar en la directiva, pero todavía requiere la entrada del usuario al usar esa configuración de directivas para crear el proxy de servicio o el punto de conexión de servicio. Por ejemplo, la aplicación debe proporcionar credenciales para la autenticación de encabezado HTTP.

La aplicación debe rellenar la estructura de la plantilla, denominada WS_bindingTemplateType_BINDING_TEMPLATE para cada tipo de plantilla de enlace diferente, definido en webservices.h:

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

La lista de plantillas de enlace de seguridad es opcional depende del enlace de seguridad coincidente. Por ejemplo, WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE campo se presenta en WS_HTTP_SSL_BINDING_TEMPLATE para que la aplicación proporcione información de enlace de seguridad relacionada con SSL, incluida la información de credenciales.

La aplicación debe rellenar todos los campos de esta estructura antes de llamar a las API de plantilla de servicios web. Las propiedades de seguridad adicionales, así como las propiedades de enlace de seguridad que no se pueden representar en la directiva deben rellenarse, y las API de servicios web combinan los dos conjuntos de propiedades en tiempo de ejecución. Los campos se pueden eliminar de cero si no son aplicables. Por ejemplo, securityProperties se puede eliminar sin cero si no se necesitan propiedades de seguridad adicionales.

Rutinas auxiliares y declaración de descripción de directiva en archivos de encabezado

wsutil crea una rutina auxiliar para facilitar una mejor compatibilidad en el nivel de modelo de servicio, de modo que la aplicación pueda crear un proxy de servicio y un punto de conexión de servicio más fáciles. La descripción de la directiva también se expone de forma que la aplicación pueda usarlas directamente. Una rutina de ayuda CreateSerivceProxy tiene el siguiente aspecto:

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

Se recomienda a los desarrolladores que usen esas rutinas auxiliares, aunque también pueden usar directamente la rutina de tiempo de ejecución subyacente proporcionada por webservices.dll. No se recomienda a los desarrolladores que usen las descripciones de directivas directamente al programar mediante el nivel de modelo de servicio .

Las referencias de descripción de directiva también se generan en el encabezado para el usuario avanzado. Si los desarrolladores no usan las funcionalidades del modelo de servicio, pueden usar las descripciones de directivas directamente.

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

Prototipos de definición en archivos de código auxiliar

Se crean un único campo de estructura de descripción de directiva por enlace y sus descripciones auxiliares a las que se hace referencia internamente en la estructura del prototipo local. Las descripciones de directiva se generan en el archivo donde se genera el WS_CONTRACT_DESCRIPTION . Por lo general, los desarrolladores no necesitan inspeccionar el archivo de código auxiliar durante el desarrollo, aunque el archivo de código auxiliar contiene todos los detalles sobre las especificaciones de la directiva.

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

Implementación de rutinas auxiliares en los archivos de código auxiliar

Wsutil genera rutinas auxiliares para simplificar las llamadas de aplicación a WsCreateServiceProxy y crear WS_SERVICE_ENDPOINT base en la información proporcionada en la configuración de directiva.

Depende de las restricciones de enlace especificadas para el puerto especificado, el primer argumento es diferente según la estructura de la plantilla. En el ejemplo siguiente se supone que el transporte HTTP, la firma para la creación del proxy de servicio es similar con un 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);
}

Opciones de configuración de directiva compatibles

En la tabla siguiente se enumeran todos los tipos de plantilla de enlace admitidos, los enlaces de seguridad coincidentes necesarios en el tipo, la estructura de plantilla que va a rellenar la aplicación para el tipo y el tipo de descripción coincidente. La aplicación debe rellenar la estructura de la plantilla, mientras que el desarrollador de aplicaciones debe comprender cuáles son los enlaces de seguridad necesarios en la directiva especificada.

WS_BINDING_TEMPLATE_TYPE Combinaciones de enlaces de seguridad estructura de plantilla que rellenará la aplicación descripción de la directiva
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 y 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 y 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 y 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 y 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 y 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 y WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_USERNAME_MESSAGE_SECURITY_BINDING en el canal de arranque 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 y WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING en el canal de arranque 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 y WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_USERNAME_MESSAGE_SECURITY_BINDING en el canal de arranque 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 y WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING en el canal de arranque WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

Por ejemplo, WS_HTTP_SSL_BINDING_TEMPLATE_TYPE indica la directiva de entrada para el enlace especifica el transporte HTTP y WS_SSL_TRANSPORT_SECURITY_BINDING. La aplicación debe rellenar WS_HTTP_SSL_BINDING_TEMPLATE estructura antes de llamar a las rutinas auxiliares y se WS_HTTP_SSL_POLICY_DESCRIPTION la descripción de la directiva coincidente. Más concretamente, la sección de enlace de WSDL contiene los siguientes 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>

Compatibilidad con contexto de seguridad

En Contexto de seguridad, se crea el canal de arranque para establecer la conversación segura en el canal de servicio. Wsutil solo admite el escenario en el que el canal de arranque es el mismo que el canal de servicio, con las mismas propiedades de canal y propiedades de seguridad. Se requiere seguridad de transporte para el enlace de mensajes de contexto de seguridad; wsutil admite canales de arranque con otros enlaces de seguridad de mensajes, pero solo admite el contexto de seguridad como el único enlace de seguridad de mensajes en el canal de servicio, sin combinación con otros enlaces de seguridad de mensajes. Los desarrolladores pueden admitir esas combinaciones fuera de la compatibilidad con plantillas de directiva.

La enumeración siguiente forma parte de la compatibilidad con directivas:

Las siguientes funciones forman parte de la compatibilidad con directivas:

Las estructuras siguientes forman parte de la compatibilidad con directivas: