Delen via

Beleidsondersteuning

  • Artikel

Wsutil verwerkt beleid dat is opgegeven in invoermetagegevens en genereert helperroutines voor ondersteuning van servicemodellen.

Beleidsondersteuning gebruiken in wsutil

Ontwikkelaars moeten de volgende stappen volgen om de beleidsondersteuning in wsutil compiler te gebruiken:

  • Verzamel alle invoermetagegevensbestanden die nodig zijn voor de doelwebservice.
  • Compileer alle verzamelde WSDL-/XSD-/beleidsbestanden met behulp van wsutil.exe. Wsutil genereert één set stub-bestand en headerbestand voor elke WSDL- en XSD-invoerbestanden.
  • Controleer het gegenereerde headerbestand, alle namen van de beleidshelperroutines worden vermeld in de opmerkingensectie aan het begin van het headerbestand.
  • Gebruik bindingName_CreateServiceProxy helperroutine om een serviceproxy te maken.
  • Gebruik bindingName_CreateServiceEndpoint helperroutine om een service-eindpunt te maken.
  • Vul WS_bindingTemplateType_BINDING_TEMPLATE structuur in die is opgegeven in de methodehandtekening. Ontwikkelaars kunnen indien nodig aanvullende kanaaleigenschappen en/of beveiligingseigenschappen bieden.
  • Roep de helperroutines aan, bij een geslaagde retourserviceproxy of service-eindpunt wordt gemaakt.

In de volgende secties worden verwante onderwerpen uitgebreid beschreven.

Beleidsinvoer verwerken

Hieronder ziet u compileropties met betrekking tot beleidsverwerking.

Wsutil genereert standaard altijd beleidssjablonen, tenzij deze worden aangeroepen met de optie '/nopolicy'. Beleid kan worden ingesloten als onderdeel van een WSDL-bestand of kan afzonderlijk worden gemaakt als een bestand met beleidsmetagegevens dat wsutil als invoer gebruikt. De compileroptie '/wsp:' wordt gebruikt om aan te geven dat opgegeven invoermetagegevens een beleidsbestand is. Wsutil genereert potentiële beleidsgerelateerde helpers met de volgende compilatie:

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

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

Er worden geen beleidshelpers gegenereerd wanneer de optie '/nopolicy' wordt gebruikt, zoals in het volgende voorbeeld.

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

metagegevenstoewijzing pagina bevat informatie over de toewijzing tussen metagegevensconstructies met verschillende bindingstypen.

Er kunnen drie categorieën beleidsinstellingen worden opgegeven in beleidsinstellingen:

Type bindingssjabloon

Er zijn beperkte aantallen bindingen die worden ondersteund in wsutil. Al deze ondersteunde combinaties van deze bindingen worden vermeld in WS_BINDING_TEMPLATE_TYPE definitie. Bijvoorbeeld voor de volgende binding in wsdl

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

Wsutil genereert WS_HTTP_BINDING_TEMPLATE_TYPE bindingssjabloontype voor deze binding.

Beleidsbeschrijvingen

Met de instelling voor invoerbeleid genereert wsutil een set beleidsbeschrijvingen die het invoerbeleid beschrijven, inclusief het sjabloontype, evenals de waarden die zijn opgegeven in het beleid. Bijvoorbeeld voor invoer

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

wsutil genereert een beschrijving van de kanaaleigenschap, zoals:

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

Alle beleidsinstellingen (kanaaleigenschappen, beveiligingseigenschappen en eigenschappen van beveiligingsbindingen) in één binding worden samengevoegd in één WS_bindingTemplateType_POLICY_DESCRIPTION structuur. WS_BINDING_TEMPLATE_TYPE geeft de verschillende combinaties van bindingsbeleid wsutil ondersteunt.

Sjabloonstructuur die moet worden ingevuld door toepassing

Beleidsbeschrijving bevat alle beleidsinformatie die is opgegeven in invoermetagegevens voor een bepaalde binding, maar er zijn gegevens die niet kunnen worden weergegeven in het beleid, maar vereist gebruikersinvoer wanneer u deze beleidsinstelling gebruikt om een serviceproxy en/of service-eindpunt te maken. De toepassing moet bijvoorbeeld referenties opgeven voor HTTP-headerverificatie.

De toepassing moet de sjabloonstructuur, met de naam WS_bindingTemplateType_BINDING_TEMPLATE, invullen voor elk ander type bindingssjabloon, gedefinieerd in webservices.h:

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

De lijst met beveiligingsbindingssjablonen is optioneel, afhankelijk van de overeenkomende beveiligingsbinding. Het veld WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE wordt bijvoorbeeld weergegeven in WS_HTTP_SSL_BINDING_TEMPLATE voor toepassing om ssl-gerelateerde beveiligingsbindingsgegevens op te geven, inclusief de referentiegegevens.

De toepassing moet alle velden in deze structuur invullen voordat deze api's voor webservicessjablonen worden aangeroepen. Aanvullende beveiligingseigenschappen, evenals eigenschappen van beveiligingsbindingen die niet in beleid kunnen worden weergegeven, moeten worden ingevuld en webservices-API's voegen de twee eigenschappen in runtime samen. Velden kunnen worden uitgeschakeld als dit niet van toepassing is. SecurityProperties kunnen bijvoorbeeld worden uitgeschakeld als er geen extra beveiligingseigenschappen nodig zijn.

Helper-routines en beleidsbeschrijvingsdeclaratie in headerbestanden

wsutil maakt helperroutine om betere ondersteuning in de servicemodellaag te vergemakkelijken, zodat de toepassing serviceproxy en service-eindpunt eenvoudiger kan maken. De beleidsbeschrijving wordt ook weergegeven, zodat de toepassing deze rechtstreeks kan gebruiken. Een CreateSerivceProxy Help-routine ziet er als volgt uit:

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

Ontwikkelaars worden aangemoedigd om deze helperroutines te gebruiken, maar ze kunnen ook de onderliggende runtimeroutine van webservices.dllgebruiken. Ontwikkelaars worden niet aangemoedigd om de beleidsbeschrijvingen rechtstreeks te gebruiken bij het programmeren met servicemodel laag.

Verwijzingen naar beleidsbeschrijvingen worden ook gegenereerd in de header voor geavanceerde gebruiker. Als ontwikkelaars geen servicemodelfunctionaliteit gebruiken, kunnen ze de beleidsbeschrijvingen rechtstreeks gebruiken.

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

Prototypen van definities in stub-bestanden

Eén structuurveld voor beleidsbeschrijvingen per binding en de intern verwezen helperbeschrijvingen worden gemaakt in de lokale prototypestructuur. De beleidsbeschrijvingen worden gegenereerd in het bestand waarin de WS_CONTRACT_DESCRIPTION wordt gegenereerd. Over het algemeen hoeven ontwikkelaars het stub-bestand tijdens de ontwikkeling niet te inspecteren, hoewel het stub-bestand alle details over de beleidsspecificaties bevat.

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

Implementatie van helperroutines in de stub-bestanden

Wsutil genereert helperroutines om toepassingsoproepen naar WsCreateServiceProxy- te vereenvoudigen en WS_SERVICE_ENDPOINT basis te maken op informatie in beleidsinstellingen.

Afhankelijk van de bindingsbeperkingen die zijn opgegeven voor de opgegeven poort, is het eerste argument anders op basis van de sjabloonstructuur. In het volgende voorbeeld wordt ervan uitgegaan dat HTTP-transport, handtekening voor het maken van de serviceproxy vergelijkbaar is met één extra parameter voor kanaaltypen.

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

Ondersteunde beleidsinstellingen

De volgende tabel bevat alle ondersteunde bindingssjabloontypen, de overeenkomende beveiligingsbindingen die vereist zijn in het type, de sjabloonstructuur die moet worden ingevuld door de toepassing voor het type en het overeenkomende beschrijvingstype. De toepassing moet de sjabloonstructuur invullen, terwijl toepassingsontwikkelaar moet begrijpen wat de beveiligingsbindingen zijn die vereist zijn in het opgegeven beleid.

WS_BINDING_TEMPLATE_TYPE Combinaties van beveiligingsbindingen sjabloonstructuur die moet worden ingevuld door toepassing beleidsbeschrijving
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 en 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 en 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 en 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 en 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 en 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 en WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING met WS_USERNAME_MESSAGE_SECURITY_BINDING in bootstrapkanaal 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 en WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING met WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING in bootstrapkanaal 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 en WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING met WS_USERNAME_MESSAGE_SECURITY_BINDING in bootstrapkanaal 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 en WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING met WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING in bootstrapkanaal WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

WS_HTTP_SSL_BINDING_TEMPLATE_TYPE geeft bijvoorbeeld aan dat het invoerbeleid voor de binding HTTP-transport aangeeft en WS_SSL_TRANSPORT_SECURITY_BINDING. De toepassing moet WS_HTTP_SSL_BINDING_TEMPLATE structuur invullen voordat de helperroutines worden aangeroepen en de beschrijving van het overeenkomende beleid wordt WS_HTTP_SSL_POLICY_DESCRIPTION. Meer specifiek bevat de bindingssectie in WSDL de volgende segmenten:

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

Ondersteuning voor beveiligingscontext

In Security Contextwordt het bootstrap-kanaal gemaakt om het beveiligde gesprek in het servicekanaal tot stand te brengen. Wsutil ondersteunt alleen het scenario waarbij bootstrap-kanaal hetzelfde is als het servicekanaal, met dezelfde kanaaleigenschappen en beveiligingseigenschappen. Transportbeveiliging is vereist voor binding van beveiligingscontextberichten; wsutil ondersteunt bootstrapkanalen met andere berichtbeveiligingsbindingen, maar ondersteunt alleen beveiligingscontext als de enige berichtbeveiligingsbinding in het servicekanaal, zonder combinatie met andere berichtbeveiligingsbindingen. Ontwikkelaars kunnen deze combinaties buiten de beleidssjabloonondersteuning ondersteunen.

De volgende inventarisatie maakt deel uit van beleidsondersteuning:

De volgende functies maken deel uit van beleidsondersteuning:

De volgende structuren maken deel uit van beleidsondersteuning: