Freigeben über

Richtlinienunterstützung

  • Artikel

Wsutil verarbeitet die in Eingabemetadaten angegebene Richtlinie und generiert Hilfsroutinen für die Unterstützung des Dienstmodells.

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 zielbezogenen Webdienst erforderlich sind.
  • Kompilieren Sie alle gesammelten WSDL/XSD/Richtliniendateien mithilfe von wsutil.exe. Wsutil generiert eine Gruppe von Stubdateien und Headerdateien für jede Eingabe-WSDL- und XSD-Datei.
  • Überprüfen Sie die generierte Headerdatei, werden alle Richtlinienhilfsroutinnamen am Anfang der Headerdatei im Kommentarabschnitt aufgeführt.
  • Verwenden Sie bindingName_CreateServiceProxy Hilfsroutine zum Erstellen des Dienstproxys.
  • Verwenden Sie bindingName_CreateServiceEndpoint Hilfsroutine zum Erstellen des Dienstendpunkts.
  • Füllen Sie WS_bindingTemplateType_BINDING_TEMPLATE Struktur aus, die in der Methodensignatur angegeben ist. Entwickler können bei Bedarf zusätzliche Kanaleigenschaften und/oder Sicherheitseigenschaften bereitstellen.
  • Rufen Sie die Hilfsroutinen auf, wird bei einem erfolgreichen Rückgabedienstproxy oder Dienstendpunkt erstellt.

In den folgenden Abschnitten werden verwandte Themen ausführlich beschrieben.

Behandeln von Richtlinieneingaben

Im Folgenden werden Compileroptionen im Zusammenhang mit der Richtlinienverarbeitung aufgeführt.

Standardmäßig generiert wsutil immer Richtlinienvorlagen, es sei denn, sie werden 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 angegebene Eingabemetadaten eine Richtliniendatei sind. Wsutil generiert potenzielle richtlinienbezogene Hilfsprogramme mit der folgenden Kompilierung:

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

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

Es werden keine Richtlinienhilfsprogramme generiert, wenn die Option "/nopolicy" wie im folgenden Beispiel verwendet wird.

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

Metadatenzuordnung Seite detailiert die Zuordnung zwischen Metadatenkonstrukten mit verschiedenen Bindungstypen.

In Richtlinieneinstellungen können drei Kategorien von Richtlinieneinstellungen angegeben werden:

Bindungsvorlagentyp

Es gibt begrenzte Anzahl von Bindungen, die in wsutil unterstützt werden. Alle diese unterstützten Kombinationen dieser Bindungen werden in WS_BINDING_TEMPLATE_TYPE Definition aufgeführt. For example, for the following binding in wsdl

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

Wsutil generiert WS_HTTP_BINDING_TEMPLATE_TYPE Bindungsvorlagentyp für diese Bindung.

Richtlinienbeschreibungen

Mit der Eingaberichtlinieneinstellung generiert wsutil eine Reihe von Richtlinienbeschreibungen, die die Eingaberichtlinie beschreiben, einschließlich des Vorlagentyps, sowie die in der Richtlinie angegebenen Werte. Beispiel: für Eingaben

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

wsutil generiert kanaleigenschaftenbeschreibung wie:

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_bindingTemplateType_POLICY_DESCRIPTION Struktur aggregiert. WS_BINDING_TEMPLATE_TYPE gibt die verschiedenen Bindungsrichtlinienkombinationen an, die von wsutil unterstützt werden.

Vorlagenstruktur, die nach Anwendung ausgefüllt werden soll

Die Richtlinienbeschreibung enthält alle Richtlinieninformationen, die in Eingabemetadaten für eine bestimmte Bindung angegeben sind, aber es gibt Informationen, die in der Richtlinie nicht dargestellt werden können, aber benutzereingaben erforderlich sind, wenn sie diese Richtlinieneinstellung zum Erstellen von Dienstproxy und/oder Dienstendpunkt verwenden. Beispielsweise muss die Anwendung Anmeldeinformationen für die HTTP-Headerauthentifizierung bereitstellen.

Die Anwendung muss die Vorlagenstruktur mit dem Namen WS_bindingTemplateType_BINDING_TEMPLATE für jeden unterschiedlichen 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, hängt von der übereinstimmende Sicherheitsbindung ab. Beispielsweise wird WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE Feld in WS_HTTP_SSL_BINDING_TEMPLATE für die Anwendung angezeigt, um SSL-bezogene Sicherheitsbindungsinformationen bereitzustellen, einschließlich der Anmeldeinformationsinformationen.

Die Anwendung muss alle Felder in dieser Struktur ausfüllen, bevor Sie webservices-Vorlagen-APIs aufrufen. Zusätzliche Sicherheitseigenschaften sowie Sicherheitsbindungseigenschaften, die in der Richtlinie nicht dargestellt werden können, müssen ausgefüllt werden, und Webservices-APIs führen die beiden Eigenschaftengruppen zur Laufzeit zusammen. Felder können bei Bedarf nulliert werden. Beispielsweise können securityProperties nulliert werden, wenn keine zusätzlichen Sicherheitseigenschaften erforderlich sind.

Hilfsroutinen und Richtlinienbeschreibungsdeklaration in Headerdateien

wsutil erstellt Hilfsroutine, um eine bessere Unterstützung auf Dienstmodellebene zu ermöglichen, sodass die Anwendung den Dienstproxy und den 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);

Entwickler werden ermutigt, diese Hilfsroutinen zu verwenden, obwohl sie auch direkt die untere Laufzeitroutine verwenden können, die von webservices.dllbereitgestellt wird. Entwickler werden nicht empfohlen, die Richtlinienbeschreibungen direkt beim Programmieren mit Dienstmodell Ebene zu verwenden.

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

Definitionsprototypen in Stubdateien

Ein einzelnes Richtlinienbeschreibungsstrukturfeld pro Bindung und die 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 stub-Datei 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 Hilfsroutinen, um Anwendungsaufrufe an WsCreateServiceProxy- zu vereinfachen und WS_SERVICE_ENDPOINT Basis auf Informationen zu erstellen, die in Richtlinieneinstellungen bereitgestellt werden.

Abhängig von den für den angegebenen Port angegebenen Bindungseinschränkungen unterscheidet sich das erste Argument entsprechend der Vorlagenstruktur. Im folgenden Beispiel wird davon ausgegangen, dass der HTTP-Transport der Signatur für die Dienstproxyerstellung mit einem zusätzlichen Kanaltypparameter vergleichbar ist.

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 entsprechenden Sicherheitsbindungen aufgeführt, die für den Typ erforderlich sind, die Vorlagenstruktur, die von der Anwendung für den Typ ausgefüllt werden soll, und der entsprechende Beschreibungstyp. Die Anwendung muss die Vorlagenstruktur ausfüllen, während der Anwendungsentwickler verstehen sollte, welche Sicherheitsbindungen in der angegebenen Richtlinie erforderlich sind.

WS_BINDING_TEMPLATE_TYPE Sicherheitsbindungskombinationen Vorlagenstruktur, die von der Anwendung ausgefüllt werden soll Richtlinienbeschreibung
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 und 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 und 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 und 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 und 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 und 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 und WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING mit WS_USERNAME_MESSAGE_SECURITY_BINDING im Bootstrap-Kanal 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 und WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING mit WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING im Bootstrap-Kanal 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 und WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING mit WS_USERNAME_MESSAGE_SECURITY_BINDING im Bootstrap-Kanal 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 und WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING mit WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING im Bootstrap-Kanal WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_BINDING_TEMPLATE WS_TCP_SSPI_KERBEROS_APREQ_SECURITY_CONTEXT_POLICY_DESCRIPTION

 

Beispielsweise gibt WS_HTTP_SSL_BINDING_TEMPLATE_TYPE die Eingaberichtlinie für die Bindung den HTTP-Transport und WS_SSL_TRANSPORT_SECURITY_BINDINGan. Die Anwendung muss WS_HTTP_SSL_BINDING_TEMPLATE Struktur ausfüllen, bevor Sie die Hilfsroutinen aufrufen, und die entsprechende Richtlinienbeschreibung wird WS_HTTP_SSL_POLICY_DESCRIPTION. Genauer gesagt enthält der Bindungsabschnitt in WSDL folgende 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 von Sicherheitskontexten

In Security Contextwird der Bootstrap-Kanal erstellt, um die sichere Unterhaltung im Dienstkanal einzurichten. Wsutil unterstützt nur das Szenario, in dem der Bootstrap-Kanal mit den gleichen Kanaleigenschaften und Sicherheitseigenschaften identisch ist wie der Dienstkanal. Transportsicherheit ist für die Bindung von Sicherheitskontextnachrichten erforderlich; wsutil unterstützt Bootstrap-Kanäle mit anderen Nachrichtensicherheitsbindungen, unterstützt jedoch nur den Sicherheitskontext als einzige Nachrichtensicherheitsbindung im Dienstkanal, ohne dass eine Kombination mit anderen Nachrichtensicherheitsbindungen vorhanden ist. 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 politischen Unterstützung: