WCF, IIS, and REST

Overview

Download the code: http://gallery.technet.microsoft.com/WCF-REST-and-IIS-130b242c

While I was performing mindless chores around the house this morning I came to the realization that they were not that mindless. After all, I was contemplating REST. Not the type of REST that has you falling into a hole in the couch that you can’t get out of for a few hours but rather Representational State Transfer. Why should I be thinking about REST? I think the better question is why not? REST is certainly gathering momentum and I have noticed this while loitering around the WCF Forum on MSDN. The usual question seems to be “How do I upload a file using REST?”. Therefore, that will be the topic of discussion today.

I intend to provide a fully functional implementation of a REST service that lives in IIS as an Application. It may seem elementary to do so but most of the examples are quite difficult to work with and that’s even for a seasoned WCFaholic like myself.

The implementation for our REST service will be done through a configuration file. Yes, I know, Microsoft has put in a lot of effort creating the WebServiceHost and WebServiceHostFactory classes to make our lives easier but if you take the time and get a deeper understanding of WCF configuration, I guarantee you will be weighing up the advantages of imperative or configuration programming more carefully.

The reason we need to upload files today is because we love to go fishing. When we go fishing we like to take pictures of our adventures. When we come home, we want to store those pictures on the internet so our families in other countries can get a better idea of our endeavours (Also to make them jealous of the fresh seafood Australia has to offer).  

Figure 1: My nephew onto a good size kingfish (The type of stuff we want uploaded)

Creating the REST Service

The reason we are choosing REST today is that all of our functionality is based around a resource. We will be adding new images using POST and retrieving images using GET. If we required operational functionality in the form of operations like Crop Image or Watermark image I probably would have used an operation centric approach such as SOAP. Hence there lies the difference. REST is resource centric, SOAP is operation centric.

