博客园_Artech

[WCF REST] 通过ASP.NET Output Caching实现声明式缓存

2012-02-10T00:58:00Z

ASP.NET的输出缓存（Output Caching）机制允许我们针对整个Web页面或者页面的某个部分（主要针对用户控件）最终呈现的HTML进行缓存。对于后续针对相同资源的请求，只需要直接将缓存的HTML予以回复而无须按照页面处理生命周期对每次请求进行重复处理。WCF通过操作行为AspNetCacheProfileAttribute利用ASP.NET的输出缓存提供一种针对于某个操作的声明式缓存机制。[源代码从这里下载]

一、AspNetCacheProfileAttribute

WCF对ASP.NET缓存的支持是通过AspNetCacheProfileAttribute特性来实现的。通过如下的代码我们不难看出AspNetCacheProfileAttribute是实现了IOperationBehavior接口的操作行为，我们可以直接将其应用到契约接口/类中的某个具有缓存需要的操作方法上。

   1: [AttributeUsage(AttributeTargets.Method)]

   2: public sealed class AspNetCacheProfileAttribute : Attribute, IOperationBehavior

   3: {

   4:     //其他成员

   5:     public AspNetCacheProfileAttribute(string cacheProfileName);

   6:     public string CacheProfileName { get; }

   7: }

AspNetCacheProfileAttribute构造函数参数cacheProfileName表示的CacheProfile的配置名称，目标操作按照定义在相应CacheProfile的缓存策略实施缓存。CacheProfile配置在<system.web>/<caching>/<outputCacheSettings>/<outputCacheProfiles>节点下。

   1: <configuration>

   2:   <connectionStrings>

   3:     <add name="localDb"

   4:          connectionString="Server=.; Database=TestDb; Uid=sa; Pwd=password"

   5:          providerName="System.Data.SqlClient"/>

   6:   </connectionStrings>

   7:   <system.web>

   8:     <caching>

   9:       <outputCacheSettings>

  10:         <outputCacheProfiles>

  11:           <add name="default"

  12:                duration="60"

  13:                varyByParam="none"

  14:                sqlDependency="TestDb: TestTable"/>

  15:         </outputCacheProfiles>

  16:       </outputCacheSettings>

  17:       <sqlCacheDependency>

  18:         <databases>

  19:           <add name="TestDb" connectionStringName="localDb"/>

  20:         </databases>

  21:       </sqlCacheDependency>

  22:     </caching>

  23:   </system.web>

  24: </configuration>

在如上所示的配置片断中，我们定义了一个名称为default的CacheProfile。代表缓存时间的duration属性被设置为60，意味着缓存项在被存储之后1分钟之后实失效；属性varyByParam被设置为none表示缓存项与请求的查询字符串无关。此外，该CacheProfile还设置针对某个本地数据库中的TestTable表的SQL依赖（SQL Dependency）。关于CacheProfile的配置属于ASP.NET的范畴，在这里我们不会作过多的讨论。

既然是采用ASP.NET输出缓存，WCF服务自然需要采用IIS寄宿并采用ASP.NET 兼容模式。值得一提的是，基于AspNetCacheProfileAttribute的输出缓存仅仅针对HTTP-GET。

二、实例演示：创建采用输出缓存的服务

接下来我们通过一个简单的实例来演示如何通过操作行为对某个操作的返回值实施缓存，为此我们创建一个用于返回当前时间的服务。如下所示的是作为服务契约的ITime接口的定义，AspNetCacheProfileAttribute特性被应用到了用于返回当前时间的操作方法GetCurrentTime上。

   1: using System;

   2: using System.ServiceModel;

   3: using System.ServiceModel.Web;

   4: namespace Artech.WcfServices.Service.Interface

   5: {

   6:     [ServiceContract(Namespace = "http://www.artech.com/")]

   7:     public interface ITime

   8:     {

   9:         [WebGet(UriTemplate = "/current")]

  10:         [AspNetCacheProfile("default")]

  11:         DateTime GetCurrentTime();

  12:     }

  13: }

实现了契约接口ITime的服务类型TimeService定义如下。我们将AspNetCompatibilityRequirementsAttribute特性应用在服务类型上并将RequirementsMode属性设置为Allowed以提供对ASP.NET兼容模式的支持。

   1: using System;

   2: using System.ServiceModel.Activation;

   3: using Artech.WcfServices.Service.Interface;

   4: namespace Artech.WcfServices.Service

   5: {

   6:     [AspNetCompatibilityRequirements(

   7:      RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]

   8:     public class TimeService : ITime

   9:     {

  10:         public DateTime GetCurrentTime()

  11:         {

  12:             return DateTime.Now;

  13:         }

  14:     }

  15: }

在一个Web项目中我们为通过IIS寄宿的服务TimeService添加一个对应的.svc文件（TimeService.svc），如下所示的是<%@ServiceHost%>指令的定义。表示ServiceHostFactory类型的指令属性Factory被设置为System.ServiceModel.Activation.WebServiceHostFactory.

   1: <%@ ServiceHost Service="Artech.WcfServices.Service.TimeService" Factory="System.ServiceModel.Activation.WebServiceHostFactory"%>

我们在作为服务宿主的Web项目下添加一个配置文件（Web.config）并定义如下的配置。除了服务寄宿的基本配置外，我们将<system.serviceModel>/<serviceHostingEnvironment >配置节的aspNetCompatibilityEnabled属性设置为True以开启ASP.NET兼容模式。应用在操作方法GetCurrentTime上的AspNetCacheProfileAttribute特性中指定的名称为default的CacheProfile定义在该配置中，duration和varyByParam分别被设置为60和none。

   1: <configuration>

   2:     <system.serviceModel>

   3:         <services>

   4:             <service name="Artech.WcfServices.Service.TimeService">

   5:                 <endpoint binding="webHttpBinding"

   6:                           contract="Artech.WcfServices.Service.Interface.ITime"/>

   7:             </service>

   8:         </services>

   9:       <serviceHostingEnvironment aspNetCompatibilityEnabled="true" />

  10:     </system.serviceModel>

  11:   <system.web>

  12:     <caching>

  13:       <outputCacheSettings>

  14:         <outputCacheProfiles>

  15:           <add name="default" duration="60" varyByParam="none"/>

  16:         </outputCacheProfiles>

  17:       </outputCacheSettings>

  18:     </caching>

  19:   </system.web>

  20: </configuration>

作为客户端的控制台程序在进行了相应配置之后通过如下的代码进行服务的调用。在这段代码中，我们通过创建的服务代理进行了5次服务调用，并将获取的时间打印出来。每次服务的时间间隔为1秒。

   1: using (ChannelFactory<ITime> channelFactory =  new ChannelFactory<ITime>("timeService"))

   2: {

   3:     ITime proxy = channelFactory.CreateChannel();

   4:     for (int i = 0; i < 5; i++)

   5:     {

   6:         Console.WriteLine(proxy.GetCurrentTime().ToLongTimeString());

   7:         Thread.Sleep(1000);

   8:     }

   9: }

客户端代码执行之后会在控制台上输出如下的结果。由于服务端通过ASP.NET的输出缓存对第一次执行GetCurrentTime操作的结果进行了缓存，所以客户端返回的时间都是相同的。

   1: 4:48:43 PM

   2: 4:48:43 PM

   3: 4:48:43 PM

   4: 4:48:43 PM

   5: 4:48:43 PM

三、 AspNetCacheProfileAttribute是如何实现输出缓存的？

既然我们采用ASP.NET兼容模式来寄宿服务，意味着我们调用某个服务与访问某个页面没有本质的区别，所以基于Web页面的输出缓存能够应用于基于某个服务操作的调用就不足为奇了。现在有这么一个问题：通过AspNetCacheProfileAttribute特性指定CacheProfile是如何生效的？

如果对ASP.NET具有一定的了解，应该知道可以通过当前HttpResponse（HttpContext.Current.Response）的Cache属性表示的HttpCachePolicy对象来控制当前输出缓存的基本策略。实际上AspNetCacheProfileAttribute就是通过这种方式将定义在指定CacheProfile的缓存策略应用到针对当前操作的调用上的。

具体来说，AspNetCacheProfileAttribute针对输出缓存策略的控制是通过一个实现了接口IParameterInspector的自定义参数检验器实现的，这是一个名称为CachingParameterInspector的内部类型。操作行为AspNetCacheProfileAttribute通过实现的ApplyDispatchBehavior方法将针对某个CacheProfile创建的CachingParameterInspector对象添加到当前分发操作（DispatchOperation）的参数检验器列表中。

   1: internal class CachingParameterInspector : IParameterInspector

   2: {

   3:     public CachingParameterInspector(string cacheProfileName);

   4:     public object BeforeCall(string operationName, object[] inputshens);

   5:     public void AfterCall(string operationName, object[] outputs, object returnValue, object correlationState)

   6:     {

   7:         //将指定CacheProfile的输出缓存策略应用到当前HttpResponse

   8:     }

   9: }

如上面的代码片断所示，当AfterCall方法被执行的之后，在构造函数中指定的CacheProfile定义的输出缓存策略应用到当前HttpResponse。而AfterCall会在操作执行之后，回复消息序列化之前被执行。

本文链接

[WCF REST] UriTemplate、UriTemplateTable与WebHttpDispatchOperationSelector

2012-02-09T01:13:00Z

REST服务采用面向资源的架构，而资源通过URI进行标识和定位，所以URI在REST中具有重要的地位。对于WCF来说，服务调用请求的URI映射为某个具体的操作，所以服务端需要解决的是如何根据请求URI选择出对应的操作。如果采用SOAP，操作的选择是根据消息的<Action>报头来实现的，那么REST服务又采用怎样的操作选择机制呢？

目录
一、URI模板
二、UriTemplate
三、UriTemplateTable
四、WebHttpDispatchOperationSelector
五、实例演示、自定义OperationSelector实现基于URI模板的操作选择机制

一、URI模板

在定义服务契约的时候，我们可以通过应用在操作方法上的WebGetAttribute和WebInvokeAttribute特性的UriTemplate属性定义一个URI模板。如下面的代码片断所示，我们为契约接口ICalculator的Add操作定义了Uri模板"Add/{x}/{y}")，路经部分{x}和{y}对应着操作方法同名的参数。如果终结点地址为http://127.0.0.1:3721/calculatorservice，我们可以访问地址http://127.0.0.1:3721/calculatorservice/add/1/2调用Add操作并传入操作数1和2。

   1: [ServiceContract(Namespace = "http://www.artech.com/")]

   2: public interface ICalculator

   3: {

   4:     [WebGet(UriTemplate = "Add/{x}/{y}")]

   5:     double Add(double x, double y);

   6: }

