Richtlinienunterstützung
Wsutil verarbeitet in Eingabemetadaten angegebene Richtlinien und generiert Hilfsroutinen für die Unterstützung von Dienstmodellen.
Verwenden der Richtlinienunterstützung in wsutil
Entwickler sollten die folgenden Schritte ausführen, um die Richtlinienunterstützung im wsutil-Compiler zu verwenden:
- Sammeln Sie alle Eingabemetadatendateien, die für den Zielwebdienst erforderlich sind.
- Kompilieren Sie alle gesammelten WSDL-/XSD-/Richtliniendateien mithilfe wsutil.exe. Wsutil generiert einen Satz von Stubdateien und Headerdateien für jede WSDL- und XSD-Eingabedatei.
- Überprüfen Sie die generierte Headerdatei. Alle Namen der Richtlinienhilfsprogrammroutinen werden am Anfang der Headerdatei im Kommentarabschnitt aufgeführt.
- Verwenden Sie die Hilfsroutine bindingName _ CreateServiceProxy, um einen Dienstproxy zu erstellen.
- Verwenden Sie die Hilfsroutine bindingName _ CreateServiceEndpoint, um einen Dienstendpunkt zu erstellen.
- Füllen Sie die in der Methodensignatur angegebene WS _ bindingTemplateType _ BINDING _ TEMPLATE-Struktur aus. Entwickler können bei Bedarf zusätzliche Kanaleigenschaften und/oder Sicherheitseigenschaften bereitstellen.
- Rufen Sie die Hilfsroutinen auf, wenn ein erfolgreicher Rückgabedienstproxy oder Dienstendpunkt erstellt wurde.
In den folgenden Abschnitten werden verwandte Themen ausführlich beschrieben.
Behandeln von Richtlinieneingaben
Im Folgenden werden Compileroptionen im Zusammenhang mit der Richtlinienverarbeitung angezeigt.
Standardmäßig generiert wsutil immer Richtlinienvorlagen, es sei denn, es wird mit der Option "/nopolicy" aufgerufen. Die Richtlinie kann als Teil einer WSDL-Datei eingebettet oder separat als Richtlinienmetadatendatei erstellt werden, die wsutil als Eingabe verwendet. Die Compileroption "/wsp:" wird verwendet, um anzugeben, dass die angegebenen Eingabemetadaten eine Richtliniendatei sind. Wsutil generiert potenzielle richtlinienbezogene Hilfsmöglichkeiten mit der folgenden Kompilierung:
wsutil /wsdl:trusted.wsdl /wsdl:trusted1.wsdl
wstuil /wsdl:input.wsdl /wsp:policy.wsp
Es werden keine Richtlinienhilfshilfen generiert, wenn die Option "/nopolicy" wie im folgenden Beispiel verwendet wird.
wsutil /nopolicy /wsdl:trusted.wsdl /wsdl:trusted1.wsdl
Richtlinienbezogener Code, der vom wsutil-Compiler generiert wird
Auf der Seite Metadatenzuordnung wird die Zuordnung zwischen Metadatenkonstrukten mit unterschiedlichen Bindungstypen ausführlich erläutert.
Drei Kategorien von Richtlinieneinstellungen können in richtlinieneinstellungen angegeben werden:
- Kanaleigenschaften. Derzeit werden nur die folgenden Kanaleigenschaften unterstützt: WS _ CHANNEL PROPERTY _ _ ENCODING, WS CHANNEL PROPERTY ADDRESSING _ _ _ _ VERSION und WS CHANNEL PROPERTY ENVELOPE _ _ _ _ VERSION.
- Sicherheitseigenschaften. Derzeit werden nur die folgenden Sicherheitseigenschaften unterstützt: WS _ SECURITY PROPERTY _ _ TIMESTAMP _ USAGE, WS SECURITY PROPERTY SECURITY _ _ HEADER _ _ _ LAYOUT, WS SECURITY PROPERTY TRANSPORT _ _ PROTECTION _ _ _ LEVEL und WS SECURITY PROPERTY SECURITY _ _ HEADER _ _ _ VERSION.
- Sicherheitsbindung. Derzeit werden nur die folgenden Sicherheitsbindungen unterstützt: 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 _ _ BINDINGund WS SECURITY CONTEXT MESSAGE _ SECURITY _ _ _ _ BINDING.
Bindungsvorlagentyp
Es gibt eine begrenzte Anzahl von Bindungen, die in wsutil unterstützt werden. Alle unterstützten Kombinationen dieser Bindungen sind in der WS _ BINDING TEMPLATE _ _ TYPE-Definition aufgeführt. Beispiel für die folgende Bindung in wsdl
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
Wsutil generiert den Bindungsvorlagentyp WS _ HTTP BINDING TEMPLATE _ _ _ TYPE für diese Bindung.
Richtlinienbeschreibungen
Mit der Eingaberichtlinieneinstellung generiert wsutil eine Reihe von Richtlinienbeschreibungen, die die Eingaberichtlinie beschreiben, einschließlich des Vorlagentyps sowie der in der Richtlinie angegebenen Werte. Zum Beispiel für die Eingabe
<wsdl:binding...>
<soap11:binding.../> =< WS_ENVELOPE_VERSION_SOAP_1_1
</wsdl:binding>
wsutil generiert eine Beschreibung der Channeleigenschaft wie folgt:
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 Richtlinieneinstellungen (Kanaleigenschaften, Sicherheitseigenschaften und Sicherheitsbindungseigenschaften) in einer Bindung werden in einer _ WS-BindungTemplateType _ POLICY _ DESCRIPTION-Struktur aggregiert. WS _ BINDING _ TEMPLATE _ TYPE gibt die verschiedenen Bindungsrichtlinienkombinationen an, die wsutil unterstützt.
Vorlagenstruktur, die nach Anwendung ausgefüllt werden soll
Die Richtlinienbeschreibung enthält alle Richtlinieninformationen, die in den Eingabemetadaten für eine bestimmte Bindung angegeben sind. Es gibt jedoch Informationen, die in der Richtlinie noch nicht dargestellt werden können und benutzereingaben erfordern, wenn diese Richtlinieneinstellung zum Erstellen eines Dienstproxys und/oder Dienstendpunkts verwendet wird. Beispielsweise muss die Anwendung Anmeldeinformationen für die HTTP-Headerauthentifizierung bereitstellen.
Die Anwendung muss die Vorlagenstruktur namens WS _ bindingTemplateType _ BINDING TEMPLATE für jeden anderen _ Bindungsvorlagentyp ausfüllen, der in webservices.h definiert ist:
struct WS_bindingTemplateType_BINDING_TEMPLATE
{
WS_CHANNEL_PROPERTIES channelProperties;
WS_SECURITY_PROPERTIES securityProperties;
possible_list_of_SECURITY_BINDING_TEMPLATEs;
...
};
Die Liste der Sicherheitsbindungsvorlagen ist optional und hängt von der übereinstimmenden Sicherheitsbindung ab. Beispielsweise wird das Feld WS _ SSL TRANSPORT SECURITY BINDING _ _ _ _ TEMPLATE in der _ WS-HTTP-SSL-BINDUNGSVORLAGE _ _ _ für die Anwendung angezeigt, um SSL-bezogene Sicherheitsbindungsinformationen einschließlich der Anmeldeinformationen bereitzustellen.
Die Anwendung muss alle Felder in dieser Struktur ausfüllen, bevor webservices-Vorlagen-APIs aufgerufen werden. Zusätzliche Sicherheitseigenschaften sowie Sicherheitsbindungseigenschaften, die in der Richtlinie nicht darstellbar sind, müssen ausgefüllt werden, und Webdienst-APIs führen die beiden Eigenschaften zur Laufzeit zusammen. Felder können ggf. auf null gesetzt werden. Beispielsweise können securityProperties auf null gesetzt werden, wenn keine zusätzlichen Sicherheitseigenschaften erforderlich sind.
Hilfsroutinen und Deklaration von Richtlinienbeschreibungen in Headerdateien
wsutil erstellt eine Hilfsroutine, um eine bessere Unterstützung auf Dienstmodellebene zu ermöglichen, sodass die Anwendung Dienstproxy und Dienstendpunkt einfacher erstellen kann. Die Richtlinienbeschreibung wird auch verfügbar gemacht, sodass sie von der Anwendung direkt verwendet werden können. Eine CreateSerivceProxy-Hilferoutine sieht wie folgt aus:
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);
Entwicklern wird empfohlen, diese Hilfsroutinen zu verwenden, obwohl sie auch direkt die von webservices.dll bereitgestellte Laufzeitroutine verwenden können. Entwicklern wird nicht empfohlen, die Richtlinienbeschreibungen direkt zu verwenden, wenn sie mithilfe der Dienstmodellebene programmieren.
Verweise auf Richtlinienbeschreibungen werden auch im Header für erweiterte Benutzer generiert. Wenn Entwickler keine Dienstmodellfunktionen verwenden, können sie die Richtlinienbeschreibungen direkt verwenden.
struct {
...
struct {
...
} contracts;
struct {
WS_bindingTemplateType_POLICY_DESCRIPTION bindingName;
...
} policies;
}
Definition von Prototypen in Stubdateien
Ein einzelnes Richtlinienbeschreibungsstrukturfeld pro Bindung und die zugehörigen intern referenzierten Hilfsbeschreibungen werden in der lokalen Prototypstruktur erstellt. Die Richtlinienbeschreibungen werden in der Datei generiert, in der die WS _ CONTRACT _ DESCRIPTION generiert wird. Im Allgemeinen müssen Entwickler die Stubdatei während der Entwicklung nicht überprüfen, obwohl die Stubdatei alle Details zu den Richtlinienspezifikationen enthält.
struct {
...
struct {
... } contracts;
...
struct {
struct {
hierarchy of policy template descriptions;
} bindingName;
...
list of bindings in the input wsdl file.
} policies;
} fileNameLocalDefinitions;
Implementierung von Hilfsroutinen in den Stubdateien
Wsutil generiert Hilfsprogrammroutinen, um Anwendungsaufrufe von WsCreateServiceProxy zu vereinfachen und WS _ SERVICE _ ENDPOINT auf Grundlage der Informationen in den Richtlinieneinstellungen zu erstellen.
Abhängig von den Bindungseinschränkungen, die für den angegebenen Port angegeben sind, unterscheidet sich das erste Argument je nach Vorlagenstruktur. Im folgenden Beispiel wird von HTTP-Transport ausgegangen. Die Signatur für die Erstellung des Dienstproxys ähnelt einem zusätzlichen Kanaltypparameter.
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);
}
Unterstützte Richtlinieneinstellungen
In der folgenden Tabelle sind alle unterstützten Bindungsvorlagentypen, die übereinstimmenden Sicherheitsbindungen, die für den Typ erforderlich sind, die Vorlagenstruktur, die von der Anwendung für den Typ ausgefüllt werden soll, und der Typ der übereinstimmenden Beschreibung aufgeführt. Die Anwendung muss die Vorlagenstruktur ausfüllen, während Anwendungsentwickler verstehen sollten, welche Sicherheitsbindungen in der angegebenen Richtlinie erforderlich sind.
Beispiel: WS _ HTTP SSL BINDING TEMPLATE _ _ _ _ TYPE gibt die Eingaberichtlinie für die Bindung an, die HTTP-Transport und WS SSL TRANSPORT SECURITY _ _ _ _ BINDINGangibt. Die Anwendung muss die WS _ HTTP SSL _ BINDING _ _ TEMPLATE-Struktur ausfüllen, bevor die Hilfsroutinen aufgerufen werden, und die entsprechende Richtlinienbeschreibung lautet WS HTTP SSL POLICY _ _ _ _ DESCRIPTION. Genauer gesagt enthält der Bindungsabschnitt in WSDL die folgenden Segmente:
<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>
Unterstützung des Sicherheitskontexts
Im Sicherheitskontextwird der Bootstrapkanal erstellt, um die sichere Konversation im Dienstkanal einzurichten. Wsutil unterstützt nur das Szenario, in dem der Bootstrapkanal mit denselben Kanaleigenschaften und Sicherheitseigenschaften identisch ist wie der Dienstkanal. Transportsicherheit ist für die Nachrichtenbindung im Sicherheitskontext erforderlich. wsutil unterstützt Bootstrapkanäle mit anderen Nachrichtensicherheitsbindungen, unterstützt aber nur den Sicherheitskontext als einzige Nachrichtensicherheitsbindung im Dienstkanal, ohne kombination mit anderen Nachrichtensicherheitsbindungen. Entwickler können diese Kombinationen außerhalb der Richtlinienvorlagenunterstützung unterstützen.
Die folgende Enumeration ist Teil der Richtlinienunterstützung:
Die folgenden Funktionen sind Teil der Richtlinienunterstützung:
Die folgenden Strukturen sind Teil der Richtlinienunterstützung:
- _ _ WS-HTTP-BINDUNGSVORLAGE _
- _ _ _ WS-HTTP-HEADER-AUTHENTIFIZIERUNGSBINDUNGSVORLAGE _ _
- BESCHREIBUNG DER _ WS-HTTP-HEADERAUTHENTIFIZIERUNGSRICHTLINIE _ _ _ _
- BESCHREIBUNG DER SICHERHEITSBINDUNGSRICHTLINIE FÜR DIE _ WS-HTTP-HEADERAUTHENTIFIZIERUNG _ _ _ _ _ _
- _WS-HTTP-HEADER- _ _ _ AUTHENTIFIZIERUNGSSICHERHEITSBINDUNGSVORLAGE _ _
- _WS-HTTP-RICHTLINIENBESCHREIBUNG _ _
- _ _ WS-HTTP-SSL-BINDUNGSVORLAGE _ _
- WS _ HTTP SSL HEADER AUTH BINDING TEMPLATE (WS-HTTP-SSL-HEADER-AUTHENTIFIZIERUNGSBINDUNGSVORLAGE) _ _ _ _ _
- BESCHREIBUNG DER _ _ _ _ _ AUTHENTIFIZIERUNGSRICHTLINIE _ FÜR WS-HTTP-SSL-HEADER
- _ _ _ _ WS-HTTP-SSL-KERBEROS-APREQ-BINDUNGSVORLAGE _ _
- WS _ HTTP _ SSL _ KERBEROS _ APREQ _ POLICY _ DESCRIPTION
- _ _ _ _ WS-SSL-KERBEROS-APREQ-SICHERHEITSKONTEXTBINDUNGSVORLAGE _ _ _ _
- WS _ HTTP _ SSL _ KERBEROS _ APREQ _ SECURITY _ CONTEXT _ POLICY _ DESCRIPTION
- BESCHREIBUNG DER _ WS-HTTP-SSL-RICHTLINIE _ _ _
- WS _ HTTP _ SSL _ USERNAME _ BINDING _ TEMPLATE
- BESCHREIBUNG DER _ WS-HTTP-SSL-BENUTZERNAMENSRICHTLINIE _ _ _ _
- WS _ HTTP _ SSL _ USERNAME _ SECURITY _ CONTEXT _ BINDING _ TEMPLATE
- BESCHREIBUNG DER SICHERHEITSKONTEXTRICHTLINIE FÜR DEN _ WS-HTTP-SSL-BENUTZERNAMEN _ _ _ _ _ _
- WS _ KERBEROS _ APREQ _ MESSAGE _ SECURITY _ BINDING _ POLICY _ DESCRIPTION
- WS _ _ KERBEROS-APREQ-NACHRICHTENSICHERHEITSBINDUNGSVORLAGE _ _ _ _
- BESCHREIBUNG DER _ SICHERHEITSBINDUNGSRICHTLINIE FÜR WS-SICHERHEITSKONTEXTNACHRICHTEN _ _ _ _ _ _
- _ _ _ _ _ WS-SICHERHEITSKONTEXT-NACHRICHTENSICHERHEITSBINDUNGSVORLAGE _
- BESCHREIBUNG DER _ _ _ _ _ SICHERHEITSBINDUNGSRICHTLINIE _ FÜR DEN WS-SICHERHEITSKONTEXT
- _ _ _ _ WS-SICHERHEITSKONTEXT-SICHERHEITSBINDUNGSVORLAGE _
- BESCHREIBUNG DER _ WS-SSL-TRANSPORTSICHERHEITSRICHTLINIE _ _ _ _ _
- _ _ _ WS-SSL-TRANSPORTSICHERHEITSBINDUNGSVORLAGE _ _
- BESCHREIBUNG DER _ WS-SSPI-TRANSPORTSICHERHEITSRICHTLINIE _ _ _ _ _
- _ _ WS-TCP-BINDUNGSVORLAGE _
- _ _ WS-TCP-RICHTLINIENBESCHREIBUNG _
- _ _ WS-TCP-SSPI-BINDUNGSVORLAGE _ _
- _ _ _ _ WS-TCP-SSPI-KERBEROS-APREQ-BINDUNGSVORLAGE _ _
- 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-RICHTLINIENBESCHREIBUNG _
- _ _ _ WS-TCP-SSPI-TRANSPORTSICHERHEITSBINDUNGSVORLAGE _ _ _
- BINDUNGSVORLAGE FÜR WS _ _ TCP-SSPI-BENUTZERNAME _ _ _
- BESCHREIBUNG DER WS _ _ TCP-SSPI-BENUTZERNAMENSRICHTLINIE _ _ _
- 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