Создание прокси-класса XML-веб-службы

Этот раздел посвящен технологии прежних версий. Веб-службы XML и клиенты веб-служб XML должны создаваться с использованием Windows Communication Foundation.

По умолчанию взаимодействие с веб-службами по сети возможно с использованием стандартных отраслевых протоколов, включая протокол SOAP. А именно, клиент и веб-служба обмениваются данными с помощью сообщений SOAP, в которых входные и выходные параметры инкапсулированы в виде XML. К счастью, в случае клиентов веб-служб сопоставление параметров с элементами XML и последующая передача сообщений SOAP по сети выполняются прокси-классом.

При наличии описания службы создание прокси-класса возможно, если описание службы удовлетворяет требованиям языка описания веб-служб (WSDL). Описание службы определяет способ взаимодействия с веб-службой. При наличии описания службы прокси-класс можно создать с помощью инструмента Wsdl.exe. В свою очередь, клиент веб-службы может вызывать методы прокси-класса, который обменивается данными с веб-службой по сети, обрабатывая сообщения SOAP, передаваемые службе и получаемые от нее. Так как прокси-класс обменивается данными с веб-службой по Интернету, рекомендуется проверить, что свойство Url прокси-класса ссылается на доверенное назначение.

По умолчанию для взаимодействия с веб-службой в прокси-классе используется протокол SOAP через HTTP. Однако инструмент Wsdl.exe может создавать прокси-классы для взаимодействия с веб-службой с использованием протокола HTTP-GET или HTTP-POST. Чтобы указать, что прокси-класс должен использовать HTTP-GET или HTTP-POST, укажите для программы Wsdl.exe переключатель /protocol, как описано в следующей таблице.

Использование инструмента Wsdl.exe для создания прокси-класса XML-веб-службы

Для создания прокси-класса можно использовать инструмент языка описания веб-служб (Wsdl.exe) из командной строки, указав (как минимум) URL веб-службы или описания службы либо путь к сохраненному описанию службы.

Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

Примечание
Далее перечислены часто используемые аргументы Wsdl.exe. Полный синтаксис программы Wsdl.exe см. в разделе Инструмент языка описания веб-служб (Wsdl.exe).

Параметр	Значение
<URL-адрес или путь>	URL-адрес или путь к описанию службы (файлу, описывающему веб-службу на языке WSDL). Если задан файл, предоставьте файл, содержащий описание службы. Пример. mywebservice.wsdl Если задан URL-адрес, этот URL должен ссылаться на страницу .asmx или возвращать описание службы. Для веб-служб, созданных с помощью ASP.NET, описание службы можно получить, добавив текст "?WSDL" к URL-адресу веб-службы. Например, https://www.contoso.com/MyWebService.asmx?WSDL.
/language:язык	Язык, на котором создается прокси-класс. Предусмотрены значения CS, VB и JS, что соответствует языкам C#, Visual Basic .NET и JScript .NET. По умолчанию используется язык C#. (Необязательный параметр)
/protocol:протокол	Протокол, используемый для взаимодействия с методами веб-службы. Предусмотрены значения SOAP, HTTP-GET и HTTP-POST. По умолчанию используется протокол SOAP. (Необязательный параметр).
/namespace:пространство_имен	Пространство имен создаваемого прокси-класса. Значение по умолчанию — глобальное пространство имен. (Необязательный параметр)
/out:имя_файла	Имя создаваемого файла, содержащего прокси-класс. Имя по умолчанию основано на имени класса, реализующего веб-службу. (Необязательный параметр)
/username:имя_пользователя	Имя пользователя, используемое для соединения с веб-сервером, требующему проверку подлинности. (Необязательный параметр).
/password:пароль	Пароль, используемый для подключению к веб-серверу, требующему проверку подлинности. (Необязательный параметр).
/domain:домен	Домен, используемый для подключению к веб-серверу, требующему проверку подлинности. (Необязательный параметр).

Сведения о созданном прокси-классе