关于URI模板定义的语法和规范，请参考http://msdn.microsoft.com/en-us/library/bb675245.aspx

二、UriTemplate

在Web HTTP编程模型中，URI模板通过具有如下定义的UriTemplate表示。UriTemplate具有一系列的构造函数重载，这些重载除了接受以字符串类表示的URI模板作为参数之外，还具有额外的一些参数。布尔类型的参数ignoreTrailingSlash表示是否需要忽略URI模板最右边的斜杠（“/”），而字典参数additionalDefaults用于指定默认变量值。

   1: public class UriTemplate

   2: {

   3:     //其他成员

   4:     public UriTemplate(string template);

   5:     public UriTemplate(string template, bool ignoreTrailingSlash);

   6:     public UriTemplate(string template, IDictionary<string, string> additionalDefaults);

   7:     public UriTemplate(string template, bool ignoreTrailingSlash, IDictionary<string, string> additionalDefaults);

8:

   9:     public IDictionary<string, string> Defaults { get; }

  10:     public bool IgnoreTrailingSlash { get; }

  11:     public ReadOnlyCollection<string> PathSegmentVariableNames { get; }

  12:     public ReadOnlyCollection<string> QueryValueVariableNames { get; }

13:

  14:     public Uri BindByName(Uri baseAddress, IDictionary<string, string> parameters);

  15:     public Uri BindByName(Uri baseAddress, NameValueCollection parameters);

  16:     public Uri BindByName(Uri baseAddress, IDictionary<string, string> parameters, bool omitDefaults);

  17:     public Uri BindByName(Uri baseAddress, NameValueCollection parameters, bool omitDefaults);

  18:     public Uri BindByPosition(Uri baseAddress, params string[] values);

19:

  20:     public UriTemplateMatch Match(Uri baseAddress, Uri candidate);

  21: }

UriTemplate具有三个只读的属性。IgnoreTrailingSlash属性返回调用构造函数指定的同名参数，默认值为True，意味着在默认情况在模板字符串结尾指定的斜杠会被忽略。PathSegmentVariableNames和QueryValueVariableNames则返回路径表达式和查询字符串表达式中指定的变量名。

我们可以指定基地址和变量值调用BindByName方法得到一个完整的URI。变量值可以通过字典和NameValueCollection对象的形式指定，其中的Key和Value分别表示变量名和变量值。在BindByPosition方法中我们以字符串数组的形式指定变量值，URI模板中的变量会按照出现的先后顺利进行替换并最终得到一个完整的URI。

方法Match用于判断URI模板是否与指定的某个完整的URI匹配，被用于进行匹配比较的URI通过参数candidate表示，而第一个参数代表的是基地址。如果不匹配则返回Null，否则返回具有如下定义的UriTemplateMatch对象。

   1: public class UriTemplateMatch

   2: {

   3:     public Uri RequestUri { get; set; }

   4:     public Uri BaseUri { get; set; }

   5:     public UriTemplate Template { get; set; }

6:

   7:     public NameValueCollection BoundVariables { get; }

   8:     public NameValueCollection QueryParameters { get; }

9:

  10:     public Collection<string> RelativePathSegments { get; }

  11:     public Collection<string> WildcardPathSegments { get; }

12:

  13:     public object Data { get; set; }

  14: }

UriTemplateMatch属性Template返回的是调用Match方法的UriTemplate对象，而基地址和被用于进行匹配判断的Uri分别通过BaseUri和RequestUri属性返回。被绑定变量（变量名称和值）以及查询字符串参数（参数名称和值）分别通过NameValueCollection类型的属性BoundVariables和QueryParameters返回。属性RelativePathSegments返和WildcardPathSegments分别返回相对路径段和通配路径段。通过可读写属性Data，我们可以将任意一个对象附加在UriTemplateMatch上面。

三、UriTemplateTable

具有如下定义UriTemplateTable本质上是一个KeyValuePair<UriTemplate, object>对象集合，我们可以使用任意类型的对象和某个UriTemplate对象关联。当我们指定某个Uri对象调用它的Match方法时，会遍历集合中的所有UriTemplate对象并调用它的Match方法，最终返回一个UriTemplateMatch集合。对于每个UriTemplateMatch对象，其Data属性直接上就是与对应UriTemplate关联的对象。

而MatchSingle方法被执行的时候会在内部调用Match方法，如果没有匹配的UriTemplate，返回Null；如果只有唯一匹配的UriTemplate，则返回对应的UriTemplateMatch对象；如果多个UriTemplate同时匹配指定的Uri，直接抛出异常。

   1: public class UriTemplateTable

   2: {

   3:     public UriTemplateTable();

   4:     public UriTemplateTable(IEnumerable<KeyValuePair<UriTemplate, object>> keyValuePairs);

   5:     public UriTemplateTable(Uri baseAddress);

   6:     public UriTemplateTable(Uri baseAddress, IEnumerable<KeyValuePair<UriTemplate, object>> keyValuePairs);

7:

   8:     public void MakeReadOnly(bool allowDuplicateEquivalentUriTemplates);

   9:     public Collection<UriTemplateMatch> Match(Uri uri);

  10:     public UriTemplateMatch MatchSingle(Uri uri);

11:

  12:     public Uri BaseAddress { get; set; }

  13:     public Uri OriginalBaseAddress { get; }

  14:     public bool IsReadOnly { get; }

  15:     public IList<KeyValuePair<UriTemplate, object>> KeyValuePairs { get; }

  16: }

