Dela via

Principstöd

  • Artikel

Wsutil bearbetar principen som anges i indatametadata och genererar hjälprutiner för servicemodellstöd.

Så här använder du principstöd i wsutil

Utvecklare bör följa följande steg för att använda principstöd i wsutil-kompilatorn:

  • Samla in alla indatametadatafiler som krävs för den riktade webbtjänsten.
  • Kompilera alla insamlade WSDL/XSD/principfiler med hjälp av wsutil.exe. Wsutil genererar en uppsättning stub-filer och huvudfiler för varje WSDL- och XSD-indatafiler.
  • Granska den genererade huvudfilen. Alla rutinnamn för principhjälp visas i kommentarsavsnittet i början av rubrikfilen.
  • Använd bindingName_CreateServiceProxy hjälprutin för att skapa tjänstproxy.
  • Använd bindingName_CreateServiceEndpoint hjälprutin för att skapa tjänstslutpunkt.
  • Fyll i WS_bindingTemplateType_BINDING_TEMPLATE struktur som anges i metodsignaturen. Utvecklare kan tillhandahålla ytterligare kanalegenskaper och/eller säkerhetsegenskaper efter behov.
  • Anropa hjälprutinerna när en tjänstproxy eller tjänstslutpunkt har skapats.

I följande avsnitt beskrivs relaterade ämnen i detalj.

Hantera principindata

Följande är kompilatoralternativ relaterade till principbearbetning.

Som standard genererar wsutil alltid principmallar om det inte anropas med alternativet "/nopolicy". Principen kan bäddas in som en del av en WSDL-fil eller skapas separat som en principmetadatafil som wsutil tar som indata. Kompilatoralternativet "/wsp:" används för att indikera att angivna metadata för indata är en principfil. Wsutil genererar potentiella principrelaterade hjälpfunktioner med följande kompilering:

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

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

Inga principhjälpare genereras när alternativet "/nopolicy" används som i följande exempel.

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

metadatamappning sidan beskriver mappningen mellan metadatakonstruktioner med olika bindningstyper.

Tre kategorier av principinställningar kan anges i principinställningar:

Typ av bindningsmall

Det finns ett begränsat antal bindningar som stöds i wsutil. Alla kombinationer som stöds av dessa bindningar visas i WS_BINDING_TEMPLATE_TYPE definition. Till exempel för följande bindning i wsdl

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

Wsutil genererar WS_HTTP_BINDING_TEMPLATE_TYPE bindningsmalltyp för den här bindningen.

Principbeskrivningar

Med indataprincipinställningen genererar wsutil en uppsättning principbeskrivningar som beskriver indataprincipen, inklusive malltypen, samt de värden som anges i principen. Till exempel för indata

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

wsutil genererar kanalegenskapsbeskrivning som:

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

Alla principinställningar (kanalegenskaper, säkerhetsegenskaper och egenskaper för säkerhetsbindning) i en bindning aggregeras till en WS_bindingTemplateType_POLICY_DESCRIPTION struktur. WS_BINDING_TEMPLATE_TYPE anger de olika kombinationer av bindningsprinciper som wsutil stöder.

Mallstruktur som ska fyllas i av programmet

Principbeskrivningen innehåller all principinformation som anges i indatametadata för en viss bindning, men det finns information som inte kan representeras i principen men som kräver användarindata när du använder den här principinställningen för att skapa tjänstproxy och/eller tjänstslutpunkt. Programmet måste till exempel ange autentiseringsuppgifter för HTTP-huvudautentisering.

Programmet måste fylla i mallstrukturen med namnet WS_bindingTemplateType_BINDING_TEMPLATE för varje typ av bindningsmall som definieras i webservices.h:

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

Listan över säkerhetsbindningsmallar är valfri beror på den matchade säkerhetsbindningen. Till exempel visas WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE fält i WS_HTTP_SSL_BINDING_TEMPLATE för program för att tillhandahålla SSL-relaterad säkerhetsbindningsinformation, inklusive information om autentiseringsuppgifter.

Programmet måste fylla i alla fält i den här strukturen innan det anropas till webbtjänstmall-API:er. Ytterligare säkerhetsegenskaper samt säkerhetsbindningsegenskaper som inte kan representeras i principen måste fyllas i, och API:er för webbtjänster sammanfogar de två egenskaperna i körningen. Fält kan nollställas om det inte är tillämpligt. Till exempel kan securityProperties nollställas om inga ytterligare säkerhetsegenskaper behövs.

