Freigeben über

Richtlinienunterstützung

  • Artikel

Wsutil verarbeitet die in Eingabemetadaten angegebene Richtlinie 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 von 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 Richtlinienhilfsroutine sind im Kommentarabschnitt am Anfang der Headerdatei aufgeführt.
  • Verwenden Sie bindingName_CreateServiceProxy Hilfsroutine, um einen Dienstproxy zu erstellen.
  • Verwenden Sie bindingName_CreateServiceEndpoint Hilfsroutine, um einen Dienstendpunkt zu erstellen.
  • Geben Sie WS_bindingTemplateType_BINDING_TEMPLATE struktur ein, die in der Methodensignatur angegeben ist. Entwickler können bei Bedarf zusätzliche Kanaleigenschaften und/oder Sicherheitseigenschaften bereitstellen.
  • Rufen Sie die Hilfsroutinen auf, wenn erfolgreich ein Rückgabedienstproxy oder Dienstendpunkt erstellt wird.

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

Behandeln von Richtlinieneingaben

Im Folgenden finden Sie Compileroptionen im Zusammenhang mit der Richtlinienverarbeitung.

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 es sich bei den angegebenen Eingabemetadaten um eine Richtliniendatei handelt. Wsutil generiert potenzielle richtlinienbezogene Hilfsprogramme mit der folgenden Kompilierung:

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

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

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

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

Auf der Seite Metadatenzuordnung wird die Zuordnung zwischen Metadatenkonstrukten mit unterschiedlichen Bindungstypen beschrieben.

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

Bindungsvorlagentyp

Es gibt eine begrenzte Anzahl von Bindungen, die in wsutil unterstützt werden. Alle unterstützten Kombinationen dieser Bindungen sind in 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 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 der in der Richtlinie angegebenen Werte. Beispielsweise für Eingaben

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

wsutil generiert eine Beschreibung der Kanaleigenschaft 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 zu einer WS_bindingTemplateType_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, aber es gibt Informationen, die in der Richtlinie nicht dargestellt werden können, aber eine Benutzereingabe erfordern, wenn diese Richtlinieneinstellung zum Erstellen des Dienstproxys und/oder Dienstendpunkts verwendet wird. 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 verschiedenen 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 entsprechenden 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 Informationen zur Sicherheitsbindung bereitzustellen, einschließlich der Anmeldeinformationen.

Die Anwendung muss alle Felder in dieser Struktur ausfüllen, bevor webservicevorlagen-APIs aufgerufen werden. Zusätzliche Sicherheitseigenschaften sowie Sicherheitsbindungseigenschaften, die in der Richtlinie nicht dargestellt werden können, müssen ausgefüllt werden, und Webdienst-APIs führen die beiden Eigenschaftensätze zur Laufzeit zusammen. Felder können auf Null gesetzt werden, wenn dies nicht zutreffend ist. Beispielsweise kann securityProperties auf null gesetzt 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 dienstproxys und Dienstendpunkte einfacher erstellen kann. Die Richtlinienbeschreibung wird auch verfügbar gemacht, sodass die Anwendung sie direkt verwenden kann. 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 Unterlaufzeitroutine verwenden können. Entwicklern wird nicht empfohlen, die Richtlinienbeschreibungen bei der Programmierung mithilfe der Dienstmodellebene direkt 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 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 Hilfsroutinen, um Anwendungsaufrufe an WsCreateServiceProxy zu vereinfachen und WS_SERVICE_ENDPOINT basierend auf Informationen zu erstellen, die in Den Richtlinieneinstellungen bereitgestellt werden.

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 davon ausgegangen, dass http-Transport, Signatur für die Erstellung des Dienstproxys mit einem zusätzlichen Kanaltypparameter ähnlich 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 im Typ erforderlichen übereinstimmenden Sicherheitsbindungen, die Vorlagenstruktur, die von der Anwendung für den Typ ausgefüllt werden soll, und der entsprechende Beschreibungstyp aufgeführt. Die Anwendung muss die Vorlagenstruktur ausfüllen, während anwendungsentwickler verstehen sollten, welche Sicherheitsbindungen in der angegebenen Richtlinie erforderlich sind.

WS_BINDING_TEMPLATE_TYPE Sicherheitsbindungskombinationen Vorlagenstruktur, die nach 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 Bootstrapkanal 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 Bootstrapkanal 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 Bootstrapkanal 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 Bootstrapkanal 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 an, dass die Eingaberichtlinie für die Bindung http-Transport und WS_SSL_TRANSPORT_SECURITY_BINDING angibt. Die Anwendung muss WS_HTTP_SSL_BINDING_TEMPLATE Struktur ausfüllen, bevor die Hilfsroutinen aufgerufen werden, und die Entsprechende Richtlinienbeschreibung ist 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 Sicherheitskontext wird der Bootstrapkanal erstellt, um die sichere Konversation im Dienstkanal einzurichten. Wsutil unterstützt nur das Szenario, in dem der Bootstrap-Kanal mit den gleichen Kanaleigenschaften und Sicherheitseigenschaften identisch mit dem Dienstkanal ist. Transportsicherheit ist für die Nachrichtenbindung im Sicherheitskontext erforderlich. wsutil unterstützt Bootstrap-Kanäle mit anderen Nachrichtensicherheitsbindungen, 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: