Supporto dei criteri
Wsutil elabora i criteri specificati nei metadati di input e genera routine helper per il supporto del modello di servizio.
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.
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:
- Proprietà del canale. Attualmente sono supportate solo le proprietà del canale seguenti: WS_CHANNEL_PROPERTY_ENCODING, WS_CHANNEL_PROPERTY_ADDRESSING_VERSION e WS_CHANNEL_PROPERTY_ENVELOPE_VERSION.
- Proprietà di sicurezza. Attualmente sono supportate solo le proprietà di sicurezza seguenti: WS_SECURITY_PROPERTY_TIMESTAMP_USAGE, WS_SECURITY_PROPERTY_SECURITY_HEADER_LAYOUT, WS_SECURITY_PROPERTY_TRANSPORT_PROTECTION_LEVEL e WS_SECURITY_PROPERTY_SECURITY_HEADER_VERSION.
- Associazione di sicurezza. Attualmente sono supportate solo le associazioni di sicurezza seguenti: 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 e WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING.
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);
}
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.
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>
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:
- WS_HTTP_BINDING_TEMPLATE
- WS_HTTP_HEADER_AUTH_BINDING_TEMPLATE
- WS_HTTP_HEADER_AUTH_POLICY_DESCRIPTION
- WS_HTTP_HEADER_AUTH_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_HTTP_HEADER_AUTH_SECURITY_BINDING_TEMPLATE
- WS_HTTP_POLICY_DESCRIPTION
- WS_HTTP_SSL_BINDING_TEMPLATE
- WS_HTTP_SSL_HEADER_AUTH_BINDING_TEMPLATE
- WS_HTTP_SSL_HEADER_AUTH_POLICY_DESCRIPTION
- WS_HTTP_SSL_KERBEROS_APREQ_BINDING_TEMPLATE
- WS_HTTP_SSL_KERBEROS_APREQ_POLICY_DESCRIPTION
- WS_HTTP_SSL_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE
- WS_HTTP_SSL_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION
- WS_HTTP_SSL_POLICY_DESCRIPTION
- WS_HTTP_SSL_USERNAME_BINDING_TEMPLATE
- WS_HTTP_SSL_USERNAME_POLICY_DESCRIPTION
- WS_HTTP_SSL_USERNAME_SECURITY_CONTEXT_BINDING_TEMPLATE
- WS_HTTP_SSL_USERNAME_SECURITY_CONTEXT_POLICY_DESCRIPTION
- WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING_TEMPLATE
- WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING_TEMPLATE
- WS_SECURITY_CONTEXT_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_SECURITY_CONTEXT_SECURITY_BINDING_TEMPLATE
- WS_SSL_TRANSPORT_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE
- WS_SSPI_TRANSPORT_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_TCP_BINDING_TEMPLATE
- WS_TCP_POLICY_DESCRIPTION
- WS_TCP_SSPI_BINDING_TEMPLATE
- WS_TCP_SSPI_KERBEROS_APREQ_BINDING_TEMPLATE
- WS_TCP_SSPI_KERBEROS_APREQ_POLICY_DESCRIPTION
- WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE
- WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION
- WS_TCP_SSPI_POLICY_DESCRIPTION
- WS_TCP_SSPI_TRANSPORT_SECURITY_BINDING_TEMPLATE
- WS_TCP_SSPI_USERNAME_BINDING_TEMPLATE
- WS_TCP_SSPI_USERNAME_POLICY_DESCRIPTION
- WS_TCP_SSPI_USERNAME_SECURITY_CONTEXT_BINDING_TEMPLATE
- WS_TCP_SSPI_USERNAME_SECURITY_CONTEXT_POLICY_DESCRIPTION
- WS_USERNAME_MESSAGE_SECURITY_BINDING_POLICY_DESCRIPTION
- WS_USERNAME_MESSAGE_SECURITY_BINDING_TEMPLATE