Hjälprutiner och principbeskrivningsdeklaration i huvudfiler

wsutil skapar hjälprutin för att underlätta bättre stöd i tjänstmodellskiktet, så att programmet kan skapa tjänstproxy och tjänstslutpunkt enklare. Principbeskrivningen exponeras också så att programmet kan använda dem direkt. Hjälprutinen CreateSerivceProxy ser ut så här:

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

Utvecklare uppmuntras att använda dessa hjälprutiner, men de kan också direkt använda rutinen under körning som tillhandahålls av webservices.dll. Utvecklare uppmanas inte att använda principbeskrivningarna direkt när de programmerar med hjälp av tjänstmodell lager.

Principbeskrivningsreferenser genereras också i huvudet för avancerad användare. Om utvecklare inte använder tjänstmodellfunktioner kan de använda principbeskrivningarna direkt.

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

Definitionsprototyper i stub-filer

Ett enda principbeskrivningsstrukturfält per bindning och dess internt refererade hjälpbeskrivningar skapas i den lokala prototypstrukturen. Principbeskrivningarna genereras i filen där WS_CONTRACT_DESCRIPTION genereras. Vanligtvis behöver utvecklare inte inspektera stub-filen under utvecklingen, men stub-filen innehåller all information om principspecifikationerna.

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

Implementering av hjälprutiner i stub-filerna

Wsutil genererar hjälprutiner för att förenkla programanrop till WsCreateServiceProxy och skapa WS_SERVICE_ENDPOINT grund för information som tillhandahålls i principinställningar.

Beror på de bindningsbegränsningar som angetts för den angivna porten är det första argumentet annorlunda beroende på mallstrukturen. I följande exempel förutsätts HTTP-transport, signaturen för skapande av tjänstproxy liknar en ytterligare parameter av kanaltyp.

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

Principinställningar som stöds

Följande tabell visar alla typer av bindningsmallar som stöds, de matchande säkerhetsbindningar som krävs i typen, mallstrukturen som ska fyllas i efter program för typen och matchande beskrivningstyp. Programmet måste fylla i mallstrukturen, medan programutvecklaren bör förstå vilka säkerhetsbindningar som krävs i den angivna principen.

WS_BINDING_TEMPLATE_TYPE Kombinationer av säkerhetsbindningar mallstruktur som ska fyllas i av program principbeskrivning
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 och 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 och 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 och 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 och 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 och 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 och WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING med WS_USERNAME_MESSAGE_SECURITY_BINDING i bootstrap-kanalen 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 och WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING med WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING i bootstrap-kanalen 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 och WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING med WS_USERNAME_MESSAGE_SECURITY_BINDING i bootstrap-kanalen 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 och WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING med WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING i bootstrap-kanalen WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

Till exempel anger WS_HTTP_SSL_BINDING_TEMPLATE_TYPE indataprincipen för bindningen HTTP-transport och WS_SSL_TRANSPORT_SECURITY_BINDING. Programmet måste fylla i WS_HTTP_SSL_BINDING_TEMPLATE struktur innan du anropar hjälprutinerna, och den matchande principbeskrivningen är WS_HTTP_SSL_POLICY_DESCRIPTION. Mer specifikt innehåller bindningsavsnittet i WSDL följande segment:

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

Stöd för säkerhetskontext

I Säkerhetskontextskapas bootstrap-kanalen för att upprätta den säkra konversationen i tjänstkanalen. Wsutil stöder endast scenariot där bootstrap-kanalen är samma som tjänstkanalen, med samma kanalegenskaper och säkerhetsegenskaper. Transportsäkerhet krävs för bindning av säkerhetskontextmeddelanden. wsutil stöder bootstrap-kanaler med andra meddelandesäkerhetsbindningar, men stöder endast säkerhetskontext som den enda meddelandesäkerhetsbindningen i tjänstkanalen, utan kombination med andra meddelandesäkerhetsbindningar. Utvecklare kan stödja dessa kombinationer utanför principmallens stöd.

Följande uppräkning är en del av principstöd:

Följande funktioner ingår i principstöd:

Följande strukturer ingår i principstöd: