摘要:本文讲解微软asp.net web服务方法(webmethod)是如何提供高效率的建立web服务的途径的。webmethod可以把传统的微软.net方法暴露为web服务操作,支持http、xml、xml schema、soap和wsdl。webmethod(.asmx)处理处理程序能自动地把输入的soap消息传递给适当的方法,并自动地把输入的xml元素串行化为相应的.net对象。
介绍
目前在微软.net中实现基于http的web服务有两种根本不同的途径。最底层的技术是编写一个插入.net http管道的自定义ihttphandler类。这种途径要求你使用system.web api来处理输入的http消息,使用system.xml api处理http体中的soap封装。编写自定义处理程序要求你手工建立正确描述实现的wsdl文档。严格执行所有的这些操作要求你非常了解xml、xsd、soap和wsdl规范,但是这对于大多数开发者来说很困难。
实现web服务的效率更高的途径是使用微软asp.net webmethods框架组件。asp.net为.asmx终结点(称为webservicehandler)发布了一个特定的ihttphandler类,它提供必要的xml、xsd、soap和wsdl功能的范本文件。因为webmethods框架组件把你从下层xml技术的复杂性中解放了出来,你能够快速聚焦于手头的业务问题。
图1:灵活性和生产率之间的折衷
在实现技术之间作出选择形成了图1中所示的灵活性和生产率之间的折衷。编写自定义的ihttphandler给了你无限大的灵活性,但是要花费你很长时间编写、测试和调试代码。webmethods框架组件使建立自己的web服务和快速运行变得很容易,但是很明显你要受到该框架组件界限的限制。但是,在webmethods框架组件不能提供你完全需要的信息的情况下,可以通过添加自己的附加功能来扩展该框架组件。
通常,除非你已经掌握了xml、xsd、soap和wsdl并且原意承担直接处理它们的负担,最好不要专注于web服务所需要的webmethods框架组件。它提供了大多数web服务端点(endpoints)所需要的基本服务,以及能把框架组件进行”弯曲”来适合你的精确的需要的一些有趣的可扩充能力。本文是基于这种假定讨论webmethods如何工作的内部信息。如果你不太了解xml schema和soap,可以参阅understanding xml schema和understanding soap。
webmethods框架组件
webmethods框架组件循环地把soap消息映射到.net类中的方法。这种功能的实现首先需要把你的方法注解为system.web.services名字空间中的[webmethod]属性。例如,下面的.net类包含四个方法,其中两个使用[webmethod]属性注解了:
|
为了在webmethods框架组件重使用这个类,你需要把这个类编译为一个部件(assembly)并把它复制到虚拟目录的bin目录中。在这个例子中,add和subtract方法可以被暴露作为web服务操作,但是multiply和divide却不能(因为它们没有使用[webmethod]标记)。
你可以通过一个.asmx端点(endpoint)把add和subtract暴露为web服务操作。为了实现这个功能,建立一个名为math.asmx的包含下面的简单声明的新文本文件,并把它放到包含该部件的虚拟目录中(注意:它自己进入虚拟目录而不是子目录bin中):
|
这个声明告诉.asmx处理程序使用哪个类检查webmethods,并且该处理程序自动处理其它的信息。例如,假定虚拟目录叫作”math”并且它包含了math.asmx,并且bin子目录包含了该部件,那么浏览http://localhost/math/math.asmx将导致.asmx处理程序生成图2所示的文档页面。
这与.asmx处理程序如何工作有较大的变化。.asmx文件通常只包含通过名字引用web服务类(如上所示)的webservice声明。因此,在这种情况下,该部件必须已经被编译好、配置到了虚拟目录的bin目录中。.asmx处理程序也提供.asmx文件中源代码的just-in-time(实时)编译。例如,下面的文件(叫作mathjit.asmx)包含了webservice声明和被引用类的源代码。
|
第一次通过http访问这个文件时,.asmx处理程序编译源代码并把部件配置到正确的位置。注意webservice声明必须提供语言,这样.asmx处理程序才能在运行时选择正确的编译器。这种方法的一个明显的问题是直到你第一次访问该文件时才会发现编译错误。
图2:mathservice文档
当你使用visual studio .net建立一个新的web服务项目时,它通常使用”双文件”技术,把源文件与引用它的.asmx文件分开。集成开发环境(ide)隐藏了这些文件,但是你可以点击”解决方案浏览器”工具条上的show all files(显示所有文件),你会发现项目中的每个web服务类都有两个文件。实际上,visual studio .net并不支持.asmx文件的高亮度提醒或intellisense。有了web项目后,visual studio .net也处理建立虚拟目录并自动把部件编译到虚拟目录的bin目录中。
在深入分析.asmx处理程序如何工作前,我们先简短讨论一下来自iis的消息如何分派到用于处理的.asmx处理程序中。当输入的http消息到达80端口时,iis使用自己的元数据库(metabase)的信息来找出使用哪一个isapi dll来处理这个消息。.net安装程序把.asmx扩展映射到aspnet_isapi.dll,如图3所示。
图3:.asmx 的iis应用程序映射
aspnet_isapi.dll是.net框架组件提供的一个标准的isapi扩充,它简单地把http请求转发到单独的叫作aspnet_wp.exe的工作进程中。aspnet_wp.exe寄宿了通用语言运行时和.net http管道。一旦消息进入.net http管道,管道就查询配置文件,看应该使用哪一个ihttphandler类处理给定的扩充。如果你查看machine.config文件,你会发现它包含了.asm文件的一个httphandler映射,如下所示:
|
因此当某个目标为.asmx文件的消息进入.net http管道时,该管道调用webservicehandlerfactory类来实例化用于处理这个请求的新的webservicehandler对象。webservicehandler对象打开物理的.asmx文件以决定包含webmethods的类的名称。
一旦.asmx处理程序被.net http管道调用,它就开始处理xml、xsd、soap和wsdl进程。.asmx处理程序提供的功能可以分为三个部分:1)消息发送;2)把xml映射到对象;3)自动化wsdl和文档生成。下面讲详细讲解每一部分。
消息发送
当http管道调用.asmx处理程序时,它通过查看.asmx文件中的webservice声明来找出使用哪个.net类来检查。接着它查看输入的http消息的信息以正确地决定调用被引用类地哪个方法。为了调用前面的例子中显示的add操作,输入的http消息必须有类似下面的信息:
|
在输入的http消息中的确有两部分信息可以用于找出调用类中的哪个方法:soapaction头部或者请求的元素名称(例如soap:body元素内的元素名称)。在这种情况下,任何一个都表明了发送者希望调用的方法的名称。
默认情况下.asmx处理程序使用soapaction头部的值来执行消息发送。因此,.asmx 处理程序查看消息中的soapaction头部,接着使用.net反射(reflection)检查被引用类中的方法。它只考虑使用[webmethod]标志标记的方法,但是它通过查看每个方法的soapaction值来正确地决定调用哪个方法。因为我们没有在自己的类的方法中明确指定soapaction的值,.asmx处理程序就假定soapaction的值是web服务的名字空间后面跟上方法名称的组合。因为我们也没有指定名字空间,处理程序就把http://tempuri.org作为默认值。因此add方法的默认的soapaction值是http://tempuri.org/add。
你可以使用[webservice]标志作为类的注解来自定义web服务的名字空间,使用下面所说明的[soapdocumentmethod]标志作为webmethods的注解来指定soapaction的值:
|
现在.asmx处理程序认为add 方法的soapaction的值为http://example.org/math/add(使用默认的启发式),subtract方法的为urn:math:subtract(因为我们明确地定义了这个值)。例如,下面的http请求消息调用subtract操作:
|
如果.asmx处理程序无法查找到匹配输入的http消息的soapaction,它简单地抛出一个异常(后面将解释异常如何处理)。如果你不愿意依赖soapaction头部来进行方法调度,你可以指示.asmx处理程序通过使用[soapdocumentservice]标志的routingstyle属性作为类的注解来使用请求元素地名称。如果你这样做了,你大概也会通过把soapaction的值设置为空字符串来表明webmethods不需要soapaction值:
|
在这种情况下,处理程序不会查看soapaction值–它使用请求元素的名称作为代替。例如,它认为add方法的请求元素的名称为add(来自http://example.org/math名字空间),下面演示了这种http请求消息:
|
因此,.asmx处理程序接收到一个输入的http请求时,第一件重要的事情是找出怎样把这个消息发送到对应的webmethod。但是在能够实际调用该方法前,它需要把输入的xml映射到.net对象。
把xml映射到对象
一旦webmehod处理程序找出了将调用哪个方法,接着它就需要把xml消息转换为可以提供给方法调用的.net对象。在消息发送后,处理程序通过反射检查该类找出如何处理输入的xml消息以达到这个目的。system.xml.serialization名字空间中的xmlserializer类执行xml和对象之间的自动映射。
xmlserializer使任何公共的.net类型映射到xml schema类型成为可能,并且有了类似的映射,它可以在.net对象和xml实例文档之间自动映射(图4所示)。目前xmlserializer被限制为xml schema所支持的模型,因此不能处理目前现代的对象模型(例如复杂的非树型对象图表、两重指针等等)的所有复杂性。然而,xmlserializer可以处理开发者趋向使用的大多数复杂的类型。
对于上面的例子中所示的add方法,xmlserializer会把x和y元素映射到.net双精度型值,那么调用add时它们就可以使用了。add方法给调用者返回一个双精度型值,接着需要串行化该值返回为soap响应中的一个xml元素。
图4:把xml映射到对象
xmlserializer也能自动处理复杂的类型(除了上面描述的限制)。例如,下面的webmethod计算两个point(点)结构体之间的距离。
|
这种操作的soap请求消息将包含一个distance元素,该元素包含两个子元素,一个叫作orig,另一个叫dest,它们每个都包含两个子元素x和y,如下所示:
|
这种情况下的soap响应消息将包含一个distanceresponse元素,该元素包含一个双精度类型的distanceresult元素:
|
默认的xml映射使用方法的名称作为请求元素的名称,参数的名称作为它的子元素的名称。每个参数的结构依赖于类型的结构。公共字段和属性的名称简单地映射到子元素(这种情况下是point中的x和y)。默认情况下响应元素的名称是请求元素的名称后面加上”response”。响应元素也包含一个子元素,名称为请求元素的名称加上”result”。
你可以使用一系列内建的映射标志从标准的xml映射中解放出来。例如,你可用使用[xmltype]标志自定义类型的名称和名字空间。你可以使用[xmlelement]和[xmlattribute]标志来控制参数或类成员如何分别映射到元素或属性。你可以使用[soapdocumentmethod]标志来控制方法自身如何映射到请求/响应消息中的元素名称。例如,你可以看一看下面版本的distance示例的多种标志:
|
这个版本的distance要求输入的soap消息格式如下:
|
它生成的soap响应消息的格式如下:
|
该.asmx处理程序使用soap document/literal样式来实现和描述上面所示的默认映射。这意味着该wsdl定义将包含描述soap消息中所使用的请求和响应元素的字面上的xml schema定义(例如,没有使用soap编码规则)。
该.asmx处理程序也可以使用soap rpc/encoded样式。这意味着soap主体(body)包含一个rpc调用的xml表现,并且参数都使用soap编码规则串行化了(例如,不需要xml schema)。为了达到这个目标,使用[soaprpcservice]和[soaprpcmethod]代替[soapdocumentservice]和[soapdocumentmethod]标志。如果你要了解这些样式之间的差别,请参阅understanding soap。
从上面的信息中你可以发现,完全地自定义如何把给定的方法映射到soap消息是可能的。xmlserializer提供了强大的串行化引擎以及许多我们在此文中没有讨论的特性。如果你要了解xmlserializer如何工作的详细信息,请查阅moving to .net and web services。
作为处理参数的并行化的补充,.asmx处理程序也能够并行化/串行化soap头部。soap头部的处理方法与参数不同,因为典型情况下它们被认为是范围之外的信息,没有直接关联到某个特定的方法。由于这个原因,典型的头部处理是由监听层完成的,使webmethod根本不用进行头部处理。
但是,如果你希望在webmethod中处理头部信息,你必须提供一个演示自soapheader(它描述了头部的xml schema类型)的.net类。接着你定义该类型的一个成员变量作为头部实例的位置标志符。最后,你给每个需要访问该头部的webmethod作注解,指定你需要处理的字段的名称。
例如,看一看下面的包含用于身份验证目的的usernametoken头部的soap请求:
|
为了使.asmx处理程序能够并行化该头部,首先你必须定义一个描述隐含的xml schema类型的.net类(注意:如果你已经有了该头部的xml schema,那么可以使用xsd.exe /c生成这个类)。在这种情况下,相应的类如下所示:
|
接着,你必须在webmethod类中简单地定义一个成员变量来保持该头部类的一个实例,并使用[soapheader]标志来注解该webmethod,如下所示:
|
接着,在webmethod中你可以访问该头部提供的token字段并提取信息。你也可以使用相同的技术把该头部送回给客户端–你只需要在[soapheader]标志声明中简单地指定头部的方向。需要了解在webmethod框架组件中处理soap头部的更多信息,请查阅digging into soap headers with the .net framework。
.asmx处理程序也提供了.net异常的自动的串行化。任何被.asmx捕捉到的没有处理的异常都自动地串行化进入响应中的soap fault元素。例如,在前面的例子中,如果用户名与与密码不匹配,代码将抛出一个.net异常。接着.asmx处理程序捕捉到这个异常并串行化到下面所示的soap响应中:
|
如果你需要更多地soap fault元素控制权,可以明确地抛出一个soapexception对象,指定所有的soap fault元素细节,例如faultcode、faulstring、faultactor和detail元素。你可以参阅using soap faults获得更多信息。
如上所示,指出webmethod如何工作必须了解下层串行化引擎和它的多种选项。串行化引擎的优点是它隐藏了所有的通常在编写自定义处理程序中需要的下层xml api代码。但是,尽管大多数开发者发现这是有正面意义的,有一些开发者认为它是一个缺陷,因为它们仍然希望在webmethod实现中手动包装soap消息。要了解如何实现这种混合的途径的详细信息,请参阅accessing raw soap messages in asp.net web services。
自动生成wsdl
一旦你已经编写并配置了一个webmethod,客户端为了成功地与它通讯,需要了解正确地soap消息是什么样子的。提供web服务描述的标准的途径是wsdl(或嵌入式xsd定义)。为了帮助适应这种情况,.asmx处理程序自动生成人类可以阅读的文档页面和准确反映webmethod接口的wsdl定义。如果你给webmethods应用了一系列的映射标志,它们都会反映在生成的文档中。
如果你浏览.asmx文件,你会看到类似图2所示的可以阅读的文档页面。该文档页面是由一个叫作defaultwsdlhelpgenerator.aspx的.aspx页面(位置在c:\windows\microsoft.net\framework\ v1.0.3705\config)生成的。如果打开这个文件,你可以发现这仅仅是一个使用.net反射生成文档的标准的asp.net页面。这个特性使你的文档一直与代码同步。你可以简单地修改这个文件来自定义生成的文档。
你可以通过在web.config文件中指定一个不同的文档文件来绕过在虚拟目录基础上的文档生成:
|
如果客户端提出的.asmx端点的get请求在请求字符串中有”?wsdl”,那么.asmx处理程序会生成wsdl定义来代替可以阅读的文档。客户端可以使用这个wsdl定义来生成自动了解如何与web服务通讯的代理类(例如在.net中使用wsdl.exe)。
为了自定义wsdl生成进程,你可以编写一个soapextensionreflector类并在web.config文件中向webmethods框架组件注册。接着,当.asmx处理程序生成wsdl定义时,它将调用你的反射类,给了你自定义最终提供给客户端的定义的机会。如果你要了解更多的编写soapextensionreflector类的方法,请查看soapextensionreflectors in asp.net web services。
你可以使用两种不同的技术来绕过wsdl生成进程。第一种是你可以在虚拟目录种为客户端的访问提供静态的wsdl文档并在web.config文件中删除文档生成部分,如下所示:
|
另一种稍微自动化的技术是使用[webservicesbinding]标志来指定实现webmethod类的虚拟目录中的静态wsdl文档的位置。你也必须使用[soapdocumentmethod]标志指定帮定到每个webmethod实现的wsdl的名称。有了这些后,自动化的wsdl生成进程将导入你的静态wsdl文件并在它周围包装一个新的服务描述。如果你要了解这种技术的更多信息,请查阅place xml message design ahead of schema planning to improve web service interoperability。
目前wsdl极难手动编写,因为没有很多的可用的wsdl编辑器。因此,自动的文档/wsdl生成是webmethods框架组件中有价值的一部分,很多开发者将很长时间依赖它。
结论
asp.net的webmethods框架组件提供了一条高效率建立web服务的途径。webmethods把传统.net方法为支持http、xml、xml schema、soap和wsdl暴露为web服务操作成为可能。webmethods(.asmx)处理程序自动找出怎样把输入的soap消息分派给适当的方法,这时它自动把输入的xml元素串行化成相应的.net对象。为了简化与客户端的集成,.asmx处理程序也提供了生成人类可读(html)和计算机可读(wsdl)文档的自动支持。
尽管webmethods框架组件与自定义ihttphandlers相比稍微有点限制,但是它也提供了强大的可扩展性模型,就是我们所知道的soap扩展框架组件。soap扩展允许你根据需要引入附加的功能。例如,微软为.net发布了web services enhancements 1.0(wse),它仅仅提供了一个soapextension类,该类为webmethods框架组件引入了对几种gxa规格的支持。如果你需要了解编写soap扩展的更多信息,请参阅fun with soap extensions。
