WCF4.0 –- RESTful WCF Services (1)
(入门)
WCF 很好的支持了 REST 的开发, 而 RESTful 的服务通常是架构层面上的考虑。
因为它天生就具有很好的跨平台跨语言的集成能力,几乎所有的语言和网络平台都支持 HTTP 请求,无需去实现复杂的客户端代理,无需使用复杂的数据通讯方式既可以将我们的服务暴露给任何需要的人,无论他使用
VB、Ruby、JavaScript,甚至是 HTML FORM,或者直接在浏览器地址栏输入。
WCF 中通过 WebGetAttribute、WebInvokeAttribute
(GET/PUT/POST/DELETE)、UriTemplate 定义 REST 的服务的调用方式,
通过 WebMessageFormat (Xml/Json) 定义消息传递的格式。
1. 契约
using System;
2.using System.Collections.Generic;
3.using System.Runtime.Serialization;
4.using System.ServiceModel;
5.using System.ServiceModel.Web;
6.
7.namespace WcfRESTfulSvc1
8.{
9. [ServiceContract]
10. public interface ITaskService
11. {
12. [OperationContract]
13. [WebGet(UriTemplate="Tasks/Xml", ResponseFormat=WebMessageFormat.Xml)]
14. List GetTasksXml();
15.
16. [OperationContract]
17. [WebGet(UriTemplate = "Tasks/Json", ResponseFormat = WebMessageFormat.Json)]
18. List GetTasksJson();
19.
20. [OperationContract]
21. [WebInvoke(UriTemplate="Task/{title}", Method="GET", ResponseFormat=WebMessageFormat.Json)]
22. Task GetTasksByTitle(string title);
23. }
24.
25.
26. [DataContract]
27. public class Task
28. {
29. [DataMember]
30. public string Title { get; set; }
31. [DataMember]
32. public string Detail { get; set; }
33. [DataMember]
34. public DateTime CreatedDate { get; set; }
35. }
36.}
|
2. 实现
using System;
2.using System.Collections.Generic;
3.using System.Linq;
4.
5.namespace WcfRESTfulSvc1
6.{
7. public class TaskService : ITaskService
8. {
9. public List GetTasksXml()
10. {
11. return GetData();
12. }
13.
14. public List GetTasksJson()
15. {
16. return GetData();
17. }
18.
19. public Task GetTasksByTitle(string title)
20. {
21. return GetData().Where(t => t.Title == title).FirstOrDefault();
22. }
23.
24. private static List GetData()
25. {
26. return new List
27. {
28. new Task { Title="Task1", Detail="Do Something 1", CreatedDate=DateTime.Now },
29. new Task { Title="Task2", Detail="Do Something 2", CreatedDate=DateTime.Now },
30. new Task { Title="Task3", Detail="Do Something 3", CreatedDate=DateTime.Now },
31. new Task { Title="Task4", Detail="Do Something 4", CreatedDate=DateTime.Now },
32. new Task { Title="Task5", Detail="Do Something 5", CreatedDate=DateTime.Now },
33. };
34. }
35. }
36.}
|
通过 WCF 4.0 里创建的 WCF Service Application 发布REST服务很简单,只需要在
svc 的 Markup 里加上 Factory:
<%@ ServiceHost Language="C#" Debug="true"
Service="WcfRESTfulSvc1.TaskService" CodeBehind="TaskService.svc.cs"
Factory="System.ServiceModel.Activation.WebServiceHostFactory"%> |
BTW: 不过这样,WCF的Metadata就不能访问到了,也就说不能访问到svc的wsdl了。
OK,在浏览器中键入 http://localhost:2571/TaskService.svc/Tasks/Xml
就能得到结果:
<ArrayOfTask xmlns="http://schemas.datacontract.org/2004/07/WcfRESTfulSvc1"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 2. <Task> 3. <CreatedDate>2011-03-09T21:51:13.3376004+08:00</CreatedDate> 4. <Detail>Do Something 1</Detail> 5. <Title>Task1</Title> 6. </Task> 7. <Task> 8. <CreatedDate>2011-03-09T21:51:13.3376004+08:00</CreatedDate> 9. <Detail>Do Something 2</Detail> 10. <Title>Task2</Title> 11. </Task> 12. <Task> 13. <CreatedDate>2011-03-09T21:51:13.3376004+08:00</CreatedDate> 14. <Detail>Do Something 3</Detail> 15. <Title>Task3</Title> 16. </Task> 17. <Task> 18. <CreatedDate>2011-03-09T21:51:13.3376004+08:00</CreatedDate> 19. <Detail>Do Something 4</Detail> 20. <Title>Task4</Title> 21. </Task> 22. <Task> 23. <CreatedDate>2011-03-09T21:51:13.3376004+08:00</CreatedDate> 24. <Detail>Do Something 5</Detail> 25. <Title>Task5</Title> 26. </Task> 27.</ArrayOfTask>
|
客户端的调用利用System.Net.WebClient也很容易:
var client = new WebClient(); 2.this.txtResponse.Text = client.DownloadString(url);
|
Json的返回结果:
[{"CreatedDate":"//Date(1299687080328+0800)//","Detail":"Do Something 1","Title":"Task1"},
{"CreatedDate":"//Date(1299687080328+0800)//","Detail":"Do Something 2","Title":"Task2"},
{"CreatedDate":"//Date(1299687080328+0800)//","Detail":"Do Something 3","Title":"Task3"},
{"CreatedDate":"//Date(1299687080328+0800)//","Detail":"Do Something 4","Title":"Task4"},
{"CreatedDate":"//Date(1299687080328+0800)//","Detail":"Do Something 5","Title":"Task5"}]
|
再来看看利用jQuery如何调用这个服务:
<mce:script type="text/javascript" language="JavaScript"><!-- 2. $(document).ready(function () { 3. $("#btnGet").click(function () { 4. var url = $("#txtUrl").val(); 5. $.get(url, function (data) { 6. for (var i = 0; i < data.length; i++) 7. $("#divResponse").append("<li>" + 8. data[i].Title + " - " + 9. data[i].Detail + "</li>"); 10. }); 11. }); 12. }); 13.// --></mce:script>
|
WCF4.0 –- RESTful WCF Services (2)
(实现增,删,改,查)
RESTful服务就是为了实现一个易于整合的系统,可以跨平台跨语言的调用(如下图),【上篇】介绍了如何用WCF构建一个RESTful的服务。
本篇进一步通过一个实例记录如何实施一个具体的RESTful WCF服务以及客户端调用服务进行增,删,改,查。
WCF 4.0 其新功能之一就是 WCF 更容易以 REST API 来呈现,在 WCF 3.5 中的
WebGetAttribute 与 WebInvokeAttribute 中的 UriTemplate
参数原本不支持 REST URL 格式,为了 REST 功能,微软还特意发布了 WCF REST Starter
Kit 组件,让开发人员可以利用 WCF 3.5 开发真正 REST-based 的应用程序,由 URL
对应到指定的 Service Contract 中的 Operation Contract,在 WCF
4.0 中,WCF 的核心已经融入了 REST Starter Kit 中的 URL 引擎,在 WebGetAttribute
与 WebInvokeAttribute 已经可以支持 REST 的功能,Windows Azure 许多服务的
REST API 就是利用 WCF 来开发的。
主要涉及以下内容:
1. 如何通过 JSON 数据进行交互;
2. 如何进行服务端的错误处理,并在客户端区分不同的异常;
3. 如何利用 Microsoft.HttpClient (微软提供的第3方组件);
本次示例的工程:
PS: 上面虽然在一个solution里有两个工程,但是工程之前没有任何引用。完全靠Http消息传递。
1. 创建服务端工程:
通过VS2010的Extension Manager,可以下载一个“WCF REST Service
Template”。通过这个我们可以快速创建一个WCF REST服务。它是一个创建在Web Application工程里的服务。和前一篇介绍的WCF服务不同的是在Globel.asax中的Application_Start事件中注册服务。并且注册的"TaskService"自动成为服务的基地址,即
http://<machine_name>:<port>/TaskService/
public class Global : HttpApplication 2.{ 3. void Application_Start(object sender, EventArgs e) 4. { 5. RegisterRoutes(); 6. } 7. 8. private void RegisterRoutes() 9. { 10. RouteTable.Routes.Add(new ServiceRoute("TaskService", 11. new WebServiceHostFactory(), typeof(TaskService))); 12. } 13.}
|
2. 服务的实现:
服务端直接通过Linq2Entities操作DB,为了返回JSON的数据,参数和返回值都设计为POCO类。在Linq2Entities生成代码后,又拷贝了一份进行删减修改为POCO类。(现在有一个ADO.NET
POCO Generator 的t4模板,不知道能否简化我现在的做法...)
namespace WcfRestService2.Model 2.{ 3. [DataContract] 4. public class PocoTask 5. { 6. [DataMember] 7. public virtual int ID { get; set; } 8. [DataMember] 9. public virtual string Title { get; set; } 10. [DataMember] 11. public virtual string Detail { get; set; } 12. [DataMember] 13. public virtual int State { get; set; } 14. [DataMember] 15. public virtual DateTime UpdatedDate { get; set; } 16. } 17.}
|
REST中很好的利用了HTTP的GET/POST/PUT/DELETE方式,绑定到服务的不同方法上。比如GET方法不用客户端提供太多数据,正适合查询只提供主键或者查询字段的场景。POST则适合数据的插入,PUT则应用在数据更新,DELETE则直接用在数据删除上。当然通过URI的区别,也可以全部用POST或者PUT,只是语义符合调用场景的话,是的服务使用更易于理解和习惯。
服务端实现片段:
(1) 查询(Http/GET),这里定义了访问的UriTemplate,完整访问地址就是"基地址+UriTemplate",比如:
http://localhost:port/TaskService/Tasks/State/{state}
另外ResponseFormat设定为Json格式。
也可以在配置文件中,修改 <standardEndpoint> 节点的 defaultOutgoingResponseFormat
属性控制Response的格式。
[WebGet(UriTemplate = "Tasks/State/{state}", 2. ResponseFormat = WebMessageFormat.Json)] 3.public List<PocoTask> GetTasksByState(string state) 4.{ 5. using (var db = new TasksEntities()) 6. { 7. int s = Int32.Parse(state); 8. var query = db.Task.Where(t => t.State == s || -1 == s); 9. return GetPocoData(query); 10. } 11.}
|
(2) 新建(Http/POST),POST里的数据格式通过RequestFormat定义为Json,WCF框架接受到Json数据的请求,会自动反序列化成PocoTask实例。然后我又创建真正EF里的Entity实例,将PocoTask数据复制到Entity里,插入DB。
[WebInvoke(UriTemplate = "Tasks/Add", Method = "POST", 2. RequestFormat=WebMessageFormat.Json)] 3.public void Create(PocoTask pocoTask) 4.{ 5. var ctx = WebOperationContext.Current; 6. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.OK; 7. try 8. { 9. using (var db = new TasksEntities()) 10. { 11. var task = new Task(); 12. CopyValue(pocoTask, task); 13. task.UpdatedDate = DateTime.Now; 14. db.AddToTask(task); 15. db.SaveChanges(); 16. } 17. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.Created; 18. } 19. catch (Exception ex) 20. { 21. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.ExpectationFailed; 22. ctx.OutgoingResponse.StatusDescription = ex.Message; 23. } 24.}
|
(3) 更新(Http/PUT),先通过id查出Entity,再将客户端的数据更新到Entity上。
[WebInvoke(UriTemplate = "Tasks/{id}", Method = "PUT", 2. RequestFormat=WebMessageFormat.Json)] 3.public void Update(string id, PocoTask pocoTask) 4.{ 5. var ctx = WebOperationContext.Current; 6. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.OK; 7. try 8. { 9. using (var db = new TasksEntities()) 10. { 11. var nId = Convert.ToInt32(id); 12. var target = db.Task.SingleOrDefault(t => t.ID == nId); 13. target.Title = pocoTask.Title; 14. target.Detail = pocoTask.Title; 15. target.State = pocoTask.State; 16. target.UpdatedDate = DateTime.Now; 17. db.SaveChanges(); 18. } 19. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.Accepted; 20. } 21. catch (Exception ex) 22. { 23. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.ExpectationFailed; 24. ctx.OutgoingResponse.StatusDescription = ex.Message; 25. } 26.}
|
(4) 删除(Http/DELETE)
[WebInvoke(UriTemplate = "Tasks/{id}", Method = "DELETE")] 2.public void Delete(string id) 3.{ 4. var ctx = WebOperationContext.Current; 5. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.OK; 6. try 7. { 8. using (var db = new TasksEntities()) 9. { 10. var nId = Convert.ToInt32(id); 11. var task = db.Task.SingleOrDefault(t => t.ID == nId); 12. db.Task.DeleteObject(task); 13. db.SaveChanges(); 14. } 15. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.Accepted; 16. } 17. catch (Exception ex) 18. { 19. ctx.OutgoingResponse.StatusCode = System.Net.HttpStatusCode.ExpectationFailed; 20. ctx.OutgoingResponse.StatusDescription = ex.Message; 21. } 22.}
|
服务端的异常处理中通过 OutgoingResponse.StatusCode
返回不同的Code,这样客户端通过这些Code就知道服务端出现了什么错误。但是目前我还不知道OutgoingResponse.StatusDescription如何在客户端获得。如果可以的话,我们就可以知道错误的详细内容。
本示例中:
a) 查询成功 —— System.Net.HttpStatusCode.OK
(默认)
b) 创建成功 —— System.Net.HttpStatusCode.Created
c) 更新成功 —— System.Net.HttpStatusCode.Accepted
d) 删除成功 —— System.Net.HttpStatusCode.Accepted
System.Net.HttpStatusCode的枚举可以参看 MSDN:
http://msdn.microsoft.com/en-us/library/system.net.httpstatuscode.aspx。
3. 客户端实现:
因为REST 是基于HTTP的, 所以对于 REST 的客户端的开发者,无法像传统的
WebService或者其他的WCF服务通过引用wsdl,享受“奢侈”的代码生成,而使用强类型的本地代理调用服务。
开发者只能通过 Http Request 的组装, 但正因为这种直接的HttpRequest组装,而使得客户端真正是语言无关的。这里不得不提一下
Microsoft.Http.dll 和 Microsoft.Http.Extensions.dll,它们是微软提供的REST客户端包。可以更加方便地操作
HttpRequest/Response,你可以在这里下到: http://aspnet.codeplex.com/releases/view/24644
客户端片段:
(1) 查询(HTTP/GET), 使用 HttpClient.Get
方法,返回的是HttpResponseMessage,HttpResponseMessage.Content
返回的是Json数据。再通过 Json.NET 第3方组件进行反序列化。另外,为了是在客户端里能通过实例化的类来操作数据,所以在客户端单独再定义了
Task 类。(因为客户端无法通过wsdl生成代理)
// Get Data by state 2.var client = new HttpClient(); 3.var strUrl = "http://localhost:1180/TaskService/Tasks/State/{0}"; 4.strUrl = string.Format(strUrl, comboBox1.SelectedValue); 5.var response = client.Get(strUrl); 6.response.EnsureStatusIsSuccessful(); 7.var json = response.Content.ReadAsString(); 8.var data = JsonConvert.DeserializeObject<List<Task>>(json);
|
(2) 新建(HTTP/POST),将数据序列化成Json格式放进 HttpContent
再使用 HttpClient.Post 提交 HttpContent 数据。
HttpContent 需要指定 ContentType 是Json格式的
// Add Task 2.var task = GetTask(); 3.var client = new HttpClient(); 4.var strUrl = "http://localhost:1180/TaskService/Tasks/Add"; 5.var response = client.Post(strUrl, GetContent(task)); 6.response.EnsureStatusIsSuccessful();
|
(3) 更新(HTTP/PUT)
// Update Task 2.var task = GetTask(); 3.var client = new HttpClient(); 4.var strUrl = "http://localhost:1180/TaskService/Tasks/{0}"; 5.strUrl = string.Format(strUrl, task.ID); 6.var response = client.Put(strUrl, GetContent(task)); 7.response.EnsureStatusIsSuccessful();
|
(4) 删除(HTTP/DELETE)
// Delete Task 2.var task = GetTask(); 3.var client = new HttpClient(); 4.var strUrl = "http://localhost:1180/TaskService/Tasks/{0}"; 5.strUrl = string.Format(strUrl, task.ID); 6.var response = client.Delete(strUrl); 7.response.EnsureStatusIsSuccessful();
|
哦,还漏了个 GetContent(Task task) 方法:
private HttpContent GetContent(Task task) 2.{ 3. var strContent = JsonConvert.SerializeObject(task); 4. var data = System.Text.Encoding.UTF8.GetBytes(strContent); 5. return HttpContent.Create(data, "application/json"); 6.}
|
response.EnsureStatusIsSuccessful 用来检查
Response.StatusCode。
WCF4.0 –- RESTful WCF Services (3)
(Raw Stream)
前面2篇blog,主要在介绍REST WCF如何通过json/xml 和客户端完成交互。
这篇文章将对REST WCF的原生(RAW)流传输进行一次实例分析。
OK,还是利用 WCF REST Service Application
的工程模板,创建我们的REST WCF工程。
因为WCF REST服务不需要公开metadata, 所以 OperationContract
的定义也省略了。直接定义[ServiceContract]
如果修改模板中Service名,Global.asax中的RegisterRoutes方法也必须相应的修改。
下面是服务的实现:
[ServiceContract] 2.[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)] 3.[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerCall, Namespace="")] 4.public class ImageService 5.{ 6. [WebGet(UriTemplate = "{image}")] 7. public Stream GetImage(string image) 8. { 9. var imageType = Path.GetExtension(image).TrimStart('.'); 10. WebOperationContext.Current.OutgoingResponse.ContentType = "image/" + imageType; 11. var dir = System.Web.HttpContext.Current.Server.MapPath("~/Images"); 12. var file = Path.Combine(dir, image); 13. return File.OpenRead(file); 14. } 15. 16. [WebInvoke(UriTemplate = "Add/{image}", Method="POST")] 17. public void AddImage(Stream stream, string image) 18. { 19. var dir = System.Web.HttpContext.Current.Server.MapPath("~/Images"); 20. var file = Path.Combine(dir, image); 21. var bitmap = Bitmap.FromStream(stream); 22. bitmap.Save(file); 23. } 24. 25. [WebGet(UriTemplate = "ListAll", ResponseFormat=WebMessageFormat.Xml)] 26. public string[] GetAllImageNames() 27. { 28. var dir = System.Web.HttpContext.Current.Server.MapPath("~/Images"); 29. var files = Directory.GetFiles(dir); 30. var images = new List<string>(); 31. foreach (var file in files) 32. { 33. var ext = Path.GetExtension(file); 34. if (ext == ".jpg" || ext == ".gif") 35. images.Add(file); 36. } 37. for (int i = 0; i < images.Count; i++) 38. images[i] = Path.GetFileName(images[i]); 39. return images.ToArray(); 40. } 41.}
|
- GetImage 用于返回图片 Stream,
- AddImage 用于接受图片 Stream 并保存,
- GetAllImageNames 返回所有图片名。
在Http协议中,通过content-type控制客户端的解析行为。当content-type是"image/jpg"或者是"image/gif"的时候,浏览器就能够直接显示图片了。因此,在代码里有这样的设定:
WebOperationContext.Current.OutgoingResponse.ContentType
= "image/" + imageType;
还可以通过 OutgoingResponse.Header 控制缓存。另外,这个REST
WCF是建立在一个Web Application中,
我们还可以利用 System.Web.HttpContext.Current.Server.MapPath
方法,获得物理路径。
我们知道一般的WCF服务中,可以实现Streamed传输。在那种场合下,服务契约必须的参数或者返回值必须是Stream,且不能有别的类型的参数(要传递别的参数可以通过MessageHeader)。但是在上面的示例代码中,我定义的
AddImage 就有两个参数:
一个是Stream,还有一个是string。这个string参数其实是通过url传递的:
UriTemplate = "Add/{image}",且这两个参数没有顺序要求。
如果没有写"{image}"会抛出下面的异常(因为Request的Body已经被定义为Stream,图片名只能通过Url传过来。)
Operation 'AddImage' of contract 'ImageService'
specifies multiple request body parameters to be serialized
without any wrapper elements. At most one body parameter
can be serialized without wrapper elements. Either remove
the extra body parameters or set the BodyStyle property
on the WebGetAttribute/WebInvokeAttribute to Wrapped.
运行服务,直接在浏览器里输入服务URL:http://localhost:3577/ImageService/GIF002.gif
我们就可以看到结果了。
另外,利用REST WCF返回原生流的特性,我们完全可以取代以前在 ASP.NET
中专门生成验证码或者图片读取步骤的页面类,是不是很方便?
为了体现 REST WCF 的便利性, 我设计了一个 WPF 的客户端:
客户端代码:
public partial class MainWindow : Window 2.{ 3. public MainWindow() 4. { 5. InitializeComponent(); 6. } 7. 8. private void Window_Loaded(object sender, RoutedEventArgs e) 9. { 10. op.RestoreDirectory = true; 11. op.Filter = "Jpeg Files(*.jpg)|*.jpg|Gif Files(*.gif)|*.gif"; 12. 13. BindData(); 14. } 15. 16. private void BindData() 17. { 18. var url = "http://localhost:3577/ImageService/ListAll"; 19. var client = new HttpClient(); 20. var stream = client.Get(url).Content.ReadAsStream(); 21. var dataSer = new DataContractSerializer(typeof(string[])); 22. var obj = (string[])dataSer.ReadObject(stream); 23. this.listBox1.DataContext = obj; 24. } 25. 26. private Microsoft.Win32.OpenFileDialog op = new Microsoft.Win32.OpenFileDialog(); 27. 28. private void button1_Click(object sender, RoutedEventArgs e) 29. { 30. var ret = op.ShowDialog(); 31. if (!ret.HasValue || !ret.Value || !op.CheckFileExists) return; 32. var file = op.FileName; 33. var name = System.IO.Path.GetFileName(file); 34. var url = "http://localhost:3577/ImageService/Add/" + name; 35. var client = new HttpClient(); 36. var content = HttpContent.Create(File.OpenRead(file)); 37. var resp = client.Post(url, content); 38. resp.EnsureStatusIsSuccessful(); 39. 40. BindData(); 41. } 42. 43. private void button2_Click(object sender, RoutedEventArgs e) 44. { 45. this.Close(); 46. } 47.} 48. 49.[ValueConversion(typeof(string), typeof(string))] 50.public class UriConverter : IValueConverter 51.{ 52. public object Convert(object value, Type targetType, 53. object parameter, System.Globalization.CultureInfo culture) 54. { 55. if (value == null) return null; 56. string sourceValue = value.ToString(); 57. return "http://localhost:3577/ImageService/" + sourceValue; 58. } 59. 60. public object ConvertBack(object value, Type targetType, 61. object parameter, System.Globalization.CultureInfo culture) 62. { 63. return value; 64. } 65.}
|
实现的注意点:
1) 获得所有图片名,服务端返回的是string[]的序列化的xml,用DataContractSerializer反序列化。
var dataSer = new DataContractSerializer(typeof(string[]));
2) WPF中的OpenFileDialog在Microsoft.Win32命名空间下。(必须引用WindowsBase.dll)
3) 利用 Microsoft.Http.HttpClient 上传图片,
实例化 HttpContent, 通过client.Post上传
var url = "http://localhost:3577/ImageService/Add/" + name; var client = new HttpClient(); var content = HttpContent.Create(File.OpenRead(file)); var resp = client.Post(url, content); resp.EnsureStatusIsSuccessful(); |
4) 定义了一个Converter, 将 ListBox 绑定到 Image
控件的 Source
Source="{Binding ElementName=listBox1,
Path=SelectedItem, Converter={StaticResource uriConv}}"
下篇:WCF4.0
–- RESTful WCF Services(二)
|