Web Services使用SOAP Header

在Web Services方法进行通信使用SOAP遵循标准的SOAP格式，该格式的一部分是在XML文档中编码的数据。XML文档包含一个Envelope根元素（由必需的Body元素和可选的Header元素构成）。Body元素由特定于消息的数据构成。可选的Header元素可以包含不与特定消息直接相关的其他信息。

一、定义和处理SOAP Header

在ASP.NET创建的Web Services可以定义和操作SOAP Header。通过在特定的SOAP Header中定义数据类并从SoapHeader类（在System.Web.Services.Protocols命名空间下）派生，便可完成SOAP Header的定义。

 1:  [WebService(Namespace = "http://tempuri.org/")]

 2:  [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]

 3:  [System.ComponentModel.ToolboxItem(false)]

 4:  public class WebService_SoapHeader : System.Web.Services.WebService

 5:  {

 6:      //定义MySoapHeader变量用来保存SoapHeader值

 7:      public MySoapHeader mySoapHeader;

 8:   

 9:      [WebMethod]

10:      [SoapHeader("mySoapHeader")]

11:      public string HelloWorld(string name)

12:      {

13:          return "Hello,"+name;

14:      }

15:  }

16:   

17:  public class MySoapHeader : SoapHeader

18:  {

19:      public int UserID;

20:      public DateTime LoginTime;

21:      public string UserName;

22:  }

23:   

查看生成的SOAP的Post内容：

POST /WebService_SoapHeader.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/HelloWorld"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MySoapHeader xmlns="http://tempuri.org/">
      <UserID>int</UserID>
      <LoginTime>dateTime</LoginTime>
      <UserName>string</UserName>
    </MySoapHeader>
  </soap:Header>
  <soap:Body>
    <HelloWorld xmlns="http://tempuri.org/">
      <name>string</name>
    </HelloWorld>
  </soap:Body>
</soap:Envelope>

二、客户端使用Soap Header

引用或使用Wsdl.exe工具可以生成Web Services的引用辅助类。Web Services定义的Soap Header会生成对应的代码：

 1:  [System.CodeDom.Compiler.GeneratedCodeAttribute("System.Xml", "4.0.30319.1")]

 2:  [System.SerializableAttribute()]

 3:  [System.Diagnostics.DebuggerStepThroughAttribute()]

 4:  [System.ComponentModel.DesignerCategoryAttribute("code")]

 5:  [System.Xml.Serialization.XmlTypeAttribute(Namespace="http://tempuri.org/")]

 6:  public partial class MySoapHeader : object, System.ComponentModel.INotifyPropertyChanged {

 7:   

 8:      private int userIDField;

 9:   

10:      private System.DateTime loginTimeField;

11:   

12:      private string userNameField;

13:   

14:      private System.Xml.XmlAttribute[] anyAttrField;

15:   

16:      /// <remarks/>

17:      [System.Xml.Serialization.XmlElementAttribute(Order=0)]

18:      public int UserID {

19:          get {

20:              return this.userIDField;

21:          }

22:          set {

23:              this.userIDField = value;

24:              this.RaisePropertyChanged("UserID");

25:          }

26:      }

27:   

28:      /// <remarks/>

29:      [System.Xml.Serialization.XmlElementAttribute(Order=1)]

30:      public System.DateTime LoginTime {

31:          get {

32:              return this.loginTimeField;

33:          }

34:          set {

35:              this.loginTimeField = value;

36:              this.RaisePropertyChanged("LoginTime");

37:          }

38:      }

39:   

40:      /// <remarks/>

41:      [System.Xml.Serialization.XmlElementAttribute(Order=2)]

42:      public string UserName {

43:          get {

44:              return this.userNameField;

45:          }

46:          set {

47:              this.userNameField = value;

48:              this.RaisePropertyChanged("UserName");

49:          }

50:      }

51:   

52:      /// <remarks/>

53:      [System.Xml.Serialization.XmlAnyAttributeAttribute()]

54:      public System.Xml.XmlAttribute[] AnyAttr {

55:          get {

56:              return this.anyAttrField;

57:          }

58:          set {

59:              this.anyAttrField = value;

60:              this.RaisePropertyChanged("AnyAttr");

61:          }

62:      }

63:   

64:      public event System.ComponentModel.PropertyChangedEventHandler PropertyChanged;

65:   

66:      protected void RaisePropertyChanged(string propertyName) {

67:          System.ComponentModel.PropertyChangedEventHandler propertyChanged = this.PropertyChanged;

68:          if ((propertyChanged != null)) {

69:              propertyChanged(this, new System.ComponentModel.PropertyChangedEventArgs(propertyName));

70:          }

71:      }

72:  }

73:   

对于Web Method,Soap Header会变成Web Method的第一个参数：