Если для создания прокси-класса используется инструмент Wsdl.exe, создается один файл исходного кода на заданном языке. Этот файл содержит прокси-класс, предоставляющий доступ к синхронным и асинхронным методам для каждого метода веб-службы. Например, если веб-служба содержит метод с именем Add, то прокси-класс содержит следующие методы для вызова метода Add веб-службы: Add, BeginAdd** и EndAdd. Метод Add прокси-класса используется для синхронной связи с методом Add веб-службы, а методы BeginAdd и EndAdd используются для асинхронной связи с методом веб-службы. Дополнительные сведения об асинхронной связи с методами веб-службы см. в разделе Асинхронное взаимодействие с XML-веб-службами.

Каждый метод созданного прокси-класса содержит соответствующий код для взаимодействия с методом веб-службы. Если во время обмена данными между веб-службой и прокси-классом происходит ошибка, то вызывается исключение. Дополнительные сведения об обработке исключений см. в разделе Обработка и создание исключений в XML-веб-службах.

Порядок параметров, заданный в методе веб-службы и в соответствующем методе прокси-класса, может отличаться. В большинстве случаев порядок параметров совпадает. Однако, если веб-служба ожидает сообщения SOAP в формате Document, существует вариант, когда порядок параметров не совпадает. Если в методе веб-службы выходные параметры заданы до входного параметра, в прокси-классе выходные параметры помещаются после входных параметров. Например, в следующем примере кода для метода веб-службы MyWebMethod выходной параметр outStr объявлен до входного параметра inStr. Однако в прокси-классе параметр inStr объявляется до параметра outStr.

' Declare MyWebMethod in the Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)

// Declare MyWebMethod in the Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

В некоторых случаях прокси-класс, созданный программой Wsdl.exe, использует метод наименьшего общего знаменателя для приведения объектов к типу, указанному в описании службы. В результате созданный тип в прокси-классе может отличаться от требуемого или ожидаемого разработчиком. Например, когда программа Wsdl.exe обнаруживает в описании службы тип ArrayList, в создаваемом прокси-классе создается массив Object. Чтобы обеспечить правильное приведение типов объектов, откройте файл, содержащий созданный прокси-класс, и измените все неверные типы объектов на ожидаемые типы.

Предупреждения, создаваемые инструментом Wsdl.exe

Если инструменту Wsdl.exe переданы несколько описаний служб, могут выводиться следующие два сообщения об ошибках.

• Внимание! Повторяющееся описание службы с TargetNamespace=<пространство_имен_схемы> из <URI_схемы> пропущено.

  Указывает, что для нескольких указанных описаний служб совпадают параметры TargetNamespace. Так как предполагается, что параметр TargetNamespace должен быть уникальным идентификатором для определенного XML-документа, который в данном случае является описанием службы, программа Wsdl.exe считает, что эти два описания служб совпадают. Соответственно, инструмент Wsdl.exe создает только один прокси-класс для одного из описаний службы. Если ожидалось выполнение других действий, это можно изменить. Для описаний, представляющих веб-службы, созданные с помощью ASP.NET, можно применить атрибут WebService, указывающий уникальное свойство Namespace для класса, в котором реализована веб-служба. Затем это свойство Namespace используется в качестве TargetNamespace в описании службы, чтобы уникальным образом определить веб-службу.

• Внимание! Повторяющаяся схема с TargetNamespace=<пространство_имен_схемы> из <URI_схемы> пропущена.

  Указывает, что для нескольких схем XML в указанных описаниях служб совпадают параметры TargetNamespace. Так как предполагается, что параметр TargetNamespace должен быть уникальным идентификатором для определенного XML-документа, который в данном случае является схемой XML, программа Wsdl.exe считает, что эти две схемы XML совпадают. Соответственно, инструмент Wsdl.exe создает класс только для одной из схем. Если предполагался другой результат, параметр TargetNamespace для каждой схемы XML необходимо изменить на уникальный URI. Точный способ изменения параметра TargetNamespace зависит от источника конкретных схем XML.

См. также

Задачи

Как изучить существующие XML-веб-служб, созданные с помощью ASP.NET
Как получить доступ к XML-веб-службам из обозревателя

Основные понятия

Создание клиентов XML-веб-службы
Обнаружение веб-служб
Асинхронное взаимодействие с XML-веб-службами

Другие ресурсы

Создание клиентов для XML-веб-служб