SOAP 형식에 대한 .NET Framework 지원

아티클
03/02/2011

이 항목은 레거시 기술과 관련된 것입니다. 이제 XML Web services와 XML Web services 클라이언트는 다음을 사용하여 만들어야 합니다. Windows Communication Foundation.

ASP.NET용 웹 서비스 개발자는 WSDL 문서를 직접 작성하는 대신 개별 웹 서비스 메서드나 전체 웹 서비스 클래스에 특성을 적용하여 SOAP 형식을 지정할 수 있습니다. 개발자가 이러한 특성을 지정하지 않으면 기본 SOAP 형식이 사용됩니다.

기존 WSDL 문서를 기반으로 웹 서비스를 개발하는 경우 /server 옵션을 사용하여 Wsdl.exe 도구를 실행하면 적절한 특성 값이 자동으로 설정된 추상 웹 서비스 클래스를 생성할 수 있습니다.

/server 옵션을 사용하지 않고 Wsdl.exe를 실행하면 입력 WSDL 문서에 설명된 웹 서비스와 통신하는 데 적합한 값으로 관련 SOAP 형식 특성을 설정하는 클라이언트 프록시 클래스가 생성됩니다. 클라이언트 프록시 클래스는 서버에 지정할 수 있는 대부분의 특성을 사용합니다. 일반적으로 Wsdl.exe는 WSDL 문서에 지정된 서비스 계약에 부합하는 클라이언트를 생성하므로 개발자가 클라이언트 프록시 클래스에서 이러한 특성을 수동으로 추가하거나 편집할 필요가 없습니다.

다음 표에서는 ASP.NET 및 .NET Framework를 사용하여 만든 클라이언트와 웹 서비스에서 지원하는 형식 옵션과 함께 각각의 특정 조합을 구성하는 특성에 대해 간략하게 설명합니다. Service 접미사가 붙은 특성은 클라이언트 프록시 클래스가 아닌 웹 서비스를 구현하는 클래스에 적용하여 클래스 내의 웹 서비스 메서드에 대한 기본 형식 스타일을 설정할 수 있습니다. Method 접미사가 붙은 특성은 웹 서비스 메서드를 호출하는 클라이언트 프록시 클래스 내의 메서드나 웹 서비스 메서드에 적용할 수 있습니다. 각 조합에 대한 자세한 내용은 다음 단락에서 다룹니다.

매개 변수 형식(용도)	문서 기반 SOAP 메시지에 대한 SOAP 본문 형식(스타일)	SOAP 1.1 사양의 7항에 따른 RPC 기반 SOAP 메시지에 대한 SOAP 본문 형식(스타일)
Literal - 각 매개 변수에 대한 XSD 스키마 기반	SoapDocumentMethod 또는 SoapDocumentService Use=Literal 기본값입니다.	SoapRpcMethod 또는 SoapRpcService Use=Literal
Encoded - SOAP 1.1 사양의 5항 인코딩 규칙	SoapDocumentMethod 또는 SoapDocumentService Use=Encoded	SoapRpcMethod 또는 SoapRpcService Use=Encoded 기본값입니다.

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 본문 형식 제어

웹 서비스 런타임 엔진이 RPC 규칙을 적용하는지 아니면 XML 문서를 따르는지를 제어하는 스타일의 경우, ASP.NET 웹 서비스의 기본 옵션은 RPC가 아니라 문서입니다.

웹 서비스 메서드 또는 클라이언트 프록시 메서드에 SoapDocumentMethodAttribute 특성을 적용하거나, 웹 서비스 클래스에 SoapDocumentServiceAttribute 특성을 적용하여 문서 스타일을 명시적으로 지정할 수 있습니다. 또한 웹 서비스 메서드 또는 클라이언트 프록시 메서드에 SoapRpcMethodAttribute 특성을 적용하거나, 웹 서비스 클래스에 SoapRpcServiceAttribute 특성을 적용하여 RPC 스타일을 명시적으로 지정할 수 있습니다. 서비스의 경우 메서드 수준 특성이 클래스 수준 특성을 재정의합니다.

이 항목의 뒷부분에서 설명하는 것처럼 이러한 특성은 매개 변수와 반환 값 형식을 결정하는 데 사용됩니다. 또한 "래퍼" 요소가 런타임에 자동으로 생성되어 매개 변수나 반환 값을 포함하는지 여부를 결정하는 역할도 합니다. 자세한 내용은 다음 항목을 참조하십시오. 방법: 웹 서비스 메서드 매개 변수가 추가 요소에 인코딩되는지 여부 제어를 참조하십시오.

