Partager via

Prise en charge des stratégies

  • Article

Wsutil traite la stratégie spécifiée dans les métadonnées d’entrée et génère des routines d’assistance pour la prise en charge du modèle de service.

Comment utiliser la prise en charge des stratégies dans wsutil

Les développeurs doivent suivre les étapes suivantes pour utiliser la prise en charge de la stratégie dans le compilateur wsutil :

  • Collectez tous les fichiers de métadonnées d’entrée nécessaires pour le service web ciblé.
  • Compilez tous les fichiers WSDL/XSD/policy collectés à l’aide de wsutil.exe. Wsutil génère un ensemble de fichiers stub et de fichier d’en-tête pour chaque fichier WSDL et XSD d’entrée.
  • Inspectez le fichier d’en-tête généré, tous les noms de routine d’assistance de stratégie sont répertoriés dans la section commentaires au début du fichier d’en-tête.
  • Utilisez bindingName_CreateServiceProxy routine d’assistance pour créer un proxy de service.
  • Utilisez bindingName_CreateServiceEndpoint routine d’assistance pour créer un point de terminaison de service.
  • Renseignez WS_bindingTemplateType_BINDING_TEMPLATE structure spécifiée dans la signature de méthode. Les développeurs peuvent fournir des propriétés de canal supplémentaires et/ou des propriétés de sécurité en fonction des besoins.
  • Appelez les routines d’assistance, lors de la création d’un proxy de service ou d’un point de terminaison de service réussi.

Les sections suivantes décrivent en détail les rubriques connexes.

Gérer l’entrée de stratégie

Voici les options de compilateur liées au traitement des stratégies.

Par défaut, wsutil génère toujours des modèles de stratégie, sauf si elle est appelée avec l’option « /nopolicy ». La stratégie peut être incorporée dans le cadre d’un fichier WSDL ou peut être créée séparément en tant que fichier de métadonnées de stratégie que wsutil accepte comme entrée. L’option du compilateur « /wsp : » est utilisée pour indiquer que les métadonnées d’entrée spécifiées sont un fichier de stratégie. Wsutil génère des helpers potentiels liés à la stratégie avec la compilation suivante :

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

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

Aucune assistance de stratégie n’est générée lorsque l’option « /nopolicy » est utilisée comme dans l’exemple suivant.

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

mappage des métadonnées page détaille le mappage entre les constructions de métadonnées avec différents types de liaison.

Trois catégories de paramètres de stratégie peuvent être spécifiées dans les paramètres de stratégie :

Type de modèle de liaison

Il existe un nombre limité de liaisons prises en charge dans wsutil. Toutes ces combinaisons prises en charge de ces liaisons sont répertoriées dans WS_BINDING_TEMPLATE_TYPE définition. Par exemple, pour la liaison suivante dans wsdl

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

Wsutil génère WS_HTTP_BINDING_TEMPLATE_TYPE type de modèle de liaison pour cette liaison.

Descriptions de stratégie

Avec le paramètre de stratégie d’entrée, wsutil génère un ensemble de descriptions de stratégie décrivant la stratégie d’entrée, y compris le type de modèle, ainsi que les valeurs spécifiées dans la stratégie. Par exemple, pour l’entrée

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

wsutil génère une description de propriété de canal comme :

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

Tous les paramètres de stratégie (propriétés de canal, propriétés de sécurité et propriétés de liaison de sécurité) d’une liaison sont agrégés dans une structure WS_bindingTemplateType_POLICY_DESCRIPTION. WS_BINDING_TEMPLATE_TYPE spécifie les différentes combinaisons de stratégies de liaison que wsutil prend en charge.

Structure de modèle à remplir par application

La description de la stratégie contient toutes les informations de stratégie spécifiées dans les métadonnées d’entrée pour une liaison donnée, mais il existe des informations qui ne peuvent pas être représentées dans la stratégie, mais qui nécessitent une entrée utilisateur lors de l’utilisation de ces paramètres de stratégie pour créer un proxy de service et/ou un point de terminaison de service. Par exemple, l’application doit fournir des informations d’identification pour l’authentification d’en-tête HTTP.

L’application doit remplir la structure de modèle, nommée WS_bindingTemplateType_BINDING_TEMPLATE pour chaque type de modèle de liaison différent, défini dans webservices.h :

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

La liste des modèles de liaison de sécurité est facultative dépend de la liaison de sécurité correspondante. Par exemple, WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE champ est présenté dans WS_HTTP_SSL_BINDING_TEMPLATE pour que l’application fournisse des informations de liaison de sécurité liées à SSL, y compris les informations d’identification.

