Condividi tramite

Supporto dei criteri

  • Articolo

Wsutil elabora i criteri specificati nei metadati di input e genera routine helper per il supporto del modello di servizio.

Come usare il supporto dei criteri in wsutil

Gli sviluppatori devono seguire questa procedura per usare il supporto dei criteri nel compilatore wsutil:

  • Raccogliere tutti i file di metadati di input necessari per il servizio Web di destinazione.
  • Compilare tutti i file WSDL/XSD/policy raccolti usando wsutil.exe. Wsutil genera un set di file stub e file di intestazione per ogni file WSDL e XSD di input.
  • Esaminare il file di intestazione generato, tutti i nomi di routine dell'helper dei criteri sono elencati nella sezione commento all'inizio del file di intestazione.
  • Usare bindingName_CreateServiceProxy routine helper per creare il proxy del servizio.
  • Usare bindingName_CreateServiceEndpoint routine helper per creare l'endpoint di servizio.
  • Compilare WS_bindingTemplateType_BINDING_TEMPLATE struttura specificata nella firma del metodo. Gli sviluppatori possono fornire proprietà di canale aggiuntive e/o proprietà di sicurezza in base alle esigenze.
  • Chiamare le routine helper, al termine della creazione del proxy del servizio restituito o dell'endpoint di servizio.

Le sezioni seguenti descrivono in dettaglio gli argomenti correlati.

Gestire l'input dei criteri

Di seguito sono riportate le opzioni del compilatore correlate all'elaborazione dei criteri.

Per impostazione predefinita, wsutil genererà sempre modelli di criteri a meno che non venga chiamato con l'opzione "/nopolicy". I criteri possono essere incorporati come parte di un file WSDL o possono essere creati separatamente come file di metadati dei criteri che wsutil accetta come input. L'opzione del compilatore "/wsp:" viene usata per indicare che i metadati di input specificati sono un file di criteri. Wsutil genera potenziali helper correlati ai criteri con la compilazione seguente:

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

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

Nessun helper dei criteri viene generato quando l'opzione "/nopolicy" viene usata come nell'esempio seguente.

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

La pagina Mapping dei metadati descrive in dettaglio il mapping tra costrutti di metadati con tipi di associazione diversi.

Nelle impostazioni dei criteri è possibile specificare tre categorie di impostazioni dei criteri:

Tipo di modello di associazione

Esistono un numero limitato di associazioni supportate in wsutil. Tutte le combinazioni supportate di queste associazioni sono elencate nella definizione WS_BINDING_TEMPLATE_TYPE . Ad esempio, per l'associazione seguente in wsdl

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

Wsutil genera WS_HTTP_BINDING_TEMPLATE_TYPE tipo di modello di associazione per questa associazione.

Descrizioni dei criteri

Con l'impostazione dei criteri di input, wsutil genera un set di descrizioni dei criteri che descrivono i criteri di input, incluso il tipo di modello, nonché i valori specificati nei criteri. Ad esempio, per l'input

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

wsutil genera una descrizione della proprietà del canale, ad esempio:

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

Tutte le impostazioni dei criteri (proprietà del canale, proprietà di sicurezza e proprietà dell'associazione di sicurezza) in un'associazione vengono aggregate in una struttura WS_bindingTemplateType_POLICY_DESCRIPTION. WS_BINDING_TEMPLATE_TYPE specifica le diverse combinazioni di criteri di associazione supportate da wsutil.

Struttura del modello da compilare dall'applicazione

La descrizione dei criteri contiene tutte le informazioni sui criteri specificate nei metadati di input per una determinata associazione, ma esistono informazioni che non possono essere rappresentate nei criteri, ma richiedono l'input dell'utente quando si usano tali impostazioni di criteri per creare il proxy del servizio e/o l'endpoint di servizio. Ad esempio, l'applicazione deve fornire le credenziali per l'autenticazione dell'intestazione HTTP.

L'applicazione deve compilare la struttura del modello, denominata WS_bindingTemplateType_BINDING_TEMPLATE per ogni tipo di modello di associazione diverso, definito in webservices.h:

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

L'elenco dei modelli di associazione di sicurezza è facoltativo dipende dall'associazione di sicurezza corrispondente. Ad esempio, WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE campo viene presentato in WS_HTTP_SSL_BINDING_TEMPLATE per l'applicazione per fornire informazioni di associazione di sicurezza correlate a SSL, incluse le informazioni sulle credenziali.

L'applicazione deve compilare tutti i campi di questa struttura prima di chiamare le API modello dei servizi Web. È necessario compilare proprietà di sicurezza aggiuntive, nonché proprietà di associazione di sicurezza che non sono rappresentabili nei criteri e le API dei servizi Web unisce il due set di proprietà in fase di esecuzione. Se non applicabile, i campi possono essere azzerato. Ad esempio, securityProperties può essere azzerato se non sono necessarie proprietà di sicurezza aggiuntive.

Routine helper e dichiarazione di descrizione dei criteri nei file di intestazione

wsutil crea routine helper per semplificare il supporto nel livello del modello di servizio, in modo che l'applicazione possa creare più facilmente proxy di servizio ed endpoint di servizio. La descrizione dei criteri viene esposta anche in modo che l'applicazione possa usarle direttamente. Una routine della Guida CreateSerivceProxy ha un aspetto simile al seguente:

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

Gli sviluppatori sono invitati a usare queste routine helper, anche se possono usare direttamente la routine di runtime sottostante fornita da webservices.dll. Gli sviluppatori non sono invitati a usare le descrizioni dei criteri direttamente durante la programmazione usando il livello del modello di servizio .

I riferimenti alla descrizione dei criteri vengono generati anche nell'intestazione per l'utente avanzato. Se gli sviluppatori non usano le funzionalità del modello di servizio, possono usare direttamente le descrizioni dei criteri.

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

Prototipi di definizione nei file stub

Nella struttura del prototipo locale vengono creati un singolo campo della struttura della descrizione dei criteri per ogni associazione e le relative descrizioni helper a cui si fa riferimento internamente. Le descrizioni dei criteri vengono generate nel file in cui viene generato il WS_CONTRACT_DESCRIPTION . In genere gli sviluppatori non devono esaminare il file stub durante lo sviluppo, anche se il file stub contiene tutti i dettagli sulle specifiche dei criteri.

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

Implementazione delle routine helper nei file stub

Wsutil genera routine helper per semplificare le chiamate dell'applicazione a WsCreateServiceProxy e la creazione di WS_SERVICE_ENDPOINT in base alle informazioni fornite nelle impostazioni dei criteri.

Dipende dai vincoli di associazione specificati per la porta specificata, il primo argomento è diverso in base alla struttura del modello. Nell'esempio seguente si presuppone che il trasporto HTTP, la firma per la creazione del proxy del servizio sia simile a un parametro di tipo di canale aggiuntivo.

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

Impostazioni dei criteri supportate

Nella tabella seguente sono elencati tutti i tipi di modello di associazione supportati, le associazioni di sicurezza corrispondenti richieste nel tipo, la struttura del modello da compilare in base all'applicazione per il tipo e il tipo di descrizione corrispondente. L'applicazione deve compilare la struttura del modello, mentre lo sviluppatore dell'applicazione deve comprendere quali sono le associazioni di sicurezza necessarie nei criteri specificati.

WS_BINDING_TEMPLATE_TYPE Combinazioni di associazioni di sicurezza struttura del modello da compilare dall'applicazione descrizione dei criteri
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 e 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 e 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 e 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 e 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 e 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_USERNAME_MESSAGE_SECURITY_BINDING nel canale bootstrap 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING nel canale bootstrap 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_USERNAME_MESSAGE_SECURITY_BINDING nel canale bootstrap 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING con WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING nel canale bootstrap WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

Ad esempio, WS_HTTP_SSL_BINDING_TEMPLATE_TYPE indica i criteri di input per l'associazione specifica il trasporto HTTP e WS_SSL_TRANSPORT_SECURITY_BINDING. L'applicazione deve compilare WS_HTTP_SSL_BINDING_TEMPLATE struttura prima di chiamare le routine helper e la descrizione dei criteri corrispondenti è WS_HTTP_SSL_POLICY_DESCRIPTION. In particolare, la sezione binding in WSDL contiene i segmenti seguenti:

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

Supporto del contesto di sicurezza

In Contesto di sicurezza viene creato il canale bootstrap per stabilire la conversazione sicura nel canale del servizio. Wsutil supporta solo lo scenario in cui il canale bootstrap è lo stesso del canale del servizio, con le stesse proprietà del canale e le stesse proprietà di sicurezza. La sicurezza del trasporto è necessaria per l'associazione di messaggi del contesto di sicurezza; wsutil supporta i canali bootstrap con altre associazioni di sicurezza dei messaggi, ma supporta solo il contesto di sicurezza come unica associazione di sicurezza dei messaggi nel canale del servizio, senza combinazione con altre associazioni di sicurezza dei messaggi. Gli sviluppatori possono supportare tali combinazioni al di fuori del supporto dei modelli di criteri.

L'enumerazione seguente fa parte del supporto dei criteri:

Le funzioni seguenti fanno parte del supporto dei criteri:

Le strutture seguenti fanno parte del supporto dei criteri: