Obsługa zasad

Wsutil przetwarza zasady określone w metadanych wejściowych i generuje procedury pomocnicze na potrzeby obsługi modelu usług.

Jak używać obsługi zasad w narzędziu wsutil

Deweloperzy powinni wykonać następujące kroki, aby użyć obsługi zasad w kompilatorze wsutil:

• Zbierz wszystkie pliki metadanych wejściowych niezbędnych dla docelowej usługi internetowej.
• Skompiluj wszystkie zebrane pliki WSDL/XSD/policy przy użyciu wsutil.exe. Narzędzie Wsutil generuje jeden zestaw plików wycinkowych i pliku nagłówkowego dla każdego wejściowego pliku WSDL i XSD.
• Sprawdź wygenerowany plik nagłówka, wszystkie nazwy procedur pomocnika zasad są wymienione w sekcji komentarza na początku pliku nagłówka.
• Użyj procedury pomocnika bindingName_CreateServiceProxy, aby utworzyć serwer proxy usługi.
• Użyj procedury pomocnika bindingName_CreateServiceEndpoint, aby utworzyć punkt końcowy usługi.
• Wypełnij WS_bindingTemplateType_BINDING_TEMPLATE strukturę określoną w podpisie metody. Deweloperzy mogą udostępniać dodatkowe właściwości kanału i/lub właściwości zabezpieczeń zgodnie z potrzebami.
• Wywołaj procedury pomocnika po pomyślnym utworzeniu zwrotnego serwera proxy usługi lub punktu końcowego usługi.

W poniższych sekcjach opisano szczegółowo powiązane tematy.

Obsługa danych wejściowych zasad

Poniżej przedstawiono opcje kompilatora związane z przetwarzaniem zasad.

Domyślnie program wsutil zawsze generuje szablony zasad, chyba że jest wywoływany z opcją "/nopolicy". Zasady można osadzać jako część pliku WSDL lub można utworzyć oddzielnie jako plik metadanych zasad, który wsutil przyjmuje jako dane wejściowe. Opcja kompilatora "/wsp:" służy do wskazania, że określone metadane wejściowe są plikiem zasad. Wsutil generuje potencjalnych pomocników związanych z zasadami przy użyciu następującej kompilacji:

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

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

Żadne pomocniki zasad nie są generowane, gdy opcja "/nopolicy" jest używana jak w poniższym przykładzie.

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

Kod powiązany z zasadami wygenerowany przez kompilator wsutil

mapowanie metadanych na stronie szczegóły mapowania między konstrukcjami metadanych z różnymi typami powiązań.

W ustawieniach zasad można określić trzy kategorie ustawień zasad:

• Właściwości kanału. Obecnie obsługiwane są tylko następujące właściwości kanału: WS_CHANNEL_PROPERTY_ENCODING, WS_CHANNEL_PROPERTY_ADDRESSING_VERSION i WS_CHANNEL_PROPERTY_ENVELOPE_VERSION.
• Właściwości zabezpieczeń. Obecnie obsługiwane są tylko następujące właściwości zabezpieczeń: WS_SECURITY_PROPERTY_TIMESTAMP_USAGE, WS_SECURITY_PROPERTY_SECURITY_HEADER_LAYOUT, WS_SECURITY_PROPERTY_TRANSPORT_PROTECTION_LEVEL i WS_SECURITY_PROPERTY_SECURITY_HEADER_VERSION.
• Powiązanie zabezpieczeń. Obecnie obsługiwane są tylko następujące powiązania zabezpieczeń: 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, , i WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING.

Typ szablonu powiązania

Istnieje ograniczona liczba powiązań obsługiwanych w narzędziu wsutil. Wszystkie te obsługiwane kombinacje tych powiązań są wymienione w definicji WS_BINDING_TEMPLATE_TYPE. Na przykład dla następującego powiązania w pliku wsdl

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

Narzędzie Wsutil generuje WS_HTTP_BINDING_TEMPLATE_TYPE typ szablonu powiązania dla tego powiązania.

Opisy zasad

Po ustawieniu zasad wejściowych narzędzie wsutil generuje zestaw opisów zasad opisujących zasady wejściowe, w tym typ szablonu, a także wartości określone w zasadach. Na przykład dla danych wejściowych

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

Wsutil generuje opis właściwości kanału, na przykład:

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

Wszystkie ustawienia zasad (właściwości kanału, właściwości zabezpieczeń i właściwości powiązania zabezpieczeń) w jednym powiązaniu są agregowane w jedną strukturę WS_bindingTemplateType_POLICY_DESCRIPTION. WS_BINDING_TEMPLATE_TYPE określa różne kombinacje zasad powiązań wsutil obsługuje.

Struktura szablonu do wypełnienia przez aplikację

Opis zasad zawiera wszystkie informacje o zasadach określone w metadanych wejściowych dla danego powiązania, ale istnieją informacje, które nie mogą być reprezentowane w zasadach, ale wymagają danych wejściowych użytkownika podczas korzystania z tych ustawień zasad w celu utworzenia serwera proxy usługi i/lub punktu końcowego usługi. Na przykład aplikacja musi podać poświadczenia na potrzeby uwierzytelniania nagłówka HTTP.

Aplikacja musi wypełnić strukturę szablonu o nazwie WS_bindingTemplateType_BINDING_TEMPLATE dla każdego innego typu szablonu powiązania zdefiniowanego w pliku webservices.h:

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

Lista szablonów powiązań zabezpieczeń jest opcjonalna, zależy od dopasowanego powiązania zabezpieczeń. Na przykład pole WS_SSL_TRANSPORT_SECURITY_BINDING_TEMPLATE jest prezentowane w WS_HTTP_SSL_BINDING_TEMPLATE, aby aplikacja dostarczała powiązane z protokołem SSL informacje o powiązaniu z zabezpieczeniami, w tym informacje o poświadczeniach.

Aplikacja musi wypełnić wszystkie pola w tej strukturze przed wywołaniem interfejsów API szablonów usług internetowych. Dodatkowe właściwości zabezpieczeń, a także właściwości powiązania zabezpieczeń, które nie są godne reprezentowania w zasadach, należy wypełnić, a interfejsy API usług internetowych scalają dwa zestaw właściwości w środowisku uruchomieniowym. Jeśli nie ma zastosowania, pola mogą być wyzerowane. Na przykład właściwości securityProperties mogą być zerowe, jeśli nie są potrzebne żadne dodatkowe właściwości zabezpieczeń.

Procedury pomocnika i deklaracja opisu zasad w plikach nagłówków

narzędzie wsutil tworzy procedurę pomocnika, aby ułatwić lepszą obsługę warstwy modelu usług, dzięki czemu aplikacja może łatwiej tworzyć serwer proxy usługi i punkt końcowy usługi. Opis zasad jest również uwidoczniony, tak aby aplikacja mogła ich używać bezpośrednio. Procedury pomocy CreateSerivceProxy wyglądają następująco:

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

Deweloperzy są zachęcani do korzystania z tych procedur pomocników, choć mogą również bezpośrednio korzystać z procedury środowiska uruchomieniowego poniżej zapewnianych przez webservices.dll. Deweloperzy nie są zachęcani do bezpośredniego używania opisów zasad podczas programowania przy użyciu modelu usługi warstwy.

Odwołania do opisu zasad są również generowane w nagłówku dla zaawansowanego użytkownika. Jeśli deweloperzy nie korzystają z funkcji modelu usług, mogą bezpośrednio używać opisów zasad.

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

Prototypy definicji w plikach wycinków

Jedno pole struktury opisu zasad na powiązanie i jego wewnętrznie przywoływały opisy pomocnika są tworzone w lokalnej strukturze prototypu. Opisy zasad są generowane w pliku, w którym jest generowany WS_CONTRACT_DESCRIPTION. Ogólnie rzecz biorąc, deweloperzy nie muszą sprawdzać pliku wycinkowego podczas programowania, chociaż plik wycinkowy zawiera wszystkie szczegóły dotyczące specyfikacji zasad.

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

Implementacja procedur pomocnika w plikach wycinków

Wsutil generuje procedury pomocnicze, aby uprościć wywołania aplikacji do WsCreateServiceProxy i tworząc WS_SERVICE_ENDPOINT oparte na informacjach podanych w ustawieniach zasad.

Zależy od ograniczeń powiązań określonych dla danego portu, pierwszy argument różni się w zależności od struktury szablonu. W poniższym przykładzie przyjęto założenie, że transport HTTP, podpis tworzenia serwera proxy usługi jest podobny z jednym dodatkowym parametrem typu kanału.

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

Obsługiwane ustawienia zasad

W poniższej tabeli wymieniono wszystkie obsługiwane typy szablonów powiązań, pasujące powiązania zabezpieczeń wymagane w typie, strukturę szablonu, która ma zostać wypełniona przez aplikację dla typu i pasujący typ opisu. Aplikacja musi wypełnić strukturę szablonu, podczas gdy deweloper aplikacji powinien zrozumieć, jakie powiązania zabezpieczeń są wymagane w danych zasadach.

Na przykład WS_HTTP_SSL_BINDING_TEMPLATE_TYPE wskazuje zasady wejściowe powiązania określają transport HTTP i WS_SSL_TRANSPORT_SECURITY_BINDING. Aplikacja musi wypełnić strukturę WS_HTTP_SSL_BINDING_TEMPLATE przed wywołaniem procedur pomocnika, a zgodny opis zasad jest WS_HTTP_SSL_POLICY_DESCRIPTION. W szczególności sekcja powiązania w języku WSDL zawiera następujące segmenty:

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

Obsługa kontekstu zabezpieczeń

W kontekst zabezpieczeńkanał bootstrap jest tworzony w celu ustanowienia bezpiecznej konwersacji w kanale usługi. Wsutil obsługuje tylko scenariusz, w którym kanał bootstrap jest taki sam jak kanał usługi, z tymi samymi właściwościami kanału i właściwościami zabezpieczeń. Zabezpieczenia transportu są wymagane do powiązania komunikatów kontekstowych zabezpieczeń; Program wsutil obsługuje kanały bootstrap z innymi powiązaniami zabezpieczeń komunikatów, ale obsługują tylko kontekst zabezpieczeń jako jedyne powiązanie zabezpieczeń komunikatów w kanale usługi bez kombinacji z innymi powiązaniami zabezpieczeń komunikatów. Deweloperzy mogą obsługiwać te kombinacje poza obsługą szablonów zasad.

Następujące wyliczenie jest częścią obsługi zasad:

• WS_BINDING_TEMPLATE_TYPE

Następujące funkcje są częścią obsługi zasad:

• WsCreateServiceEndpointFromTemplate
• WsCreateServiceProxyFromTemplate

Następujące struktury są częścią obsługi zasad:

• 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