构成UriTemplateTable的KeyValuePair<UriTemplate, object>集合通过只读属性KeyValuePairs返回，该属性在构造函数中被初始化。属性BaseAddress 表示基地址，可以在构造函数中初始化，也可以直接通过属性赋值的方式指定。只读属性OriginalBaseAddress表示在构造函数或者针对BaseAddress的属性赋值中指定的Uri，它和BaseAddress唯一不同之处在于：后者经过“标准化（Normalization）”。

   1: Uri baseAddress = new Uri("http://127.0.0.1:3721/calculatorservice");

   2: UriTemplateTable uriTemplateTable = new UriTemplateTable(baseAddress);

   3: Console.WriteLine("{0,-20}: {1}", "BaseAddress", uriTemplateTable.BaseAddress);

   4: Console.WriteLine("{0,-20}: {1}", "OriginalBaseAddress", uriTemplateTable.OriginalBaseAddress);

在如上所示的代码片断中，我们针对基地址http://127.0.0.1:3721/calculatorservice创建了一个UriTemplateTable对象，然后分别在控制台中打印出它的BaseAddress和OriginalBaseAddress属性表示的Uri。从如下所示的输出结果可以看出，OriginalBaseAddress正是我们指定的原生基地址，而经过标准化处理后的BaseAddress的路径部分全部大写，并且添加了后缀“/”。

   1: BaseAddress         : http://localhost/CALCULATORSERVICE/

   2: OriginalBaseAddress : http://127.0.0.1:3721/calculatorservice

UriTemplateTable的只读属性IsReadOnly表示是否处于只读状态，我们通过调用MakeReadOnly方法将此属性设置为True。一旦调用了该方法，我们便不允许对该UriTemplateTable作任何改变。MakeReadOnly具有一个布尔类型的参数allowDuplicateEquivalentUriTemplates表示是否允许存在多个结构等效的UriTemplate。如果该参数为False，多个结构等效UriTemplate的存在会导致异常的发生。

四、WebHttpDispatchOperationSelector

我们所说的服务调用实际上是针对寄宿服务的某个终结点的某个操作的调用，服务端运行时最终需要根据服务调用请求选择出正确的操作。对于针对SOAP的服务调用来说，我们一般通过其<Action>报头作为操作选择的依据，而对于REST服务来说，请求的地址决定了对应的操作。

WCF服务端运行时通过DispatchOperationSelector根据请求消息进行操作的选择，而Web HTTP编程模型通过自定义的DispatchOperationSelector实现了最终的操作选择，这就是我们接下来需要着重介绍的WebHttpDispatchOperationSelector类型。

WebHttpDispatchOperationSelector针对请求地址的操作选择机制是通过UriTemplateTable实现的。我们通过ServiceEndpoint对象创建WebHttpDispatchOperationSelector的时候，会遍历终结点契约的所有操作并获得通过WebGetAttribute/WebInvokeAttribute特性设置URI模板。然后根据URI模板创建UriTemplate对象并最终创建UriTemplateTable。在真正需要进行操作选择的时候，只需要调用该UriTemplateTable的MatchSingle方法并传入请求地址，如果匹配则表明UriTemplate对应的操作就是我们需要选择的操作。

五、实例演示、自定义OperationSelector实现基于URI模板的操作选择机制

为了让读者对WebHttpDispatchOperationSelector的操作选择策略有一个深刻的例子，我按照大致的原理自定义一个DispatchOperationSelector，我们将其命名为WebHttpOperationSelector。整个WebHttpOperationSelector的定义如下所示。

   1: public class WebHttpOperationSelector:IDispatchOperationSelector

   2: {

   3:     public IDictionary<string, UriTemplateTable> UriTemplateTables { get; private set; }

   4:     public WebHttpOperationSelector(ServiceEndpoint endpoint)

   5:     {

   6:         this.UriTemplateTables = new Dictionary<string, UriTemplateTable>();

   7:         Uri baseAddress = endpoint.Address.Uri;

   8:         foreach (var operation in endpoint.Contract.Operations)

   9:         {

  10:             WebGetAttribute webGet = operation.Behaviors.Find<WebGetAttribute>();

  11:             WebInvokeAttribute webInvoke = operation.Behaviors.Find<WebInvokeAttribute>();

  12:             string method = (null != webGet) ? "GET" : webInvoke.Method;

  13:             UriTemplateTable uriTemplateTable;

  14:             if (!this.UriTemplateTables.TryGetValue(method, out uriTemplateTable))

  15:             {

  16:                 uriTemplateTable = new UriTemplateTable(baseAddress);

  17:                 this.UriTemplateTables.Add(method, uriTemplateTable);

  18:             }

  19:             string template = (null !=

  20:             webGet)?webGet.UriTemplate:webInvoke.UriTemplate;

  21:             uriTemplateTable.KeyValuePairs.Add(new KeyValuePair<UriTemplate, object>(new UriTemplate(template),operation.Name));

  22:         }

  23:     }

24:

  25:     public string SelectOperation(ref Message message)

  26:     {

  27:         if (!message.Properties.ContainsKey(HttpRequestMessageProperty.Name))

  28:         {

  29:             return "";

  30:         }

  31:         HttpRequestMessageProperty messageProperty = (HttpRequestMessageProperty)message.Properties[HttpRequestMessageProperty.Name];

32:

  33:         var address = message.Headers.To;

  34:         var method = messageProperty.Method;

  35:         UriTemplateTable uriTemplateTable = null;

  36:         if(!this.UriTemplateTables.TryGetValue(method, out uriTemplateTable))

  37:         {

  38:             return "";

  39:         }

40:

  41:         UriTemplateMatch match = uriTemplateTable.MatchSingle(address);

  42:         if(null == match)

  43:         {

  44:             return "";

  45:         }

  46:         return match.Data.ToString();

  47:     }

  48: }

WebHttpOperationSelector具有一个字典类型的属性UriTemplateTables，Key和Value分别代表请求消息的HTTP方法和与之对应的UriTemplateTable对象。我们基于一个ServiceEndpoint对象来创建WebHttpOperationSelector，在构造函数中我们对UriTemplateTables属性进行了初始化。从上面的代码片断我们可以看出UriTemplateTable中基于某个操作的UriTemplate对象与操作名称关联。

在真正实施操作选择的SelectOperation方法中，我们根据请求消息的HTTP方法从UriTemplateTables属性中得到对应的UriTemplateTable对象。然后以请求消息的<To>报头表示的Uri为参数调用UriTemplateTable的MatchSingle方法，如果该方法返回一个具体的UriTemplateMatch对象，其Data属性即为对应操作的名称。

为了验证WebHttpOperationSelector能够正确地根据请求消息的目标地址选择出对应的操作，我们通过一个简单的实例来验证。如下面的代码片断所示，我们为熟悉的计算服务定义了如下一个契约接口ICalculator。表示加、减、乘、除运算的四个方法应用了WebGetAttribute特性并定义相应的URI模板。

   1: [ServiceContract(Namespace = "http://www.artech.com")]

   2: public interface ICalculator

   3: {

   4:     [WebGet(UriTemplate = "Add/{x}/{y}")]

   5:     double Add(double x, double y);

6:

   7:     [WebGet(UriTemplate = "Substract/{x}/{y}")]

   8:     double Substract(double x, double y);

9:

  10:     [WebGet(UriTemplate = "Multiply/{x}/{y}")]

  11:     double Multiply(double x, double y);

12:

  13:     [WebGet(UriTemplate = "Divide/{x}/{y}")]

  14:     double Divide(double x, double y);

  15: }

然后我们定义如下一个静态方法GetOperationName借助于DispatchOperationSelector对象根据表示请求地址的address选择出正确的操作名称。在这个方法中，我们创建了一个空的消息并将传入的URI作为该消息的To报头，并通过添加一个HttpRequestMessageProperty类型的消息属性将HTTP方法设置为GET。最终将创建的消息作为参数调用DispatchOperationSelector的SelectOperation方法得到正确的操作名称。

   1: static string  GetOperationName(Uri address,

   2:     IDispatchOperationSelector operationSelector)

   3: {

   4:     Message message = Message.CreateMessage(MessageVersion.None, "");

   5:     message.Headers.To = address;

   6:     HttpRequestMessageProperty messageProperty = new HttpRequestMessageProperty();

   7:     messageProperty.Method = "GET";

   8:     message.Properties.Add(HttpRequestMessageProperty.Name, messageProperty);

   9:     return operationSelector.SelectOperation(ref message);

  10: }

在如下的代码片断中，我们针对契约接口ICalculator类型创建了一个ServiceEndpoint对象，其地址为http://127.0.0.1:3721/calculatorservice，绑定类型为WebHttpBinding。然后基于该ServiceEndpoint创建我们定义WebHttpOperationSelector对象。最后我们创建了四个分别表示针对计算服务运算操作的Uri并调用GetOperationName方法测试是否能够根据我们自定义的WebHttpOperationSelector对象正确选择出相应的操作。

   1: EndpointAddress address = new EndpointAddress("http://127.0.0.1:3721/calculatorservice");

   2: Binding binding = new WebHttpBinding();

   3: ContractDescription contract = ContractDescription.GetContract(typeof(ICalculator));

   4: ServiceEndpoint endpoint = new ServiceEndpoint(contract, binding, address);

   5: WebHttpOperationSelector operationSelector = new WebHttpOperationSelector(endpoint);

6:

   7: Uri addAdress       =  new Uri("http://127.0.0.1:3721/calculatorservice/add/1/2");

   8: Uri substractAdress =  new Uri("http://127.0.0.1:3721/calculatorservice/substract/1/2");

   9: Uri multiplyAdress  =  new Uri("http://127.0.0.1:3721/calculatorservice/multiply/1/2");

  10: Uri divideAdress    =  new Uri("http://127.0.0.1:3721/calculatorservice/divide/1/2");

11:

  12: Console.WriteLine(GetOperationName(addAdress,operationSelector));

  13: Console.WriteLine(GetOperationName(substractAdress, operationSelector));

  14: Console.WriteLine(GetOperationName(multiplyAdress, operationSelector));

  15: Console.WriteLine(GetOperationName(divideAdress, operationSelector));

上面的程序执行之后在控制台上会输出如下所示的结果，它们正是与指定URI匹配的操作名称。

   1: Add

   2: Substract

   3: Multiply

   4: Divide

除了为帮助页面提供操作选择和对默认URI模板（应用在操作方法上的WebGetAttribute和WebInvokeAttribute特性并没有对UriTemplate属性进行显式设置）的支持外，WebHttpDispatchOperationSelector实现操作选择的核心逻辑与我们自定义的WebHttpOperationSelector基本类似。WebHttpDispatchOperationSelector最终通过终结点行为WebHttpBehavior（ApplyDispatchBehavior方法）应用到分发运行时上。

本文链接

[WCF REST] WebServiceHost有何特别之处？

2012-02-08T01:00:00Z

WCF为REST服务的寄宿提供了一个新的ServiceHost，即WebServiceHost。WebServiceHost是ServiceHost的子类，而WebServiceHostFactory是对应的ServiceHostFactory，在基于IIS/WAS寄宿中被使用。由于对REST服务绝大部分功能的支持都是通过WebHttpBehavior这么一个终结点行为实现的，所以WebServiceHost的核心功能就是将该终结点行为应用到寄宿服务的所有终结点。除此之外，WebServiceHost还具有一些额外的功能，这些功能都是通过重写OnOpening方法实现的。

一、ServiceDebugBehavior与ServiceMetadataBehavior

由于WebHttpBehavior提供了帮助页面，所以当我们通过WebServiceHost对REST服务进行寄宿的时候会屏蔽掉通过ServiceDebugBehavior服务行为提供的帮助页面。由于通过服务行为ServiceMetadataBehavior实现的元数据发布机制是基于SOAP的，如果我们在寄宿服务上应用了ServiceMetadataBehavior行为，WebServiceHost也会将基于HTTP-GET的元数据发布功能屏蔽。我们可以通过一个简单的实例来证实这一点。

   1: using (WebServiceHost host = new WebServiceHost(typeof(EmployeesService)))

   2: {

   3:     ServiceDebugBehavior serviceDebug =

   4:     host.Description.Behaviors.Find<ServiceDebugBehavior>();

   5:     if (null == serviceDebug)

   6:     {

   7:         serviceDebug = new ServiceDebugBehavior();

   8:         host.Description.Behaviors.Add(serviceDebug);

   9:     }

  10:     serviceDebug.HttpHelpPageEnabled = true;

  11:     serviceDebug.HttpsHelpPageEnabled = true;

12:

  13:     ServiceMetadataBehavior serviceMetadata =

  14:     host.Description.Behaviors.Find<ServiceMetadataBehavior>();

  15:     if (null == serviceMetadata)

  16:     {

  17:         serviceMetadata = new ServiceMetadataBehavior();

  18:         host.Description.Behaviors.Add(serviceMetadata);

  19:     }

  20:     serviceMetadata.HttpGetEnabled = true;

  21:     serviceMetadata.HttpsGetEnabled = true;

  22:     host.Open();

23:

  24:     Console.WriteLine("ServiceDebugBehavior");

  25:     Console.WriteLine("\t{0, -20}: {1}", "HttpHelpPageEnabled", serviceDebug.HttpHelpPageEnabled);

  26:     Console.WriteLine("\t{0, -20}: {1}\n", "HttpsHelpPageEnabled", serviceDebug.HttpsHelpPageEnabled);

27:

  28:     Console.WriteLine("ServiceMetadataBehavior");

  29:     Console.WriteLine("\t{0, -20}: {1}", "HttpGetEnabled", serviceMetadata.HttpGetEnabled);

  30:     Console.WriteLine("\t{0, -20}: {1}", "HttpsGetEnabled", serviceMetadata.HttpsGetEnabled);

  31: }

在如上所示的代码片断中，我们分别将服务行为ServiceDebugBehavior和ServiceMetadataBehavior应用在寄宿服务上，并将其HttpHelpPageEnabled/HttpsHelpPageEnabled和HttpGetEnabled/HttpsGetEnabled属性设置为True。在开启WebServiceHost之后我们将两个服务行为的这4个属性打印出来。从如下所示的输出结果我们可以看出这四个属性最终被设置成了False。

   1: ServiceDebugBehavior

   2:     HttpHelpPageEnabled : False

   3:     HttpsHelpPageEnabled: False

4:

   5: ServiceMetadataBehavior

   6:     HttpGetEnabled      : False

   7:     HttpsGetEnabled     : False

二、添加标准终结点

终结点是由地址、绑定和契约三要素构成，所谓标准终结点，就是基于典型的通信场景选择组成终结点的要素（主要是绑定和契约）进而创建出一个标准的终结点。如果我们在使用WebServiceHost进行服务寄宿的时候指定一个基地址，在没有添加任何终结点的情况下WebServiceHost会在开启过程中自动添加一个类型（Kind）为webHttpEndpoint 的标准终结点。我们同样可以通过实例演示来证实这一点。

   1: Uri baseAddress = new Uri("http://127.0.0.1:3721/employees");

   2: using (WebServiceHost host =

   3:     new WebServiceHost(typeof(EmployeesService), baseAddress))

   4: {

   5:     host.Open();

   6:     ServiceEndpoint endpoinit = host.Description.Endpoints[0];

   7:     Console.WriteLine("{0,-8}: {1}", "Address", endpoinit.Address);

   8:     Console.WriteLine("{0,-8}: {1}", "Binding", endpoinit.Binding);

   9:     Console.WriteLine("{0,-8}: {1}", "Contract", endpoinit.Contract.ContractType);

  10: }

在没有提供任何配置的情况下，我们通过如上的代码借助于WebServiceHost进行服务寄宿。在基于服务类型创建的WebServiceHost中指定了一个基地址，并在开启WebServiceHost之后，我们获取第一个终结点并将其三要素打印出来。从如下所示的输出结果我们可以看出：WebServiceHost基于服务类型实现的契约接口IEmployees创建了一个终结点，该终结点采用指定的基地址作为其地址，绑定类型为WebHttpBinding。

   1: Address : http://127.0.0.1:3721/employees

   2: Binding : System.ServiceModel.WebHttpBinding

   3: Contract: Artech.WcfServices.Service.Interface.IEmployees

三、添加WebHttpBehavior终结点行为

正如上面所说，WebServiceHost除了完成从ServiceHost继承下来的服务寄宿功能之外，其只要的职责就是将WebHttpBehavior行为应用到寄宿服务的所有终结点上。也就是说，当我们开启WebServiceHost的时候，如果终结点没有应用WebHttpBehavior行为，会自动创建一个新的WebHttpBehavior对象应用到终结点上。WebHttpBehavior的自动添加可以通过如下代码中的调试断言来体现。

   1: using (WebServiceHost host = new WebServiceHost(typeof(EmployeesService)))

   2: {

   3:     foreach (ServiceEndpoint endpoint in host.Description.Endpoints)

   4:     {

   5:         WebHttpBehavior behavior = endpoint.Behaviors.Find<WebHttpBehavior>();

   6:         if (null != behavior)

   7:         {

   8:             endpoint.Behaviors.Remove(behavior);

   9:         }

  10:     }

  11:     host.Open();

  12:     foreach (ServiceEndpoint endpoint in host.Description.Endpoints)

  13:     {

  14:         Debug.Assert(null != endpoint.Behaviors.Find<WebHttpBehavior>());

  15:     }

  16: }

本文链接

[WCF REST] 帮助页面与自动消息格式(JSON/XML)选择

2012-02-07T00:37:00Z

可以说WebHttpBinding和WebHttpBehavior是整个Web HTTP编程模型最为核心的两个类型，前者主要解决消息编码问题，而余下的工作基本上落在了终结点行为WebHttpBehavior上。WebHttpBehavior属性HelpEnabled和AutomaticFormatSelectionEnabled是“帮助页面”与“自动消息格式选择”这两个特性的总开关。[“自动消息格式(JSON/XML)选择”源代码从这里下载]

   1: public class WebHttpBehavior : IEndpointBehavior, ...

   2: {

   3:     //其他成员

   4:     public virtual bool HelpEnabled { get; set; }

   5:     public virtual bool AutomaticFormatSelectionEnabled { get; set; }

   6: }

一、帮助页面

WCF 4.0为REST服务提供了帮助页面功能，我们可以通过浏览器访问服务帮助页面的地址得到所有操作的基本信息。但是这个功能在默认的情况下是关闭的，我们需要通过应用在终结点上的WebHttpBehavior行为的HelpEnabled属性开启该功能。

   1: <configuration>

   2:     <system.serviceModel>

   3:         <behaviors>

   4:             <endpointBehaviors>

   5:                <behavior>

   6:                    <webHttp helpEnabled="true" />

   7:                </behavior>

   8:             </endpointBehaviors>

   9:         </behaviors>

  10:         <services>

  11:             <service name="Artech.WcfServices.Service.EmployeesService">

  12:                 <endpoint address="http://127.0.0.1:3721/employees"

  13:                           binding="webHttpBinding"

  14:                           contract="Artech.WcfServices.Service.Interface.IEmployees"/>

  15:             </service>

  16:         </services>

  17:     </system.serviceModel>

  18: </configuration>

同样以之前演示的EmployeesService为例，我们通过如上的配置将终结点行为WebHttpHehavior应用在服务唯一的终结点上（默认终结点），并将HelpEnabled属性设置为True。那么基于终结点的帮助页面将以地址{终结点地址}/Help发布出来，我们通过浏览器访问这个地址就会得到如下图所示帮助页面。

如上图所示，帮助页面列出了包括相对地址、HTTP方法和基本描述在内的所有操作的基本信息。我们通过点击HTTP方法对应的链接可以获得包括基于相应格式（Xml和Json）消息结构（Schema）和实例。在默认的情况下，帮助页面中表示操作描述信息的格式为“Service at {操作地址}”，我们可以在定义服务契约的时候再操作方法上应用特性DescriptionAttribute来定义出现在帮助页面中的描述信息。

   1: [ServiceContract]

   2: public interface IEmployees

   3: {

   4:     [WebGet(UriTemplate = "all")]

   5:     [Description("获取所有员工列表")]

   6:     IEnumerable<Employee> GetAll();

7:

   8:     [WebGet(UriTemplate = "{id}")]

   9:     [Description("获取指定ID的员工")]

  10:     Employee Get(string id);

11:

  12:     [WebInvoke(UriTemplate = "/", Method = "POST")]

  13:     [Description("创建一个新的员工")]

  14:     Employee Create(Employee employee);

15:

  16:     [WebInvoke(UriTemplate = "/", Method = "PUT")]

  17:     [Description("修改现有员工信息")]

  18:     void Update(Employee employee);

19:

  20:     [WebInvoke(UriTemplate = "{id}", Method = "DELETE")]

  21:     [Description("删除指定ID的员工")]

  22:     void Delete(string id);

  23: }

如上面的代码片断所示，我们在契约接口IEmployees中的所有操作方法上应用了DescriptionAttribute特性并指定了相应的描述信息。这些描述信息就是出现在如下图所示的帮助页面中。

二、自动消息格式选择

REST服务具有两种基本的消息格式（Xml和Json）。在定义服务契约的时候，我们可以通过应用在操作方法上的WebGetAttribute和WebInvokeAttribute指定回复消息的格式。如果没有通过这种方式对消息格式进行显式设置，我们还可以通过终结点行为WebHttpBehavior为回复消息设置一个默认的消息格式。除了这种显示设置方式之外，WCF还提供一种自动消息格式选择机制。

所谓消息格式的自动选择，就是服务根据请求消息来选择一种适合的格式进行消息的序列化。在默认的情况下，这种自动选择机制是关闭的，我们需要通过WebHttpBehavior的AutomaticFormatSelectionEnabled属性开启该机制。具体的消息格式选择机制策略（顺序）如下：

如果作为请求的HTTP消息具有Accept报头，则根据该报头决定回复消息的格式；
如果作为请求的HTTP消息具有Content-Type报头，则根据该报头决定回复消息的格式；
如果在定义服务契约时通过WebGetAttribute或者WebInvokeAttribute对回复消息的格式进行了显式设置，则采用该消息格式；
如果通过终结点行为WebHttpBehavior设置了对回复消息的格式进行了显式设置，则采用该消息格式；
采用默认消息格式Xml（WebMessageFormat枚举的默认值）。

我们同样通过之前创建的EmployeesService的实例来演示消息格式的自动选择机制。如下面的配置片断所示，我们将WebHttpBehavior行为应用到了寄宿服务的唯一终结点上，并且将AutomaticFormatSelectionEnabled属性设置为True。

   1: <configuration>

   2:     <system.serviceModel>

   3:         <behaviors>

   4:             <endpointBehaviors>

   5:                 <behavior name="webHttp">

   6:                     <webHttp automaticFormatSelectionEnabled="true" />

   7:                 </behavior>

   8:             </endpointBehaviors>

   9:         </behaviors>

  10:     <services>

  11:         <service name="Artech.WcfServices.Service.EmployeesService">

  12:             <endpoint address="http://127.0.0.1:3721/employees"

  13:                       behaviorConfiguration="webHttp"

  14:                       binding="webHttpBinding"

  15:                       contract="Artech.WcfServices.Service.Interface.IEmployees"/>

  16:             </service>

  17:         </services>

  18:     </system.serviceModel>

  19: </configuration>