Enough talk, more action. So, let’s create the REST service.

    -          Open Visual Studio 2010 (RunAs Administrator so you can create a website)
    -          File->New Website. This will open the Visual Studio Templates page
    -          Select WCF Service and name your site http://localhost/FishImagesService and click OK
    -          The project will be created in VB.NET (I hope to have a C# sample soon)

At this point Visual Studio will create the website as a Web Application and generate a whole bunch of boiler plate code.  First of all, what I would like you to do is delete IService.vb and Service.vb. We won’t be needing those. Now, to add our class:

    -          Right Click the App_Code folder and select ‘Add New Item…’ from the context menu
    -          When the ‘Add New Item’ window appears select Class 
    -          Name the Class FishImagesService.vb and click OK

Now that we have our class file, paste in the following Service Contract over whatever little code was generated by Visual Studio:

Imports System.IO
Imports System.Net
Imports System.ServiceModel.Channels
 
<ServiceContract()>
Public Interface IFishImagesService
    <OperationContract()>
    <WebGet(UriTemplate:="FishImagesGET")>
    Function FishImagesGET() As Message
    <OperationContract()>
    <WebGet(UriTemplate:="FishImagesGETFile/{filename}")>
    Function FishImagesGETFile(filename As String) As Message
    <OperationContract()>
    <WebInvoke(Method:="POST",
               UriTemplate:="FishImagesPOST/{filename}")>
    Sub FishImagesPOST(ByVal filename As String, file As Stream)
End Interface

Let’s have a closer look. We have two WebGet methods. First, FishImagesGET will return and xml representation of what files we have already uploaded. Second, FishImagesGETFile is the method we will call to send the actual image to the calling application. The calling application in this instance will be an ASP.NET Website. We will investigate this a little later in this article. Last, we have FishImagesPOST. This method will be invoked when we upload a file. What is really interesting about the WebGet methods is that they return a Message object back to the calling application. The reasons for this will become clearer later in this article. So apart from that, it’s a pretty simple service contract, right?

OK, now it’s time for the implementation. Copy and paste this code directly under the service contract:

<ServiceBehavior(InstanceContextMode:=InstanceContextMode.PerCall)>
 
Public Class FishImagesService
 
    Implements IFishImagesService
 
    Implements IDisposable
 
    Private filestream As FileStream
 
    Public Function FishImagesGET() As System.ServiceModel.Channels.Message Implements IFishImagesService.FishImagesGET
 
        Dim dir As New DirectoryInfo(fishImagesFolder)
 
        Dim files As XDocument = <?xml version="1.0"?><files><%= From f In dir.GetFiles("*.jpg") Select <file><%= f.Name %></file> %></files>
 
        WebOperationContext.Current.OutgoingResponse.ContentType = "application/xml"
 
        Return WebOperationContext.Current.CreateTextResponse(files.ToString)
 
    End Function
 
    Public Function FishImagesGETFile(filename As String) As System.ServiceModel.Channels.Message Implements IFishImagesService.FishImagesGETFile
 
        filestream = New FileStream(fishImagesFolder() & filename, FileMode.Open, FileAccess.Read, FileShare.Read)
 
        Return WebOperationContext.Current.CreateStreamResponse(fileStream, "image/jpeg")
 
    End Function
 
    Public Sub FishImagesPOST(filename As String, file As System.IO.Stream) Implements IFishImagesService.FishImagesPOST
 
        Dim filestream As New FileStream(fishImagesFolder() & filename, FileMode.Create)
 
        Dim filebuf(WebOperationContext.Current.IncomingRequest.ContentLength) As Byte
 
        Dim bytesRead As Integer = file.Read(filebuf, 0, filebuf.Length)
 
        filestream.Write(filebuf, 0, bytesRead)
 
        filestream.Flush()
 
        filestream.Close()
 
    End Sub
 
    Private Function fishImagesFolder() As String
 
        Return ConfigurationManager.AppSettings("FishImagesLocation")
 
    End Function
 
    Private disposedValue As Boolean
 
    Protected Overridable Sub Dispose(disposing As Boolean)
 
        If Not Me.disposedValue Then
 
            If disposing Then
 
                If Not IsNothing(filestream) Then
 
                    filestream.Close()
 
                End If
 
            End If
 
        End If
 
        Me.disposedValue = True
 
    End Sub
 
    Public Sub Dispose() Implements IDisposable.Dispose
 
        Dispose(True)
 
        GC.SuppressFinalize(Me)
 
    End Sub
 
End Class

So we’re half way there (For the REST service anyway). I should probably give some details about the above implementation.

You will notice that the message signatures for REST go against everything that is WCF. What I mean by this, and in particular the POST signature, is that it includes a value type (Although string is not a value type in .NET we will still refer to it that way), a Stream type and a Message type. WCF does not let you mix these when dealing with a standard SOAP service but with REST this is possible.

We now have to make changes to our Service.svc file. For those of you who don’t know, the Service.svc file is by which we access our REST service. It stores a pointer to our service class and code files. Open the Service.svc file that is on the root level of our site and replace all of the code with the following:

<%@ ServiceHost Language="VB" Debug="true" Service="FishImagesService" CodeBehind="~/App_Code/FishImagesService.vb" %>

Note: I have set debug to true here so we can debug our service

OK, last but not least is our web.config file. This file stores our endpoint for the REST service to say the least. There are also sections for the service, binding configurations and behaviour configurations. Copy and paste the following directly over the current content of the file:

<?xml version="1.0"?>
 
<configuration>
 
  <appSettings>
 
    <add key="FishImagesLocation" value="c:\temp\"/>
 
  </appSettings>
 
  <system.web>
 
    <compilation debug="true" strict="false" explicit="true" targetFramework="4.0" />   
 
    <pages>
 
      <namespaces>
 
        <add namespace="System.Runtime.Serialization"/>
 
        <add namespace="System.ServiceModel"/>
 
        <add namespace="System.ServiceModel.Web"/>
 
      </namespaces>
 
    </pages>      
 
  </system.web>
 
  <system.serviceModel>
 
    <services>
 
      <service name="FishImagesService">
 
        <endpoint address=""
 
                  binding="webHttpBinding"
 
                  contract="IFishImagesService"
 
                  behaviorConfiguration="webHttpBH"
 
                  bindingConfiguration="webHttpBG"/>
 
      </service>
 
    </services>
 
    <bindings>
 
      <webHttpBinding>
 
        <binding name="webHttpBG"
 
                 maxReceivedMessageSize="100000" />
 
      </webHttpBinding>
 
    </bindings>
 
    <behaviors>
 
      <endpointBehaviors>
 
        <behavior name="webHttpBH">
 
          <webHttp helpEnabled="true" />
 
        </behavior>
 
      </endpointBehaviors>
 
      <serviceBehaviors>
 
        <behavior>
 
          <serviceMetadata httpGetEnabled="true"/>
 
          <serviceDebug includeExceptionDetailInFaults="false"/>
 
        </behavior>
 
      </serviceBehaviors>
 
    </behaviors>
 
    <serviceHostingEnvironment multipleSiteBindingsEnabled="true"/>
 
  </system.serviceModel>
 
  <system.webServer>
 
    <modules runAllManagedModulesForAllRequests="true"/>   
 
  </system.webServer>
 
</configuration>

There’s just one thing really worth mentioning here. I have set the MaxReceivedMessageSize to something astronomical. You really need to pay attention to this attribute as it is usually the cause of more problems than anything else. The default is 64K so be careful.

Well that’s it for our service. We’ve defined our contract, implemented our service, modified our Service.svc file and updated our configuration file. Our REST service is ready to go.

Creating the APS.NET Website

For our REST service to be of any value, we need to create an application that consumes it. The choice for today’s example will be an ASP.NET Website. You can create any type of application to consume this service. A question that comes up a lot is “How do I access a file from the client using VBScript or Javascript”. The short answer is that you cannot. The long answer is that you can by means of ActiveX objects and if you are running a truly internet based application then the configuration for this is a nightmare (Firefox lets you do this but I have only read about it). So I’m not even going to both explaining.

The way we will send our data to the REST service will be by using the FileUpload Control. Although it may seem superfluous to do so as we can just save the file on the server using the FileUpload Control functionality. The purpose of this article is to demonstrate how to send files to REST service, so don’t let twisted logic get in the way of what is truly a great example.

OK, I’m rambling again. Let’s get down to business.

    -          Open Visual Studio 2010 (RunAs Administrator so you can create a website)
    -          File->New Website. This will open the Visual Studio Templates page
    -          Select Empty Website and name your site http://localhost/FishImagesWebsite and click OK
    -          The project will be created in VB.NET (I hope to have a C# sample soon)

We need to add our Default.aspx page to the site.

    -          Right Click the site in Solution Explorer and select ‘Add New Item…’ from the context menu
    -          When the ‘Add New Item’ window appears select WebForm and click OK
    -          The default page name will be Default.aspx. Just what we need.

Right click the Default.aspx page in Solution Explorer and select ‘View Markup’ from the context menu. Remove all of the code on the page and replace it with the following:

<%@ Page Language="VB" AutoEventWireup="false" CodeFile="Default.aspx.vb" Inherits="_Default" %>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
<html xmlns="http://www.w3.org/1999/xhtml">
 
<head runat="server">
 
    <title></title>
 
    </head>
 
<body>
 
    <form id="form1" runat="server">
 
    <div>   
 
        <asp:DataList ID="DataList1" runat="server"
 
        Height="88px" RepeatColumns="3"
 
            BackColor="White" BorderColor="#CCCCCC"
 
            BorderStyle="None" BorderWidth="1px"
 
            CellPadding="4" GridLines="Horizontal" ForeColor="Black">
 
            <FooterStyle BackColor="#CCCC99"
 
            ForeColor="Black" />
 
            <HeaderStyle BackColor="#333333"
 
            Font-Bold="True" ForeColor="White" />
 
            <ItemTemplate>
 
                <asp:Image ID="Image1"
 
                ImageUrl='<%# DataBinder.Eval(Container.DataItem, "ImageValue")%>'
 
                runat="server" Height="240px" Width="320px" />               
 
            </ItemTemplate>
 
            <SelectedItemStyle BackColor="#CC3333"
 
            Font-Bold="True" ForeColor="White" />
 
        </asp:DataList>
 
        <br />
 
        <asp:FileUpload ID="FileUpload1" runat="server" />
 
        <asp:Button ID="buttonUpload" runat="server"
 
        Height="22px" Text="Upload"
 
            style="margin-top: 1px" />   
 
    </div>
 
    </form>
 
</body>
 
</html>

Cool, that was easy.  Right click anywhere in the page markup and select ‘View Code’ from the context menu. This will take us into the code behind for the Default.aspx file. Remove any of the code that was generated by Visual Studio and replace it with the following:

Imports System.Net
 
Imports System.IO
 
Imports System.Data
 
Partial Class _Default
 
    Inherits System.Web.UI.Page
 
    Private fishImages As New FishImages
 
    Protected Sub buttonUpload_Click(sender As Object, e As System.EventArgs) Handles buttonUpload.Click
 
        FishImagesPOST()
 
    End Sub
 
    Protected Sub Page_Init(sender As Object, e As System.EventArgs) Handles Me.Init
 
        Me.EnableViewState = False
 
    End Sub
 
    Protected Sub Page_Load(sender As Object, e As System.EventArgs) Handles Me.Load
 
        If Not Page.IsPostBack Then
 
            FishImagesGET()
 
        End If
 
    End Sub
 
    Private Sub FishImagesGET()
 
        Dim requestUrl As String = "http://localhost/FishImagesService/Service.svc/FishImagesGET"
 
        Dim request As HttpWebRequest = HttpWebRequest.Create(requestUrl)
 
        request.Method = "GET"
 
        request.ContentType = "application/xml"
 
        Dim xmlfileString As String = New StreamReader(request.GetResponse.GetResponseStream).ReadToEnd
 
        Dim xmlfile As XDocument = XDocument.Parse(xmlfileString)
 
        Dim files = From f In xmlfile.Element("files").Elements Select f
 
        For Each file In files
 
            fishImages.AddFish(file.Value)
 
        Next
 
        DataList1.DataSource = fishImages.FishData
 
        DataList1.DataBind()
 
    End Sub
 
    Private Sub FishImagesPOST()
 
        Dim requestUrl As String = "http://localhost/FishImagesService/Service.svc/FishImagesPOST/" & FileUpload1.FileName
 
        Dim request As HttpWebRequest = HttpWebRequest.Create(requestUrl)
 
        request.Method = "POST"
 
        request.ContentType = "text/plain"
 
        Dim fileToSend() As Byte = FileUpload1.FileBytes
 
        request.ContentLength = fileToSend.Length
 
        Dim requestStream As Stream = request.GetRequestStream
 
        requestStream.Write(fileToSend, 0, fileToSend.Length)
 
        requestStream.Close()
 
        FishImagesGET()
 
    End Sub
 
End Class
 
Public Class FishImages
 
    Private _fishData As DataView
 
    Private dt As New DataTable()
 
    Private dr As DataRow
 
    Public Sub New()
 
        dt.Columns.Add(New DataColumn("ImageValue", GetType(String)))
 
    End Sub
 
    Public Sub AddFish(filename As String)
 
        dr = dt.NewRow()
 
        Dim img As String
 
        img = "http://localhost/FishImagesService/Service.svc/FishImagesGETFile/" & filename
 
        dr(0) = img
 
        dt.Rows.Add(dr)
 
        _fishData = New DataView(dt)
 
    End Sub
 
    Public Function FishData() As DataView
 
        Return _fishData
 
    End Function
 
End Class

After review of the code you will find that there is a method to GET resources from the REST service (FishImagesGET) and a method to POST resources to the REST service (FishImagesPOST). You will also notice another class in the picture named FishImages. We use this class as a data source for our DataList on the Default.aspx page.

Last but not lest is the configuration file for the Website.

<?xml version="1.0"?>
 
<configuration>
 
  <system.web>
 
    <compilation debug="true" strict="false"
 
                 explicit="true" targetFramework="4.0"/>
 
    <httpRuntime maxRequestLength="100000"/>
 
  </system.web>
 
</configuration>

It’s pretty obvious that there is only one thing worth mentioning here and that is maxRequestLength in the <httpRuntime> element. This ensures that the message will accept a decent size file that gets posted to our REST service. OK, we’re done! Now let’s test our implementation.

Testing the REST service using a Website

Open Internet Explorer and type in the following URL:

 http://localhost/FishImagesWebsite

You will see the following screen (pretty simple), Simply click the ‘Browse…’ button to select a file then click ‘Upload’ to upload the file to the REST service:

The same page after images have been uploaded:

**
**

Conclusion

Hopefully after today you have a better understanding of REST. We saw how to add a REST service to IIS and consume that service using a Website.