Поддержка форматов SOAP в платформе .NET Framework

Статья
02/28/2011

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

Вместо того чтобы создавать WSDL-документ вручную, разработчик, создающий веб-службу для ASP.NET, может задать эти форматы SOAP путем применения атрибутов к отдельным методам или к целым классам веб-службы. Если разработчик не задал эти атрибуты, используются форматы SOAP по умолчанию.

При разработке веб-службы на основе существующего WSDL-документа можно запустить программу Wsdl.exe с параметром /server, чтобы создать абстрактный класс веб-службы с автоматически установленными подходящими значениями атрибутов.

Без параметра /server программа Wsdl.exe создает клиентский прокси-класс, который задает для соответствующих атрибутов форматирования SOAP значения, необходимые для обмена данными с веб-службой, описываемой входным WSDL-документом. Клиентский прокси-класс использует большинство тех же атрибутов, которые могут быть заданы на сервере. Обычно разработчику не требуется вручную добавлять или редактировать эти атрибуты в клиентском прокси-классе, так как обычно клиент создается инструментом Wsdl.exe, что обеспечивает его соответствие контракту службы, заданному документом WSDL.

В следующей таблице приведены варианты форматирования, поддерживаемые веб-службами и клиентами, созданными с помощью ASP.NET и платформы .NET Framework, а также атрибуты, реализующие каждое конкретное сочетание. Атрибуты с суффиксом Service могут применяться к классу, реализующему веб-службу (а не клиентскому прокси-классу), чтобы задать стиль форматирования по умолчанию для методов веб-службы, входящих в этот класс. Атрибуты с суффиксом Method могут применяться к методу веб-службы или к методу клиентского прокси-класса, вызывающему метод веб-службы. Подробные сведения о каждом сочетании приведены в последующих абзацах.

Форматирование параметров (use)	Форматирование (style) основного текста сообщения SOAP для сообщений SOAP, основанных на документах	Форматирование (style) основного текста сообщения SOAP для сообщений SOAP, основанных на RPC, в соответствии с протоколом SOAP 1.1, раздел 7s
Literal — на основе схемы XSD для каждого параметра	SoapDocumentMethod или SoapDocumentService Use=Literal Это значение по умолчанию.	SoapRpcMethod или SoapRpcService Use=Literal
Encoded — правила кодирования протокола SOAP 1.1, раздел 5	SoapDocumentMethod или SoapDocumentService Use=Encoded	SoapRpcMethod или SoapRpcService Use=Encoded Это значение по умолчанию.

Форматирование параметров (use)

Форматирование (style) основного текста сообщения SOAP для сообщений SOAP, основанных на документах

Форматирование (style) основного текста сообщения SOAP для сообщений SOAP, основанных на RPC, в соответствии с протоколом SOAP 1.1, раздел 7s

Literal — на основе схемы XSD для каждого параметра

SoapDocumentMethod или SoapDocumentService

Use=Literal

Это значение по умолчанию.

SoapRpcMethod или SoapRpcService

Use=Literal

Encoded — правила кодирования протокола SOAP 1.1, раздел 5

SoapDocumentMethod или SoapDocumentService

Use=Encoded

SoapRpcMethod или SoapRpcService

Use=Encoded

Это значение по умолчанию.

Примечание
В фактических именах атрибутов используется суффикс Attribute. В исходном коде допускается сокращение имен, как показано в предыдущей таблице.

Управление общим форматированием основного текста сообщений SOAP

Для свойства "style", которое определяет, применяет ли обработчик среды выполнения веб-службы соглашения RPC или следует документам XML, по умолчанию в веб-службе ASP.NET выбран документ, а не RPC.

Стиль документа можно указать явно, применив атрибут SoapDocumentMethodAttribute к методу веб-службы или методу клиентского класса-посредника либо применив атрибут SoapDocumentServiceAttribute к классу веб-службы. Стиль RPC можно указать явно, применив атрибут SoapRpcMethodAttribute к методу веб-службы или методу клиентского класса-посредника либо применив атрибут SoapRpcServiceAttribute к классу веб-службы. В случае службы атрибут на уровне метода переопределяет атрибут на уровне класса.

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

Дополнительные сведения о применении этих атрибутов см. в разделе Как управлять общим форматированием текста сообщений SOAP для метода веб-службы.

Управление форматированием параметров и возвращаемых значений

Для свойства use, которое определяет форматирование параметров или возвращаемого значения метода веб-службы, в веб-службе ASP.NET для стиля документа по умолчанию используется значение literal. В веб-службе ASP.NET для стиля документа по умолчанию используется значение encoded. Значение свойства use можно изменить, установив свойство Use в соответствующих атрибутах SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute или SoapRpcServiceAttribute в значение SoapBindingUse.Literal или SoapBindingUse.Encoded.

