Prise en charge des stratégies

Article
06/13/2023

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 des modèles 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 des stratégies 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 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 commentaire 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é si nécessaire.
Appelez les routines d’assistance, une fois le proxy de service de retour réussi ou le point de terminaison de service est créé.

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

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 s’il est appelé avec l’option « /nopolicy ». La stratégie peut être incorporée dans un fichier WSDL ou peut être créée séparément en tant que fichier de métadonnées de stratégie que wsutil prend 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 assistances potentielles liées aux stratégies 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

La page Mappage des métadonnées 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 :

Propriétés du canal. Actuellement, seules les propriétés de canal suivantes sont prises en charge : WS_CHANNEL_PROPERTY_ENCODING, WS_CHANNEL_PROPERTY_ADDRESSING_VERSION et WS_CHANNEL_PROPERTY_ENVELOPE_VERSION.
Propriétés de sécurité. Actuellement, seules les propriétés de sécurité suivantes sont prises en charge : WS_SECURITY_PROPERTY_TIMESTAMP_USAGE, WS_SECURITY_PROPERTY_SECURITY_HEADER_LAYOUT, WS_SECURITY_PROPERTY_TRANSPORT_PROTECTION_LEVEL et WS_SECURITY_PROPERTY_SECURITY_HEADER_VERSION.
Liaison de sécurité. Actuellement, seules les liaisons de sécurité suivantes sont prises en charge : 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 et WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING.

Type de modèle de liaison

Il existe un nombre limité de liaisons prises en charge dans wsutil. Toutes les 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 la description de la propriété de canal, comme suit :

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 ce paramètre de stratégies 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éfinie 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 remplir tous les champs de cette structure avant d’appeler les API de modèle de services web. Les propriétés de sécurité supplémentaires, ainsi que les propriétés de liaison de sécurité qui ne sont pas représentables dans la stratégie, doivent être renseignées, et les API de services web fusionnent les deux ensembles de propriétés dans le runtime. Les champs peuvent être supprimés si cela n’est pas applicable. 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 de modèle de service, afin que l’application puisse créer plus facilement un proxy de service et un point de terminaison de service. La description de la stratégie est également exposée afin 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, même s’ils peuvent également utiliser directement la routine d’exécution sous-jacente 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 la couche de modèle de service .

Les références de description de stratégie sont également générées dans l’en-tête pour l’utilisateur avancé. Si les développeurs n’utilisent pas les fonctionnalités du 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 des fichiers stub

Un seul champ de structure de description de stratégie par liaison et ses descriptions d’assistance référencées en interne sont créés dans la structure de prototype locale. Les descriptions de stratégie sont générées dans le fichier où 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 des 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 avec 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 d’amorçage	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 d’amorçage	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 d’amorçage	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 que 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 le contexte de sécurité, le canal d’amorçage 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 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 d’amorçage avec d’autres liaisons de sécurité de message, mais prend uniquement en charge le contexte de sécurité 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 des modèles de stratégie.

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

WS_BINDING_TEMPLATE_TYPE

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 :

Partager via

Prise en charge des stratégies

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

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

Paramètres de stratégie pris en charge

Prise en charge du contexte de sécurité

Commentaires

Ressources supplémentaires

Partager via

Prise en charge des stratégies

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

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

Code lié à la stratégie généré par le compilateur wsutil

Paramètres de stratégie pris en charge

Prise en charge du contexte de sécurité

Commentaires

Ressources supplémentaires