[Blog Map]  This blog is inactive.  New blog: EricWhite.com/blog

Coding and hosting a WCF web service is a great way to experiment with Business Connectivity Services (BCS) and External Content Types (ECT). In the near future, I’m going to be writing about some of the BCS scenarios where you need to manually code the BCS model. When putting together many-to-many associations or one-to-many where you don’t have a foreign key, you need to manually edit the BCS metadata model.

My favorite way to develop/experiment/write about SharePoint 2010 is to use the 2010 Information Worker Demonstration and Evaluation Virtual Machine. It is a great virtual machine – finely tuned, and has all of the necessary software installed, including SharePoint Server 2010, Visual Studio 2010, Office 2010, etc. I do on occasion build my own virtual machines when absolutely necessary, but I consider it a necessary evil, not something that I enjoy.

Recently, I wrote a blog post / MSDN article on building and hosting a WCF web service. However, to host the web service in the demo / evaluation virtual machine, you need to add a new web site, which is different from the procedure I presented in that post. This blog post presents the correct procedures for building/hosting the web service in that VM. Once you’ve hosted the web service, you can create an ECT from it, create a list for the ECT, set permissions for the ECT in SharePoint 2010 Central Administration, and then view the list. To do this, you can follow the procedure in Consuming a Claims-Enabled WCF Web Service as a SharePoint 2010 External Content Type. If you follow the steps in this blog post, you can ignore steps 26, 27, 28, and 38, which are associated with consuming the claims-aware web service. At some point in the near future, time permitting, I’m going to write procedures for building a claims-aware web service in that virtual machine.

This web service contains only two methods: a ‘finder’ to retrieve a collection of items, and a ‘specific finder’ to retrieve a single item. The ‘database’ behind the collection is just an initialized list. The ‘schema’ of this little ‘database’ is very simple. It is a single flat table consisting of two fields – an integer CustomerID, and a string CustomerName. CustomerID is a unique ID.

return new List<Customer>()
{
    new Customer
    {
        CustomerID = 1,
        CustomerName = "Bob",
    },
    new Customer
    {
        CustomerID = 2,
        CustomerName = "Bill",
    },
    new Customer
    {
        CustomerID = 3,
        CustomerName = "Cheryl",
    },
};

After building and configuring this web service, you can use SharePoint Designer 2010 to create an ECT from it, and then view the data in a SharePoint list.

As you probably know, BCS in SharePoint server 2010 is read/write. If you supply additional methods to create, update, and delete items, then you can fully maintain the data in a list. I’m interested in keeping this web service absolutely as simple as possible, so this is only a read-only implementation.

As I mentioned, the procedure that I present here shows how to host the web service under IIS. This is the way that most implementers of such a web service will want to host it. Hosting it as a service of IIS gives lots of benefits such as process recycling, process health monitoring, and message based activation.

Creating a Web Service

1. Create a directory, C:\MyWebService, which will contain the web service. If you use a different directory than this, you will need to alter these procedures as appropriate.
2. Start Visual Studio 2010.
3. Click File => New => Project.
   1. For the installed template category, select WCF.
   2. For the template, select WCF Service Application.
   3. Target the .NET Framework 3.5.
   4. For the location of the project, browse to the directory that you created in step 1.
   5. Name the project CustomersService.
   6. Do not create a directory for the solution.
      
      
      
      Note: Don’t forget to target the .NET Framework 3.5. By default, Visual Studio will target the .NET Framework 4.0, and you must change to 3.5 for the procedure presented here to work.
4. In the project, rename IService1.cs to ICustomers.cs. Visual Studio 2010 may ask whether you would also like to perform a rename in this project of all references to the code element ‘IService1’? Click Yes. Actually, we’re going to replace all code in all modules, so it doesn’t matter whether you click Yes or No.
5. In the project, rename Service1.svc to Customers.svc. After renaming these items, the Solution Explorer will look like this.
   
   
6. Replace Customers.svc with the following single line of markup. Right click on Customers.svc, and select View Markup. Copy, paste, and save.
   
   <%@ ServiceHost Language="C#" Debug="true" Service="CustomersService.Customers" CodeBehind="Customers.svc.cs" %>
