在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可以正确地设置响应的格式。