Wouter

This is the fourth part of a series on Service Applications. The following has already been posted:

• Service Applications 101 – The Road to Rome
• Service Applications 102 – Ten lines and one F5
• Service Applications 103 – Simple proxy big results
• Service Applications 104 – Across the wire

Find the code for this sample on my CodePlex demo portal under the Navigation Service with WCF Proxy release.

Introducing WCF as an offloading mechanism

In the first three parts of this walkthrough you were introduced to the concept of service applications, on the basic steps to create one and finally on how to add a proxy layer to provide an extra level of indirection between the application and the consumers. In this blog post will show how to move the proxy to the next level by introducing WCF as a mechanism to push incoming requests to backend application servers.

The earlier three blog posts laid down the foundation for this first full-blown service application. A few extra components need to be added. Another few existing classes need some extra attention. I also threw in a testing page that is accessible from the Ribbon on the application management page. Hopefully this enables you to have an easy time seeing whether your code actually works (mine does, yay!)

The following is a list of todo items for moving the last application with the simple proxy to one that is enabled by WCF

• Start making use of new base classes for the service, service proxy, service application and service application proxy.
• Create a new service instance class to represent the service on a particular backend server
• Add a WCF contract interface
• Add the WCF service and client configuration
• Implement the WCF client and server code

That's it. A bit involved as you can see from the list of items that need to get done, but we can just start at the first and work your way down the list.

Introducing new base classes

Now that we are moving towards a WCF enabled system there are a lot of new base classes to use. Earlier we had the SPService, SPServiceProxy, SPServiceApplication and SPServiceApplicationProxy. For working WCF you can swap all these out with their counterparts. SPIisWebService, SPIisWebServiceProxy, SPIisWebServiceApplication and SPIisWebServiceApplicationProxy.

The SPIisWebService

Where earlier you derived your service class from SPService, you now need to move towards the SPIisWebService. Not that much difference in implementation. The only code that goes in this class is internal. It maintains a bunch of settings such as default endpoint names and network port numbers.

The SPIisWebServiceProxy

The replacement for the SPServiceProxy is the SPIisWebServiceProxy. Examine the class with .NET Reflector and notice that there is absolutely nothing it does extra. The reason it exists is likely to achieve some parity between all relevant classes (all SPIisWeb… classes).

The SPIisWebServiceApplication

The service application for WCF is a bit more complex in its internals. It maintains references to the IIS application pool used to serve incoming requests. There are many IIS related settings such as endpoint configuration. It iments a configurable backup strategy for the application, proxies and any databases you may have. You will also find a small model for configuring service security, allowing you to implement your own permission types. So, this class is definitely worth a further look after you have gotten your basic application going.

The SPIisWebServiceApplicationProxy

Closing the line of new base classes is the proxy for the service application. Again you will find support for easily integrating with the backup functionality. The proxy also serves as a place to store what address the proxy will connect to when used.

Updating the service and service proxy

When it comes to code changes, let's begin with the service and service proxy since these two components have the least going on. They are only there to support the larger infrastructure and do not contain any WCF specifics. The service itself only has a new base class. The rest of the changes are specific to the service proxy.

The first change you find in the service proxy is that you need to add the SupportedServiceApplication attribute. This attribute links the service proxy to a service application. You can add as many attributes as the number of service application types that your service supports. The attribute is used to fill the user interface presented as part of the Connect menu. After you enter the service URL you will be shown a list of service applications you can connect to. This list is created using the information from this attribute. Since our service will now truly support connecting proxies with applications you'll need to add this attribute. Earlier editions of the proxy didn't need this since we weren't using WCF yet.

How it works is that you will open the Connect menu and choose a service application type to connect to. Under the covers the value in this attribute is read. In the Connect to a Remote Service Application dialog that appears you will enter the URL of a farm, hit next. On the second page of the connection wizard a filtered list of available service applications is provided for you to choose from. This list is filtered based on the attribute's value, allowing filtering on the application type and the application version.

[SupportedServiceApplication(
    "f46c5a6a-0f73-4c1e-b11b-c2ffb70c19f9", 
    "1.0.0.0", 
    typeof(NavigationApplicationProxy))]
The next major change that you find in the service proxy is an implementation of the IServiceProxyAdministration interface. This interface is used by SharePoint during automated processes as well as to fill the Connect menu.

The implementation of this interface is a huge no-brainer. All the methods you need to add are one-liners.

Implementing the WCF Service
Moving to a client / server model obviously requires you to implement the server (hint, the client too!). In many of the service applications that you find inside SharePoint you find a common approach. Most of the service application objects implement the WCF service. For the Navigation Service we'll do the same. Although technically not necessary, we'll begin with defining a service contract. For the demo's sake it is a bit sparse in terms of the functionality that we'll provide to consumers.