이러한 특성을 적용하는 방법에 대한 자세한 내용은 방법: 웹 서비스 메서드에 대한 전체적인 SOAP 본문 형식 제어를 참조하십시오.

매개 변수 및 반환 값 형식 제어

웹 서비스 메서드 매개 변수 또는 반환 값의 형식을 제어하는 use의 경우 문서 스타일 ASP.NET 웹 서비스의 기본 설정은 literal입니다. RPC 스타일 ASP.NET 웹 서비스의 기본 설정은 encoded입니다. 해당하는 SoapDocumentMethodAttribute, SoapDocumentServiceAttribute, SoapRpcMethodAttribute 또는 SoapRpcServiceAttribute 특성의 Use 속성을 SoapBindingUse.Literal 또는 SoapBindingUse.Encoded로 설정하여 use 값을 변경할 수 있습니다.

Use 속성을 설정하는 방법에 대한 자세한 내용은 방법: 웹 서비스 메서드에 대한 매개 변수 및 반환 값 형식 제어를 참조하십시오.

추가 XML 요소로 매개 변수를 묶을지 여부 제어

웹 서비스 메서드의 매개 변수 또는 반환 값은 SOAP 메시지의 Body 요소 내의 부모 XML 요소에 자동으로 캡슐화될 수 있습니다. 따라서 개발자가 부모 요소를 지정할 필요가 없습니다. 앞에서 설명한 것처럼 RPC 형식 스타일에서 부모 요소를 지정합니다. 그러나 이 옵션 역시 문서 형식 스타일을 사용하는 옵션입니다. WSDL 문서에서 부모 XML 요소나 래퍼를 지정하는 대신 런타임에 웹 서비스 인프라에서 추가 요소를 암시적으로 삽입합니다.

이 규칙을 래핑이라고 하며 SoapDocumentMethod.ParameterStyle 또는 SoapDocumentService.ParameterStyle 속성을 SoapParameterStyle.Wrapped 값으로 설정하여 지정할 수 있습니다. Wrapped가 기본값입니다.

SoapParameterStyle 열거형의 값에는 Default와 Bare가 있습니다. Default는 서비스 클래스 수준에서 기본 매개 변수 스타일을 지정하고, Bare는 래핑을 사용하지 않고 WSDL에서 메시지 부분으로 지정된 XML 요소를 문자 그대로 메서드 매개 변수 및 반환 값으로 변환합니다. Bare 매개 변수 스타일을 사용할 경우 각 매개 변수 또는 반환 값은 지정된 메시지 부분에 대응됩니다.

래핑 여부 설정은 WSDL 문서에서 지정되지 않으며, Wrapped와 Bare 모두 바인딩 스타일로 문서를 사용합니다. 이 설정은 XML과 코드 간, 즉 WSDL에 정의된 XML과 메서드의 매개 변수 및 반환 값 간의 바인딩에 적용됩니다.

ParameterStyle 속성을 SoapParameterStyle.Bare로 설정하면 개발자가 여러 부분(SOAP Body 요소의 자식으로, 문자 그대로 표시되는 여러 XML 요소)으로 구성된 메시지를 지정할 수 있습니다. 기술적으로는 문서마다 루트가 하나만 있어야 하므로 여러 요소로 XML 문서를 구성할 수 없습니다. 따라서 웹 서비스 커뮤니티에서는 가장 좋은 방법으로 문서 스타일 서비스와 함께 단일 문서 부분을 사용할 것을 권장합니다. 각 웹 서비스 메서드가 의도된 서명을 반드시 사용해야 할 필요는 없지만, XML 문서에 매핑되는 한 개체가 하나의 매개 변수이고 XML 문서에 매핑되는 또 다른 개체가 반환 값인 서명을 사용해야 합니다. 개발자는 실제 매개 변수 또는 반환 값을 추출하거나 패키징하는 코드를 작성해야 합니다.

일반적으로 개발자가 ParameterStyle 속성을 SoapParameterStyle.Wrapped로 설정하면 웹 서비스 인프라에서 매개 변수와 반환 값을 XML 문서에 입력합니다.

ParameterStyle 속성을 설정하는 방법에 대한 자세한 내용은 방법: 웹 서비스 메서드 매개 변수가 추가 요소에 인코딩되는지 여부 제어를 참조하십시오.

전체 웹 서비스에 대한 기본 SOAP 형식 설정

이 항목의 앞부분에서 설명했듯이 SoapDocumentServiceAttribute 및 SoapRpcServiceAttribute 특성을 사용하면 클라이언트 프록시 클래스가 아니라 전체 웹 서비스 클래스의 스타일, 용도, 매개 변수와 문서 간 매핑 스타일에 대한 기본값을 설정할 수 있습니다. SoapDocumentMethod 및 SoapRpcMethod 특성을 사용하면 웹 서비스 메서드별로 서비스 수준 설정을 재정의할 수 있습니다.

SoapDocumentService 및 SoapRpcService 특성을 사용하는 방법에 대한 자세한 내용은 방법: 전체 웹 서비스에 대한 기본 SOAP 형식 수정을 참조하십시오.

XML Serialization을 사용하여 SOAP 메시지 사용자 지정

스타일 지정, 용도, 래퍼 요소 삽입 여부 등의 지정 외에도, XML Serialization을 사용하여 SOAP 메시지에서 XML을 직접 사용자 지정할 수 있습니다. 기본적으로 .NET Framework의 웹 서비스 인프라는 public 필드와 속성을 XML 메시지에 자동으로 serialize합니다.

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: public 필드나 속성을 XML 요소로 serialize하도록 지정합니다. 이 특성은 배열 형식이 아닌 public 필드와 속성을 serialize하는 기본 특성입니다. XmlElement 특성을 배열 형식 특성의 public 필드 및 속성에 적용할 경우 배열은 다른 멤버와 함께 특수 부모 요소 없이 serialize됩니다.
XmlAttribute: 포함하는 형식을 나타내는 요소의 XML 특성으로 public 필드나 속성을 serialize하도록 지정합니다.
XmlArray: 배열 형식의 public 필드를 특수 부모 요소와 함께 serialize하도록 지정합니다. 이는 배열 형식의 public 필드와 속성을 serialize하는 기본 특성입니다.
XmlArrayItem: 배열 요소를 제어하기 위해 XmlArray 특성과 함께 사용됩니다.
XmlIgnore: public 필드나 속성을 serialize하지 않도록 지정합니다.

XmlIgnore를 제외한 위의 특성은 배열 형식이 아닌 멤버의 이름인 요소 또는 특성 이름을 기본 이름 외의 다른 이름으로 지정하는 데 사용할 수 있습니다. 또한 특정 요소의 네임스페이스를 지정하는 데에도 사용할 수 있습니다. 일반적으로 웹 서비스는 네임스페이스를 조합하여 사용하지 않습니다. 네임스페이스는 WebService 또는 WebServiceBinding과 같은 특성을 사용하여 클래스 수준별로 하나씩만 지정해야 합니다.

자세한 내용은 다음 항목을 참조하십시오. System.Xml.Serialization을 참조하십시오.

참고:
RPC 또는 인코딩된 웹 서비스의 경우 SOAP 인코딩과 함께 RPC 스타일을 사용하면 XML serialization의 사용이 제한됩니다. 매개 변수와 반환 값은 네임스페이스 한정자 없이 자동으로 표시됩니다. 또한 SOAP 1.1 5절 인코딩을 문서 또는 RPC 스타일과 함께 사용하면 데이터를 XML 특성으로 바인딩할 수 없습니다.

참고:
추상 서비스 클래스나 클라이언트 프록시 클래스가 WSDL 문서에서 생성되는 경우, 올바른 System.Xml.Serialization 특성이 인라인으로 표시되든 가져오든 관계없이 WSDL types 요소에 정의된 XML 스키마 요소와 형식에 자동으로 적용됩니다.

참고:
웹 서비스에서 Nullable 형식을 사용하면 형식에 대해 "nillable=true" 설정을 포함하는 WSDL이 생성됩니다. 그러나 Nullable 형식을 웹 메서드 매개 변수 또는 반환 값으로 직접 사용하면 null 허용 여부가 결과 WSDL에 반영되지 않는 경우가 있습니다. 그러한 경우는 1) RPC 기반 SOAP 메시지를 사용하는 경우와 2) 문서 기반 SOAP 메시지를 Bare 모드에서 인코딩된 매개 변수와 함께 사용하는 경우입니다.

웹 서비스에서 Nullable 형식을 사용하면 형식에 대해 "nillable=true" 설정을 포함하는 WSDL이 생성됩니다. 그러나 Nullable 형식을 웹 메서드 매개 변수 또는 반환 값으로 직접 사용하면 null 허용 여부가 결과 WSDL에 반영되지 않는 경우가 있습니다. 그러한 경우는 1) RPC 기반 SOAP 메시지를 사용하는 경우와 2) 문서 기반 SOAP 메시지를 Bare 모드에서 인코딩된 매개 변수와 함께 사용하는 경우입니다.

XmlElement 특성을 사용하는 방법에 대한 자세한 내용은 방법: XML Serialization을 사용하여 SOAP 메시지 사용자 지정을 참조하십시오.

참고 항목