对于契约接口IEmployees来说，我们通过WebGetAttribute特性用于返回所有员工列表的GetAll操作的回复消息格式设置为Xml。

   1: [ServiceContract]

   2: public interface IEmployees

   3: {

   4:     //其他成员

   5:     [WebGet(UriTemplate = "all",ResponseFormat = WebMessageFormat.Xml)]

   6:     IEnumerable<Employee> GetAll();

   7: }

对于REST服务调用来说，其本质就是一种普通的HTTP请求，与针对某个网页的访问并没有什么本质的不同，所以我们完全可以手工生成HTTP请求来进行服务的访问。为此我们创建了如下一个静态方法GetAllEmployees方法通过WebClient对服务的GetAll操作进行调用，并将整个回复消息打印出来，该方法的两个参数分别是作为请求的HTTP消息的Content-Type和Accept报头值。

   1: static void GetAllEmployees(string contentType, string accept)

   2: {

   3:     WebClient webClient = new WebClient();

   4:     if (!string.IsNullOrEmpty(contentType))

   5:     {

   6:         webClient.Headers.Add("Content-Type", contentType);

   7:     }

8:

   9:     if (!string.IsNullOrEmpty(accept))

  10:     {

  11:         webClient.Headers.Add("Accept", accept);

  12:     }

  13:     using (StreamReader reader = new StreamReader(webClient.OpenRead(

  14:         "http://127.0.0.1:3721/employees/all")))

  15:     {

  16:         Console.WriteLine(reader.ReadToEnd());

  17:     }

  18: }

然后我们通过调用GetAllEmployees方法进行三次服务调用。第一次调用既没有指定Content-Type报头也没有指定Accept报头，第二次和第三次调用在分别将这两个报头指定为“application/json”。

   1: string contentType = "application/json";

2:

   3: Console.WriteLine("Content-Type = N/A; Accept = N/A:");

   4: GetAllEmployees("", "");

   5: Console.WriteLine();

6:

   7: Console.WriteLine("Content-Type = application/json; Accept = N/A:");

   8: GetAllEmployees(contentType, "");

   9: Console.WriteLine();

10:

  11: Console.WriteLine("Content-Type = N/A, Accept = application/json:");

  12: GetAllEmployees("", contentType);

从如下所示的输出结果我们可以看出：由于服务调用请求没有指定任何媒体类型相关的报头，所以回复消息采用的是契约接口中设置的消息格式Xml。对于后两次服务调用中，由于请求消息中分别通过Content-Type和Accept报头将“期望”的媒体类型设置为application/json，所以Json最终作为回复消息的格式。（S1006）

   1: Content-Type = N/A; Accept = N/A:

   2: <ArrayOfEmployee xmlns="http://www.artech.com/" xmlns:i="http://www.w3.org/2001/

   3: XMLSchema-instance"><Employee><Department>开发部</Department><Grade>G7</Grade><I

   4: d>001</Id><Name>张三</Name></Employee><Employee><Department>人事部</Department><

   5: Grade>G6</Grade><Id>002</Id><Name>李四</Name></Employee></ArrayOfEmployee>