1:  public string HelloWorld(Client.SoapHeaderService.MySoapHeader MySoapHeader, string name) {

2:      Client.SoapHeaderService.HelloWorldRequest inValue = new Client.SoapHeaderService.HelloWorldRequest();

3:      inValue.MySoapHeader = MySoapHeader;

4:      inValue.name = name;

5:      Client.SoapHeaderService.HelloWorldResponse retVal = ((Client.SoapHeaderService.WebService_SoapHeaderSoap)(this)).HelloWorld(inValue);

6:      return retVal.HelloWorldResult;

7:  }

8:   

客户端测试代码，首先定义Soap Header，再把Soap Header作为Web Method的参数传递：

 1:   static void Main(string[] args)

 2:   {

 3:       SoapHeaderService.WebService_SoapHeaderSoapClient client = new SoapHeaderService.WebService_SoapHeaderSoapClient();

 4:   

 5:       SoapHeaderService.MySoapHeader soapHeader = new SoapHeaderService.MySoapHeader();

 6:       soapHeader.UserID = 1;

 7:       soapHeader.UserName = "User1";

 8:       soapHeader.LoginTime = DateTime.Now;

 9:   

10:       client.HelloWorld(soapHeader, "UserA");

11:  }

12:   

利用tcpTrace可以查看Post的内容：

在Web Service的Web Method接收到Soap Header：

三、SoapHeader的Direction属性

SoapHeaderDirection有四个值，分别为In、Out、InOut、Flaut。模式值是In。

1、使用In定义Soap Header,In方式跟上面的例子一样。

2、使用Out定义Soap Header:

 1:  public class WebService_SoapHeader : System.Web.Services.WebService

 2:  {

 3:      public MySoapHeader mySoapHeader;

 4:   

 5:      [WebMethod]

 6:      [SoapHeader("mySoapHeader",Direction=SoapHeaderDirection.Out)]

 7:      public string HelloWorld(string name)

 8:      {

 9:          return "Hello,"+name;

10:      }

11:  }

12:   

Soap的Reaspone内容：

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MySoapHeader xmlns="http://tempuri.org/">
      <UserID>int</UserID>
      <LoginTime>dateTime</LoginTime>
      <UserName>string</UserName>
    </MySoapHeader>
  </soap:Header>
  <soap:Body>
    <HelloWorldResponse xmlns="http://tempuri.org/">
      <HelloWorldResult>string</HelloWorldResult>
    </HelloWorldResponse>
  </soap:Body>
</soap:Envelope>

3、使用InOut定义Soap Header:

1:  [WebMethod]

2:  [SoapHeader("mySoapHeader",Direction=SoapHeaderDirection.InOut)]

3:  public string HelloWorld(string name)

4:  {

5:      return "Hello,"+name;

6:  }

7:   

Soap的Request：

POST /WebService_SoapHeader.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/HelloWorld"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MySoapHeader xmlns="http://tempuri.org/">
      <UserID>int</UserID>
      <LoginTime>dateTime</LoginTime>
      <UserName>string</UserName>
    </MySoapHeader>
  </soap:Header>
  <soap:Body>
    <HelloWorld xmlns="http://tempuri.org/">
      <name>string</name>
    </HelloWorld>
  </soap:Body>
</soap:Envelope>

Soap的Response：

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MySoapHeader xmlns="http://tempuri.org/">
      <UserID>int</UserID>
      <LoginTime>dateTime</LoginTime>
      <UserName>string</UserName>
    </MySoapHeader>
  </soap:Header>
  <soap:Body>
    <HelloWorldResponse xmlns="http://tempuri.org/">
      <HelloWorldResult>string</HelloWorldResult>
    </HelloWorldResponse>
  </soap:Body>
</soap:Envelope>

4、使用Fault定义Soap Header

1:  [WebMethod]

2:  [SoapHeader("mySoapHeader",Direction=SoapHeaderDirection.Fault)]

3:  public string HelloWorld(string name)

4:  {

5:      return "Hello,"+name;

6:  }

7:   

使用Fault，Soap的描述跟使用Out基本一致：

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MySoapHeader xmlns="http://tempuri.org/">
      <UserID>int</UserID>
      <LoginTime>dateTime</LoginTime>
      <UserName>string</UserName>
    </MySoapHeader>
  </soap:Header>
  <soap:Body>
    <HelloWorldResponse xmlns="http://tempuri.org/">
      <HelloWorldResult>string</HelloWorldResult>
    </HelloWorldResponse>
  </soap:Body>
</soap:Envelope>

四、处理未知的Soap Header

ASP.NET Web Service通过SoapUnknownHeader来标识未知的Soap Header，SOAP规范通过mustUnderstand特性来表示对Soap Header的要求，当mustUnderstand特性设置为true时，如果传入未知的Soap Header将引发异常。

注意：ASP.NET 使用DidUnderstand 属性来与 Web Services的方法进行通信。它不属于 SOAP 规范；它的值不会出现在 SOAP 请求或 SOAP 响应的任何部分中。

五、Soap Header的异常处理

当 Web Services检测到与处理 SOAP Header有关的错误时，应该会引发 SoapHeaderException。利用此异常类，Web Services可以正确地设置响应的格式。