[ServiceContract]
public interface INavigationApplication
{
    [OperationContract]
    string GetNavigationInformation();
}
The next step is to change the base class for the NavigationApplication. Instead of deriving from SPServiceApplication we now extend SPIisWebServiceApplication. This base class requires you to implement two properties that point to the .SVC file that is used as the endpoint address. You will deploy the .SVC file to the WebServices folder which is a new folder found directly under the SharePoint 2010 installation path.

public class NavigationApplication
    : SPIisWebServiceApplication, 
    INavigationApplication
{
    protected override string InstallPath
    {
        get 
        { 
            return SPUtility.GetGenericSetupPath(
                @"WebServices\CodeCounsel.SharePoint.NavigationService"); 
        }
    }

    protected override string VirtualPath
    {
        get { return "Navigation.svc"; }
    }
}
Under the covers the InstallPath and VirtualPath values are combined to locate the .SVC file. This file is deployed as part of your project. In the .SVC file there is a pointer to the NavigationApplication class as well as to a new class which task it is to instantiate the WCF service host.

<%@ServiceHost

language=C#

Service="..."

Factory="..."%>

The factory is specific to your scenario. There is a factory for SOAP based services, for REST services and for ADO.NET data services. In the factory class there is only one specific bit. It activates claims security for the service.

public class NavigationApplicationHostFactory
    : MultipleBaseAddressBasicHttpBindingServiceHostFactory 
{
    public override ServiceHostBase CreateServiceHost(
        string constructorString, Uri[] baseAddresses)
    {
        ServiceHost host = new ServiceHost(
            typeof(NavigationApplication), 
            baseAddresses);
        host.Configure(SPServiceAuthenticationMode.Claims);
        return host;
    }
}
The final part on the server side of the service application is the web.config that defines the service endpoints. You can specify details such as the communication protocol, TCP, HTTP, HTTPS etcetera. There are a huge amount of settings you can configure but luckily you don't need them all. The easiest is to copy an existing web.config, for instance from the Topology service and modify that to suite your needs. Just make sure you set the <service name=""> to the actual name of the service class (namespace + classname) and do the same for the contract.

Implementing the WCF client

Now that we have a server let's also create the client. The service application proxy will serve this task. When you examine existing implementations there is quite a lot of juggling with delegates to prevent duplication of code. In the Navigation Service demo however I chose to implement all functionality inline. Not smart, but better to read.

The first change in this class is that you can and most likely want to add a load balancer class. SharePoint provides a basic load balancer that chooses between available endpoints in a round robin fashion. You can also not use a load balancer, up to you. But it's only a few lines of code to add, so, add it already!

Since the WCF proxy class is mostly the same as the previous edition without WCF I'll not reiterate all the existing methods. Let's focus on the how to call the service application running on a backend server. The first thing you'll need to do is open the .NET configuration file that contains similar information as the server configuration. Endpoint and security data is what you'll find in the client.config file. You can make use of the .NET configuration APIs to open the correct client.config, which will be provisioned to the WebClients folder under the SharePoint 2010 installation path. Based on this configuration data you will instantiate a ChannelFactory for the service interface you added earlier. The ChannelFactory wants to know the specific endpoint that you want to use. In this sample it is hardcoded, but you could also determine the correct endpoint based on the URL that the proxy is connected to (URL starts with HTTPS:// it'll be the HTTPS endpoint right?) Next, use the load balancer to open a session and open the channel to the backend. The last step is to actually call the WCF service and return results.

public string GetNavigationInformation()
{
    string channelConfigPath = SPUtility.GetGenericSetupPath(
        @"WebClients\CodeCounsel.SharePoint.NavigationService");
    Configuration clientConfig = OpenClientConfiguration(channelConfigPath);
    ChannelFactory<INavigationApplication> factory =
        new ConfigurationChannelFactory<INavigationApplication>(
            "http", clientConfig, null);
    factory.ConfigureCredentials(SPServiceAuthenticationMode.Claims);

    SPServiceLoadBalancerContext context = _loadBalancer.BeginOperation();
    try
    {
        INavigationApplication channel = 
            factory.CreateChannelActingAsLoggedOnUser<INavigationApplication>(
                new EndpointAddress(context.EndpointAddress));
        return channel.GetNavigationInformation();
    }
    finally
    {
        context.EndOperation();
    }
}
In terms of doing things better you'll likely want to do some caching since instantiating channel factories and opening / parsing configuration files are expensive pieces of code.

Enabling the service on backend servers

Now that we have both a WCF server and a WCF client we also need a way to specify on what servers in our farm we want to run the service. This task falls in the hand of the SPServiceInstance, which is basically a class that couples your service with a specific server. What you need to do is instantiate an instance of this class for each server in the farm that you may want to run your service on. You can then go to the Services on Server page and start your service. This action will provision your service instance on that server and make it available for WCF requests.

Testing your work
The last step is to test the new WCF proxy based implementation. To make this easier to do I added a menu item to the Ribbon. It opens a testing page which calls the service application via the proxy.

Hope it helps!