L’application doit renseigner tous les champs de cette structure avant d’appeler des API de modèle webservices. Des propriétés de sécurité supplémentaires, ainsi que des propriétés de liaison de sécurité qui ne sont pas représentées dans la stratégie doivent être renseignées, et les API de webservices fusionnent les deux ensembles de propriétés dans l’exécution. Les champs peuvent être supprimés s’ils ne sont pas applicables. Par exemple, securityProperties peut être supprimé si aucune propriété de sécurité supplémentaire n’est nécessaire.

Routines d’assistance et déclaration de description de stratégie dans les fichiers d’en-tête

wsutil crée une routine d’assistance pour faciliter une meilleure prise en charge dans la couche modèle de service, de sorte que l’application puisse créer plus facilement le proxy de service et le point de terminaison de service. La description de la stratégie est également exposée de telle sorte que l’application puisse les utiliser directement. Une routine d’aide CreateSerivceProxy ressemble à ceci :

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

Les développeurs sont encouragés à utiliser ces routines d’assistance, bien qu’ils puissent également utiliser directement la routine d’exécution en dessous fournie par webservices.dll. Les développeurs ne sont pas encouragés à utiliser les descriptions de stratégie directement lors de la programmation à l’aide de modèle de service couche.

Les références de description de stratégie sont également générées dans l’en-tête de l’utilisateur avancé. Si les développeurs n’utilisent pas de fonctionnalités de modèle de service, ils peuvent utiliser directement les descriptions de stratégie.

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

Prototypes de définition dans les fichiers stub

Un champ de structure de description de stratégie unique par liaison et ses descriptions d’assistance référencées en interne sont créées dans la structure de prototype local. Les descriptions de stratégie sont générées dans le fichier dans lequel le WS_CONTRACT_DESCRIPTION est généré. En règle générale, les développeurs n’ont pas besoin d’inspecter le fichier stub pendant le développement, bien que le fichier stub contienne tous les détails sur les spécifications de stratégie.

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

Implémentation de routines d’assistance dans les fichiers stub

Wsutil génère des routines d’assistance pour simplifier les appels d’application à WsCreateServiceProxy et créer WS_SERVICE_ENDPOINT base sur les informations fournies dans les paramètres de stratégie.

Dépend des contraintes de liaison spécifiées pour le port donné, le premier argument est différent selon la structure du modèle. L’exemple suivant suppose que le transport HTTP, la signature pour la création du proxy de service est similaire à un paramètre de type de canal supplémentaire.

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

Paramètres de stratégie pris en charge

Le tableau suivant répertorie tous les types de modèles de liaison pris en charge, les liaisons de sécurité correspondantes requises dans le type, la structure de modèle à remplir par application pour le type et le type de description correspondant. L’application doit remplir la structure du modèle, tandis que le développeur d’applications doit comprendre quelles sont les liaisons de sécurité requises dans la stratégie donnée.

WS_BINDING_TEMPLATE_TYPE Combinaisons de liaisons de sécurité structure de modèle à remplir par application description de la stratégie
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 et 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 et 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 et 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 et 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 et 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 et WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING avec WS_USERNAME_MESSAGE_SECURITY_BINDING dans le canal de démarrage 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 et WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING avec WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING dans le canal de démarrage 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 et WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING avec WS_USERNAME_MESSAGE_SECURITY_BINDING dans le canal de démarrage 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 et WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING avec WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING dans le canal d’amorçage WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

Par exemple, WS_HTTP_SSL_BINDING_TEMPLATE_TYPE indique la stratégie d’entrée pour la liaison spécifie le transport HTTP et WS_SSL_TRANSPORT_SECURITY_BINDING. L’application doit remplir WS_HTTP_SSL_BINDING_TEMPLATE structure avant d’appeler les routines d’assistance, et la description de la stratégie correspondante est WS_HTTP_SSL_POLICY_DESCRIPTION. Plus précisément, la section de liaison dans WSDL contient les segments suivants :

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

Prise en charge du contexte de sécurité

Dans contexte de sécurité, le canal de démarrage est créé pour établir la conversation sécurisée dans le canal de service. Wsutil prend uniquement en charge le scénario où le canal d’amorçage est le même que le canal de service, avec les mêmes propriétés de canal et les mêmes propriétés de sécurité. La sécurité du transport est requise pour la liaison de message de contexte de sécurité ; wsutil prend en charge les canaux de démarrage avec d’autres liaisons de sécurité de message, mais prend uniquement en charge le contexte de sécurité des messages comme seule liaison de sécurité de message dans le canal de service, sans combinaison avec d’autres liaisons de sécurité de message. Les développeurs peuvent prendre en charge ces combinaisons en dehors de la prise en charge du modèle de stratégie.

L’énumération suivante fait partie de la prise en charge de la stratégie :

Les fonctions suivantes font partie de la prise en charge de la stratégie :

Les structures suivantes font partie de la prise en charge de la stratégie :