7. Replace Customers.svc.cs with the following code.

using System;
using System.Collections.Generic;
using System.Linq;

namespace CustomersService
{
    public class Customers : ICustomers
    {
        // Finder
        public List<Customer> GetAllCustomers()
        {
            return new List<Customer>()
            {
                new Customer
                {
                    CustomerID = 1,
                    CustomerName = "Bob",
                },
                new Customer
                {
                    CustomerID = 2,
                    CustomerName = "Bill",
                },
                new Customer
                {
                    CustomerID = 3,
                    CustomerName = "Cheryl",
                },
            };
        }

        // Specific finder
        public Customer GetCustomerByID(int CustomerID)
        {
            return GetAllCustomers().FirstOrDefault(c => c.CustomerID == CustomerID);
        }
    }
}

Replace ICustomers.cs with the following code.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.Serialization;
using System.ServiceModel;

namespace CustomersService
{
    [ServiceContract]
    public interface ICustomers
    {
        [OperationContract] //finder
        List<Customer> GetAllCustomers();

        [OperationContract] //specificFinder
        Customer GetCustomerByID(int CustomerID);
    }

    [DataContract]
    public class Customer
    {
        [DataMember]
        public int CustomerID { get; set; }

        [DataMember]
        public string CustomerName { get; set; }
    }
}

Replace Web.config with the following markup. In Solution Explorer, right-click on Web.config and select Edit. Copy, paste, and save. Important note: this is the Web.config that configures this specific web service. It resides at C:\MyWebService\CustomersService.

<?xml version="1.0"?>
<configuration>
  <system.serviceModel>
    <services>
      <service behaviorConfiguration="CustomersService.Service1Behavior"
        name="CustomersService.Customers">
        <endpoint address="" binding="wsHttpBinding" contract="CustomersService.ICustomers">
          <identity>
            <dns value="localhost" />
          </identity>
        </endpoint>
        <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" />
      </service>
    </services>
    <behaviors>
      <serviceBehaviors>
        <behavior name="CustomersService.Service1Behavior">
          <!-- To avoid disclosing metadata information, set the value below to false and remove the metadata endpoint above before deployment -->
          <serviceMetadata httpGetEnabled="true"/>
          <!-- To receive exception details in faults for debugging purposes, set the value below to true.  Set to false before deployment to avoid disclosing exception information -->
          <serviceDebug includeExceptionDetailInFaults="false"/>
        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>
</configuration>

Build the application.

Add a new web site.

1. Start Internet Information Services (IIS) Manager. Click Start => All Programs => Administrative Tools => Internet Information Services (IIS) Manager.
2. In Internet Information Services (IIS) Manager, right-click on Sites, and select Add Web Site.
   
   
3. In the Add Web Site dialog box, in the Site name field, enter Customers. In the Application Pool field, select DefaultAppPool. In the Physical path field, enter C:\MyWebService\CustomersService. In the Port field, enter 8181. In the Host name field, enter www.contoso.com. Click OK.
   
   
4. Validate that the web service is running. Start Internet Explorer, and browse to http://www.contoso.com:8181/Customers.svc. If the web service is running, you will see the following:
   
   

Another interesting approach to testing the Web service is to use the WCF test client. Start a Visual Studio command prompt. Enter wcftestclient to run the WCF test client. Click File => Add Service. Enter http://www.contoso.com:8181/Customers.svc as the endpoint address, and click OK.

If the service was added successfully, you will see the methods that the service exposes.

Double-click on GetAllCustomers. This opens a window that allows you to configure the request and invoke the request. Click on Invoke to see the response from the Web service.