6:

   7: Content-Type = application/json; Accept = N/A:

   8: [{"Department":"开发部","Grade":"G7","Id":"001","Name":"张三"},{"Department":"人

   9: 事部","Grade":"G6","Id":"002","Name":"李四"}]

10:

  11: Content-Type = N/A, Accept = application/json:

  12: [{"Department":"开发部","Grade":"G7","Id":"001","Name":"张三"},{"Department":"人

  13: 事部","Grade":"G6","Id":"002","Name":"李四"}]

本文链接

[WCF REST] Web消息主体风格（Message Body Style）

2012-02-06T00:52:00Z

对于Web HTTP编程模型来说，服务契约中作为操作的方法无须应用OperationContractAttribute特性，只需要根据需要应用WebGetAttribute与WebInvokeAttribute特性即可。前者针对GET HTTP方法，或者则针对其他HTTP方法。WebGetAttribute与WebInvokeAttribute的属性BodyStyle和IsBodyStyleSetExplicitly涉及到“Web消息主体风格”的话题。

   1: [AttributeUsage(AttributeTargets.Method)]

   2: public sealed class WebGetAttribute : Attribute, IOperationBehavior

   3: {

   4:     //其他成员

   5:     public WebMessageBodyStyle BodyStyle { get; set; }

   6: }

7:

   8: [AttributeUsage(AttributeTargets.Method)]

   9: public sealed class WebInvokeAttribute : Attribute, IOperationBehavior

  10: {

  11:     //其他成员

  12:     public WebMessageBodyStyle BodyStyle { get; set; }

  13: }

至于消息主体的风格通过具有如下定义的枚举WebMessageBodyStyle表示。

   1: public enum WebMessageBodyStyle

   2: {

   3:     Bare,

   4:     Wrapped,

   5:     WrappedRequest,

   6:     WrappedResponse

   7: }

我们知道请求消息和回复消息分别是对操作方法输入参数和返回值（输出参数和引用参数）的封装，WebMessageBodyStyle中的Bare表示请求消息和回复消息的主体部分仅仅包含针对输入参数和返回值（输出参数和引用参数）序列化后的内容，而Wrapped则会在外面包装一个基于当前操作的“封套”。枚举项WrappedRequest和WrappedResponse用于单独针对请求消息和回复消息的主体进行封装。

WebGetAttribute与WebInvokeAttribute的属性BodyStyle的默认值为Bare。如果该属性被设置成WrappedRequest，则回复消息主体依然采用Bare风格；如果该属性被设置成WrappedResponse，则请求消息主体依然采用Bare风格。布尔类型的只读属性IsBodyStyleSetExplicitly表示是否针对属性BodyStyle进行了显示设置。

目录
一、Xml+Bare
二、Xml+Wrapped
三、JSON+Bare
四、JSON+Wrapped
五、Bare请求消息风格对单一输入的限制
六、Bare回复消息风格对单一输出的限制

一、Xml + Bare

我们通过之前演示的实例来看看针对不同的消息格式（XML和JSON），请求消息和回复消息的主体在采用不同风格的情况下具有怎样的结构。现在我们对应用在契约接口IEmployees中的Create操作方法上的WebInvokeAttribute进行了如下的修改，即显式地指定了请求消息和回复消息的格式（XML）和主体风格（Bare）。同时也将返回类型从void编程了Employee，并直接将创建的Employee对象返回。

   1: [ServiceContract]

   2: public interface IEmployees

   3: {

   4:     //其他成员

   5:     [WebInvoke(UriTemplate = "/", Method = "POST",

   6:     RequestFormat = WebMessageFormat.Xml,

   7:     ResponseFormat = WebMessageFormat.Xml,

   8:     BodyStyle = WebMessageBodyStyle.Bare)]

   9:     Employee Create(Employee employee);

  10: }

11:

  12: public class EmployeesService : IEmployees

  13: {

  14:     //其他成员

  15:     public Employee Create(Employee employee)

  16:     {

  17:         employees.Add(employee);

  18:         return employee;

  19:     }

  20: }

我们针对如下所示的代码通过服务调用添加一个姓名为“王五”的员工。

   1: using (ChannelFactory<IEmployees> channelFactory = new ChannelFactory<IEmployees>("employeeService"))

   2: {

   3:     IEmployees proxy = channelFactory.CreateChannel();

   4:     proxy.Create(new Employee

   5:     {

   6:         Id         = "003",

   7:         Name       = "王五",

   8:          Grade     = "G9",

   9:         Department = "行政部"

  10:     });

  11: }

针对如上所示的服务调用，由于消息格式和主体风格分别为Xml和Bare，所以作为请求消息和回复消息的主体仅仅是Employee对象被序列化后生成的XML片断，具体内容如下所示。

   1: 请求消息主体：

   2: <Employee xmlns="http://www.artech.com/"

   3:   xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

   4:   <Department>行政部</Department>

   5:   <Grade>G9</Grade>

   6:   <Id>003</Id>

   7:   <Name>王五</Name>

   8: </Employee>

9:

  10: 回复消息主体：

  11: <Employee xmlns="http://www.artech.com/"

  12:   xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

  13:   <Department>行政部</Department>

  14:   <Grade>G9</Grade>

  15:   <Id>003</Id>

  16:   <Name>王五</Name>

  17: </Employee>

二、Xml + Wrapped

现在我们对契约接口略加修改，将应用在操作方法Create上的WebInvokeAttribute特性的属性BodyStyle设置为Wrapped。

   1: [ServiceContract]

   2: public interface IEmployees

   3: {

   4:     //其他成员

   5:     [WebInvoke(UriTemplate = "/", Method = "POST",

   6:     RequestFormat = WebMessageFormat.Xml,

   7:     ResponseFormat = WebMessageFormat.Xml,

   8:     BodyStyle = WebMessageBodyStyle.Wrapped)]

   9:     Employee Create(Employee employee);

  10: }

针对相同的服务调用，请求消息和回复消息将具有如下所示的主体内容。我们可以看出Employee被序列化后生成的XML在请求消息中作为<Create>元素的子元素；对于回复消息来说，Employee被序列化后生成的XML的根元素名称为CreateResult，而不是<Employee>，而整个<CreateResult>内嵌于< CreateResponse >元素中。

   1: 请求消息主体：

   2: <Create xmlns="http://tempuri.org/">

   3:   <employee xmlns:a="http://www.artech.com/"

   4:         xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

   5:     <a:Department>行政部</a:Department>

   6:     <a:Grade>G9</a:Grade>

   7:     <a:Id>003</a:Id>

   8:     <a:Name>王五</a:Name>

   9:   </employee>

  10: </Create>

11:

  12: 回复消息主体：

  13: <CreateResponse xmlns="http://tempuri.org/">

  14:   <CreateResult xmlns:a="http://www.artech.com/"

  15:         xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

  16:     <a:Department>行政部</a:Department>

  17:     <a:Grade>G9</a:Grade>

  18:     <a:Id>003</a:Id>

  19:     <a:Name>王五</a:Name>

  20:   </CreateResult>

  21: </CreateResponse>

三、JSON+ Bare

上面我们通过实例演示了消息格式为Xml情况下针对不同风格的消息主体的内容差异，现在我们按照相同的方式来讨论当消息格式为JSON的时候，针对不同风格的消息主体在结构上又具有怎样差异。如下面的代码片断所示，我们通过对契约接口的修改将服务操作Create的消息格式和主体风格设置成Json和Bare。

   1: [ServiceContract]

   2: public interface IEmployees

   3: {

   4:     //其他成员

   5:     [WebInvoke(UriTemplate = "/", Method = "POST",

   6:     RequestFormat = WebMessageFormat.Json,

   7:     ResponseFormat = WebMessageFormat.Json,

   8:     BodyStyle = WebMessageBodyStyle.Bare)]

   9:     Employee Create(Employee employee);

  10: }

同样针对之前的服务调用，以JSON形式表示的Employee对象将直接作为请求消息和回复消息的主体部分，具体的内容如下所示。（S1004）

   1: 请求消息主体：

   2: {"Department":"行政部","Grade":"G9","Id":"003","Name":"王五"}

3:

   4: 回复消息主体：

   5: {"Department":"行政部","Grade":"G9","Id":"003","Name":"王五"}

四、JSON+ Wrapped

我们最后来演示Json消息格式在Wrapped风格下具有怎样的结构，为此我们只需要将应用在Create操作方法上的WebInvokeAttribute特性的BodyStyle属性设置为Wrapped。

   1: [ServiceContract]

   2: public interface IEmployees

   3: {

   4:     //其他成员

   5:     [WebInvoke(UriTemplate = "/", Method = "POST",

   6:     RequestFormat = WebMessageFormat.Json,

   7:     ResponseFormat = WebMessageFormat.Json,

   8:     BodyStyle = WebMessageBodyStyle.Wrapped)]

   9:     Employee Create(Employee employee);

  10: }

如下面的代码所示，由于请求消息和回复消息采用Wrapped风格，表示Employee的JSON对象最终作为最终JSON对象的“employee”属性和“CreateResult”属性。（S1005）

   1: 请求消息主体：

   2: {"employee":{"Department":"行政部","Grade":"G9","Id":"003","Name":"王五"}}

3:

   4: 回复消息主体：

   5: {"CreateResult":{"Department":"行政部","Grade":"G9","Id":"003","Name":"王五"}}

五、Bare请求消息风格对单一输入的要求

对于Bare消息主体风格来说，意味着对象被序列化后生成的XML或者JSON表示直接作为消息的主体，所以只适用于单一对象。具体来说，只有具有唯一输入参数的操作方法才能将请求消息的主题风格设置为Bare。

   1: [ServiceContract(Namespace = "http://www.artech.com/")]

   2: public interface ICalculator

   3: {

   4:     [WebInvoke(BodyStyle = WebMessageBodyStyle.Bare)]

   5:     double Add( double x,  double y);

   6: }

如上所示的是我们熟悉的计算服务的契约接口的定义。消息主体风格为Bare的操作方法Create具有两个输入参数（x和y），在对实现了该契约接口进行寄宿的时候就会抛出如下图所示的InvalidOperationException异常，提示“约定“ICalculator”的操作‘Add’指定要序列化多个请求正文参数，但没有任何包装元素。如果没有包装元素，至多可序列化一个正文参数。请删除多余的正文参数，或将 WebGetAttribute/WebInvokeAttribute 的 BodyStyle 属性设置为 Wrapped”。

六、Bare回复消息风格对单一输出的要求

由于回复参数是对返回值、引用参数和输出参数的封装，所以当操作方法具有引用参数或者输出参数时不能将回复消息的主体风格设置为Bare。

   1: [ServiceContract(Namespace = "http://www.artech.com/")]

   2: public interface ICalculator

   3: {

   4:     [WebInvoke(BodyStyle = WebMessageBodyStyle.WrappedRequest)]

   5:     void Add( double x,  double y, out double result);

   6: }

同样以计算服务契约为例，现在我们通过如上的方式以输出参数的形式返回加法运算的结果，并将应用在操作方法上的WebInvokeAttribute特性的BodyStyle属性设置为WrappedRequest，这意味着请求消息和回复消息分别采用Wrapped和Bare风格。当我们对实现了该契约接口的服务设施寄宿时会抛出下图所示的InvalidOperationException异常，并提示“约定‘ICalculator’的操作‘Add’至少指定一个响应正文参数不是操作的返回值。当 WebGetAttribute/WebInvokeAttribute 的 BodyStyle 属性设置为 Bare 时，只允许使用返回值。请删除多余的响应正文参数或将 BodyStyle 属性设置为 Wrapped”。

本文链接

[WCF REST] Web HTTP编程模型——WebHttpBinding

2012-02-05T01:36:00Z

不论是我们采用SOAP还是REST架构风格，运行时框架体系依然不曾改变，终结点也仍旧是通信的核心。在Web HTTP编程模型中，我们采用基于WebHttpBinding绑定的终结点。绑定是一组相关绑定元素的有序组合，绑定的特性与能力决定于它包含的绑定元素，在这里我们通过分析绑定元素的方式来剖析WebHttpBinding绑定与其它绑定有何不同。采用HTTP/HTTPS通信协议的WebHttpBinding具有一些与WSHttpBinding/WS2007HttpBinding相同的属性，在这里我们只关心如下定义的Security属性。

   1: public class WebHttpBinding : Binding, IBindingRuntimePreferences

   2: {

   3:     //其它成员

   4:     public WebHttpSecurity Security { get; }

   5: }

   6: public sealed class WebHttpSecurity

   7: {

   8:     // 其它成员

   9:     public WebHttpSecurityMode Mode { get; set; }

  10:     public HttpTransportSecurity Transport { get; }

  11: }

  12: public enum WebHttpSecurityMode

  13: {

  14:     None,

  15:     Transport,

  16:     TransportCredentialOnly

  17: }

基于SOAP的绑定一般具有两种基本的安全模式，即Message和Transport模式。对于前者，它是完全建立在WS-Security为核心的安全协议之上的，而整个WS-*协议簇都是基于SOAP的，所以自然不能应用在WebHttpBinding上，所以它只能通过HTTPS提供针对Transport模式的安全支持。具体来说，通过枚举WebHttpSecurityMode表示的安全模式具有如下三个选项：

None：HTTP 请求未使用任何安全性；
Transport：HTTP 请求使用传输级安全性；
TransportCredentialOnly：仅提供基于 HTTP 的客户端身份验证。

一、WebHttpBinding的绑定元素

现在我们根据上述三种不同的安全模式创建相应的WebHttpBinding对象，然后通过如下的程序在控制台中答应出所有的绑定元素类型。

   1: static void Main(string[] args)

   2: {

   3:     WebHttpBinding binding = new WebHttpBinding(WebHttpSecurityMode.None);

   4:     ListBindingElements(binding);

5:

   6:     binding = new WebHttpBinding(WebHttpSecurityMode.Transport);

   7:     ListBindingElements(binding);

8:

   9:     binding = new WebHttpBinding(WebHttpSecurityMode.TransportCredentialOnly);

  10:     ListBindingElements(binding);

  11: }

  12: static void ListBindingElements(WebHttpBinding binding)

  13: {

  14:     int index = 1;

  15:     Console.WriteLine(binding.Security.Mode + ":");

  16:     foreach (var element in binding.CreateBindingElements())

  17:     {

  18:         Console.WriteLine("{0}. {1}", index++, element.GetType().FullName);

  19:     }

  20:     Console.WriteLine();

  21: }

上述的程序执行之后会在控制台上产生如下的输出，从中我们不难看出三个WebHttpBinding均由一个消息编码元素和传输元素组成，我们知道这两种绑定元素最所有类型的绑定所必需的。

   1: None：

   2: 1. System.ServiceModel.Channels.WebMessageEncodingBindingElement

   3: 2. System.ServiceModel.Channels.HttpTransportBindingElement

4:

   5: Transport：

   6: 1. System.ServiceModel.Channels.WebMessageEncodingBindingElement

   7: 2. System.ServiceModel.Channels.HttpsTransportBindingElement

8:

   9: TransportCredentialOnly：

  10: 1. System.ServiceModel.Channels.WebMessageEncodingBindingElement

  11: 2. System.ServiceModel.Channels.HttpTransportBindingElement

对于WebHttpBinding的两个绑定元素来说，由于它通过HTTPS提供针对Transport安全的支持，所以当安全模式为Transport时对应的传输绑定元素为HttpsTransportBindingElement，对于其余两种安全模式则直接采用HttpTransportBindingElement作为传输绑定元素。现在我们着重讨论是作为消息编码绑定元素的WebMessageEncodingBindingElement类型，以及它涉及的消息编码机制。

二、消息编码

我们先来看看WebMessageEncodingBindingElement的基本的定义。如下面的代码片断所示，它是MessageEncodingBindingElement的子类，并且具有与TextMessageEncodingElement类似的属性定义。其中MaxReadPoolSize和MaxWritePoolSize表示表示无需分配新的XmlDictionaryReader/XmlDictionaryWriter便可以读取的便可同时读取/写入的最大消息数，默认值分别是64和16。ReaderQuotas属性返回用于约束读取的XML的复杂度的XmlDictionaryReaderQuotas对象，而WriteEncoding属性表示采用的字符编码类型，默认采用UTF-8编码方式。由于WebHttpBinding不使用SOAP，表示消息版本的MessageVersion属性自然返回None，如果我们对该属性进行设置，指定的属性值也只能是MessageVersion.None。

   1: public sealed class WebMessageEncodingBindingElement : MessageEncodingBindingElement,...

   2: {

   3:     //其它成员

   4:     public override MessageEncoderFactory CreateMessageEncoderFactory();

5:

   6:     public bool CrossDomainScriptAccessEnabled {get; set; }

   7:     public WebContentTypeMapper ContentTypeMapper { get; set; }

8:

   9:     public int MaxReadPoolSize { get; set; }

  10:     public int MaxWritePoolSize { get; set; }

  11:     public override MessageVersion MessageVersion { get; set; }

  12:     public XmlDictionaryReaderQuotas ReaderQuotas { get; }

  13:     public Encoding WriteEncoding { get; set; }

  14: }

除此之外，WebMessageEncodingBindingElement具有CrossDomainScriptAccessEnabled 和ContentTypeMapper这两个重要的属性。前者表示是否支持跨域（Corss-Domain）脚本访问，默认值为False。后者类型为WebContentTypeMapper。WebContentTypeMapper用于进行消息的内容类型（Content Type，有时候也成为媒体类型或者MIME类型）与具体的格式（比如XML、JSON等）之间的映射。

   1: public abstract class WebContentTypeMapper

   2: {

   3:     protected WebContentTypeMapper();

   4:     public abstract WebContentFormat GetMessageFormatForContentType(string contentType);

   6: }

   7: public enum WebContentFormat

   8: {

   9:     Default,

  10:     Xml,

  11:     Json,

  12:     Raw

  13: }

如上面的代码所示，WebContentTypeMapper是一个抽象类，包含的唯一的抽象方法GetMessageFormatForContentType用于根据指定的内容类型返回与之匹配的通过枚举WebContentFormat表示的内容格式。WebContentFormat枚举的Xml、JSON和Raw体现了Web HTTP编程模型支持三种基本格式，其中Raw表示原始的二进制。

最终的消息编码/解码工作是通过继承自MessageEncoder的消息编码器实现的，消息编码器又是通过继承自MessageEncoderFactory的编码器工厂创建出来的，而消息编码绑定元素最终通过方法CreateMessageEncoderFactory创建了编码器工厂。对于WebMessageEncodingBindingElement来说，它的CreateMessageEncoderFactory方法会创建一个具有如下定义的WebMessageEncoderFactory对象。

   1: internal class WebMessageEncoderFactory : MessageEncoderFactory

   2: {

   3:     public WebMessageEncoderFactory(Encoding writeEncoding, int maxReadPoolSize,int maxWritePoolSize, XmlDictionaryReaderQuotas quotas,

   4:         WebContentTypeMapper contentTypeMapper, bool javascriptCallbackEnabled);

   5:     public override MessageEncoder Encoder { get; }

   6:     public override MessageVersion MessageVersion { get; }

   7: }

8:

WebMessageEncoderFactory是一个继承自MessageEncoderFactory的内部类型。除了布尔类型的参数javascriptCallbackEnabled对应着WebMessageEncodingBindingElement的属性CrossDomainScriptAccessEnabled之外，WebMessageEncoderFactory的构造函数参数与WebMessageEncodingBindingElement的同名属性一一对应。代表消息版本的MessageVersion属性依然返回None，而真正用于最终消息编码/解码工作的是通过Encoder属性返回的具有如下定义的WebMessageEncoder对象。

   1: internal class WebMessageEncoderFactory : MessageEncoderFactory

   2: {

   3:     private class WebMessageEncoder : MessageEncoder

   4:     {

   5:         //其他成员

   6:         private MessageEncoder TextMessageEncoder { get; }

   7:         private MessageEncoder JsonMessageEncoder { get; }

   8:         private MessageEncoder RawMessageEncoder { get; }

   9:     }

  10: }

如上面的代码片断所示，WebMessageEncoder实际上是内嵌于WebMessageEncoderFactory类型中继承自MessageEncoder的内部类型。WebMessageEncoder本身并不真正地实施消息的编码/解码，最终的消息编码/解码工作是通过三个属性TextMessageEncoder、JsonMessageEncoder和RawMessageEncoder体现的具体消息编码器完成的，而它们又分别对应着通过WebContentFormat枚举表示的三种内容类型Xml、JSON和Raw。

本文链接