Дополнительные сведения об установке свойства Use см. в разделе Как управлять форматированием параметров и возвращаемых значений для метода веб-службы.

Управление тем, должны ли параметры заключаться в дополнительный элемент XML

Параметры или возвращаемое значение метода веб-службы могут автоматически заключаться в родительский XML-элемент внутри элемента Body сообщения SOAP. Разработчику не требуется задавать родительский элемент. Как было показано выше, это выполняется стилем форматирования RPC. Однако такая возможность предусмотрена и для стиля форматирования документа. Вместо родительского XML-элемента или оболочки, задаваемой в WSDL-документе, дополнительный элемент неявно вставляется инфраструктурой веб-служб во время выполнения.

Это правило называется заключением в оболочку. Чтобы включить его, установите свойство SoapDocumentMethod.ParameterStyle или SoapDocumentService.ParameterStyle в значение SoapParameterStyle.Wrapped. Wrapped также используется по умолчанию.

Перечисление SoapParameterStyle также имеет значение Default для задания стиля параметров по умолчанию на уровне класса службы, плюс значение Bare для отключения заключения в оболочку и буквального преобразования XML-элементов, указанных в WSDL в качестве частей сообщения, в параметры и возвращаемые значения методов. В стиле параметров Bare каждый параметр или возвращаемое значение соответствует указанной части сообщения.

В WSDL-документе не указывается, следует ли использовать заключение в оболочку. Для значений Wrapped и Bare используется стиль привязки document. Скорее выбор связан с привязкой между XML и кодом — между XML, заданным в WSDL, и параметрами и возвращаемыми значениями методов.

Если для свойства ParameterStyle задано значение SoapParameterStyle.Bare, разработчик может задать сообщение с несколькими частями — а именно, несколько XML-элементов, являющихся дочерними для элемента SOAP Body. Технически несколько элементов не образуют документ XML, так как документ должен иметь один корень. Поэтому в сообществе веб-служб рекомендуется использовать со службами стиля документа сообщения с одной частью. Каждый метод веб-службы должен использовать не свою предполагаемую сигнатуру, а сигнатура, в которой сопоставление объектов документу XML является одним параметром, а другое сопоставление объектов документу XML является возвращаемым значением. Разработчику необходимо написать код для извлечения или упаковки фактических параметров или возвращаемых значений.

Поэтому обычно разработчику достаточно задать для свойства ParameterStyle значение SoapParameterStyle.Wrapped и возложить размещение параметров и возвращаемых значений в XML-документах на инфраструктуру веб-служб.

Дополнительные сведения об установке свойства ParameterStyle см. в разделе Как управлять вложением параметров метода веб-службы в дополнительный элемент.

Задание форматирования SOAP по умолчанию для всей веб-службы

Как отмечалось ранее в этом разделе, атрибуты SoapDocumentServiceAttribute и SoapRpcServiceAttribute могут использоваться для задания значений по умолчанию стиля, использования и стиля сопоставления параметр-документ для всего класса веб-службы, но не для клиентского прокси-класса. Атрибуты SoapDocumentMethod и SoapRpcMethod можно использовать, чтобы переопределить параметры на уровне службы для каждого метода веб-службы.

Дополнительные сведения об использовании атрибутов SoapDocumentService и SoapRpcService см. в разделе Как изменить форматирование сообщений SOAP по умолчанию для всей веб-службы..

Настройка сообщений SOAP с помощью XML-сериализации

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

В пространство имен System.Xml.Serialization входят многочисленные атрибуты для работы с XML-кодом. В следующем примере кода показано, как некоторые из этих атрибутов могут применяться непосредственно к параметрам или возвращаемым значениям метода веб-службы.

[SoapDocumentMethod(
     "https://www.contoso.com/DocumentBareLiteral",
     Use=SoapBindingUse.Literal,
     ParameterStyle=SoapParameterStyle.Bare)]
[return: XmlElement(Namespace="https://www.contoso.com",
                    IsNullable=true)]
public string DocumentBareLiteral(
   [XmlElement(Namespace="https://www.contoso.com",
                     IsNullable=true)] 
   Address1 MyAddress, 
   [XmlElement(Namespace="https://www.contoso.com",
            IsNullable=false)] 
   bool useZipPlus4) {

<SoapDocumentMethod( _
     https://www.contoso.com/DocumentBareLiteral", _
     Use:=SoapBindingUse.Literal, _
     ParameterStyle:= SoapParameterStyle.Bare)> _
Public Function DocumentBareLiteral( _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=true)> _
   MyAddress As Address1, _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=false)> _
   useZipPlus4 As Boolean) _
   As <XmlElement([Namespace]:="https://www.contoso.com", _
                  IsNullable:=true)> _
   String

Далее перечислены некоторые часто используемые атрибуты, при этом их имена приведены без суффикса Attribute, который может опускаться.

XmlElement задает, что открытое поле или свойство сериализуется как XML-элемент. Это атрибут по умолчанию для сериализации открытых полей и свойств, не являющихся массивами. Если атрибут XmlElement применяется к открытым полям и свойствам атрибута типа массива, то массив сериализуется с другими членами без специального родительского элемента.
XmlAttribute задает, что открытое поле или свойство сериализуется как атрибут XML-элемента, представляющего содержащий тип.
XmlArray задает, что открытое поле типа массива сериализуется со специальным родительским элементом. Это атрибут по умолчанию для сериализации открытых полей и свойств с типом массива.
XmlArrayItem используется в сочетании с атрибутом XmlArray для управления элементами массива.
XmlIgnore задает, что открытое поле или свойство не сериализуется.

Указанные выше атрибуты, за исключением атрибута XmlIgnore, также используются для задания имени элемента или атрибута, помимо значения по умолчанию, которое является именем для членов, не являющихся массивами. Они также могут использоваться, чтобы задать пространство имен для определенного элемента. Обычно в веб-службе не используется одновременно несколько пространств имен, и пространство имен обязательно указывать только на уровне класса с помощью атрибута WebService или WebServiceBinding.

Дополнительные сведения см. в разделе см. в разделе System.Xml.Serialization.

Примечание
Для веб-служб, использующих RPC или кодирование со стилем RPC и кодированием SOAP, существуют ограничения на использование XML-сериализации. Параметры и возвращаемые значения автоматически отображаются без квалификации пространства имен. Кроме того, кодирование SOAP 1.1, раздел 5, в сочетании со стилем документа или стилем RPC, исключает привязку данных к атрибутам XML.

Для веб-служб, использующих RPC или кодирование со стилем RPC и кодированием SOAP, существуют ограничения на использование XML-сериализации. Параметры и возвращаемые значения автоматически отображаются без квалификации пространства имен. Кроме того, кодирование SOAP 1.1, раздел 5, в сочетании со стилем документа или стилем RPC, исключает привязку данных к атрибутам XML.

Примечание
Если абстрактный класс службы или клиентский прокси-класс создается из WSDL-документа, то правильные атрибуты System.Xml.Serialization автоматически применяются к элементам схемы XML и типам, определенным в элементе WSDL types, независимо от того, встроены они в текст или импортированы.

Если абстрактный класс службы или клиентский прокси-класс создается из WSDL-документа, то правильные атрибуты System.Xml.Serialization автоматически применяются к элементам схемы XML и типам, определенным в элементе WSDL types, независимо от того, встроены они в текст или импортированы.

Примечание
При использовании в веб-службе типа, допускающего значение NULL, WSDL-документ будет содержать для этого типа параметр «nillable=true». Однако, если типы, допускающие значение NULL, используются непосредственно как параметры или возвращаемые значения веб-метода, возможность присвоения значения NULL не отражается на конечном WSDL-документе в следующих случаях: 1) если используются сообщения SOAP, основанные на RPC, и 2) если сообщения SOAP, основанные на документе, используются с кодированными параметрами в режиме Bare.

При использовании в веб-службе типа, допускающего значение NULL, WSDL-документ будет содержать для этого типа параметр «nillable=true». Однако, если типы, допускающие значение NULL, используются непосредственно как параметры или возвращаемые значения веб-метода, возможность присвоения значения NULL не отражается на конечном WSDL-документе в следующих случаях: 1) если используются сообщения SOAP, основанные на RPC, и 2) если сообщения SOAP, основанные на документе, используются с кодированными параметрами в режиме Bare.

Дополнительные сведения об использовании атрибута XmlElement см. в разделе Как настроить сообщения SOAP с XML-сериализацией.

См. также

Поделиться через

Поддержка форматов SOAP в платформе .NET Framework

Управление общим форматированием основного текста сообщений SOAP

Управление форматированием параметров и возвращаемых значений

Управление тем, должны ли параметры заключаться в дополнительный элемент XML

Задание форматирования SOAP по умолчанию для всей веб-службы

Настройка сообщений SOAP с помощью XML-сериализации

См. также

Задачи

Справочник

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

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

Дополнительные ресурсы