Part One – The Service Application
Part Two – The Service Application’s Admin Interface
Part Three – The WCF Service Endpoint
Part Four – The User Application Page
Browse Complete Source Code
Download Visual Studio 2010 Solution
Update 10/29/09: Added Powershell cmdlets to create, retrieve and update properties of the demo service application. Refer to the accompanying sample project for details.
With each new release of SharePoint, Microsoft has managed to further improve this platform’s programmability, extensibility and manageability. Among many other exciting new features and capabilities, the new 2010 release of SharePoint now provides developers with ASP.NET AJAX as a first-class tool in our proverbial toolbox. AJAX has been around for some time now, and it is great to finally see both native and custom SharePoint applications will be enabled with the same rich, interactive user controls we’ve come to expect from quality browser-based applications. Yet another exciting technology that ships with SharePoint 2010 is the Service Application Framework. The Service Application Framework allows developers to create robust and scalable shared services which can be consumed by multiple SharePoint web applications.
In this article, I’ll show you how to create and provision a SharePoint Service Application. Within the service application I’ll define a WCF service endpoint which provides auto-completion services to ASP.NET AJAX-enabled controls. Finally I’ll leverage this WCF service and the ASP.NET AJAX Toolkit to provide users with a simple Geo-locator page. The Geo-locator will prompt a user for a city and state, suggesting known values in real-time as the form’s fields are completed. Once a city and state have been keyed, the user will be shown the specified location on a satellite map.
Admittedly, the use case set forth in this demonstration in somewhat contrived. Using SharePoint’s Service Application Framework to simply provide AJAX controls with auto-completion services is really beating a small nail with a big hammer. In most real-world production scenarios, such trivial functionality could probably be achieved with a simpler site-level web service. I’ve chosen such a simple use case so as to not distract from the primary purpose of the article, which is to illustrate how to create and provision the skeleton of a simple SharePoint Service Application.
The topic of SharePoint Service Applications is broad and technically advanced. Areas such as scalability, fault-tolerance, external service publishing, security, database provisioning and data backup are left for another demonstration. That being said, in this article I will get you started by showing the basics of creating, provisioning and hooking into the Central Administration management interface for SharePoint Service Applications.
This demonstration is accompanied by a complete Visual Studio solution. All code artifacts covered in this narrative are included in the solution. I will walk you through the process of creating the solution from scratch. As I add each artifact, I will highlight its salient points, but I will assume you also have the Visual Studio solution open to view complete code listings. There are a few utility and helper classes in the project which I don’t cover in this narrative, as I believe these artifacts are self-evident. The Visual Studio solution is meant to be a starting point for you to create your own SharePoint Service Applications. I hope you will be able to take the work done here and refactor it to a launching point for your own real-world use cases.
What You’ll Need
To follow along with this demonstration, I assume you have the following requirements installed and functioning properly.
- SharePoint 2010 – WSS only will do.
- Visual Studio 2010
- Visual Studio 2010 SharePoint Tools
- WSS 2010 SDK
- .NET Reflector
I also assume that you are an intermediate to advanced SharePoint developer familiar with the SharePoint object model and the latest ASP.NET, Visual Studio and SharePoint development tools.
Part One – The Service Application
In SharePoint 2010, the Service Application Framework provides you with the ability to create hosted, middle-tier services. These shared services can then provide data or processing resources to other SharePoint features. Native SharePoint applications such as search and Excel Services are built by using this platform. The platform is now available in SharePoint 2010 for third parties to also build upon.
Among other things, the Service Application Framework provides:
- Built-in support for building applications using the Windows Communications Framework (WCF).
- Integration with the standard SharePoint management experience, including Administration and configuration using SharePoint Central Administration.
Anatomy of a SharePoint Service Application
A service provides a very narrow range of functionality that usually does not include end-to-end functions that are valuable in themselves. Services typically run invisibly and have little or no UI.
Every SPService object has an Instances property that holds all the instances of the service that are running on various servers in the farm. No more than one instance of each service runs on any one server, but some services have multiple instances, each one running on a different server. Each instance is represented by an object of a class derived from SPServiceInstance.
SPServiceInstance represents an instance of a service on a server in the farm. A service instance is independent from, and identical in functionality, to all other server instances of the same type. As long as one service instance of a given service remains online, the service is fully functional. Service instances may be in the ‘started’ or ‘stopped’ state. A service instance provides the host process for service applications.
A service application is hosted by a service instance. Service applications are generally created by administrators. They provide the service interface, containing the administrator settings. Service applications may own user data.
A SPServiceProxy is simply the parent of the SPServiceApplicationProxy. It is the equivalent of a SPService on the server side, which is the parent of a SPServiceApplication. You can also think of these parent objects as class factories for the child objects, if that makes more sense to you.
Service application proxies provide the public (front-end) interface to a service application. They allow client code to consume remote service applications. Service applications may not be installed locally and therefore cannot be called directly.
Implementing the Service Application
In Visual Studio 2010 I start out by creating a new Empty SharePoint project.
When prompted by the SharePoint Customization Wizard, I’m going to target the Central Administration web, as this is where the service application will be deployed. Also in the wizard, I’ll select the option to Deploy as a full-trust solution.
Next, I add a new class to then project and name it AutoCompletionService.cs. As with all code artifacts in this demonstration, I’ll cover the highlights of this class, but refer to the accompanying Visual Studio 2010 sample project for the complete listing. The AutoCompletionService class inherits the SPIisWebService class and implements the IServiceAdministration interface. Because this class is a persisted object, it must also be decorated with the System.Runtime.InteropServices.Guid attribute and assigned a unique guid.
For serialization purposes, the AutoCompletionService class must have a default, parameter-less constructor. This class also implements a singleton pattern to provide the means for acquiring an instance of the local service.
I’ll add three more classes to the project. I’m going to name the new classes AutoCompletionServiceProxy.cs, AutoCompletionServiceApplication.cs and AutoCompletionServiceApplicationProxy.cs respectively.
AutoCompletionServiceApplication inherits from SPIisWebServiceApplication and implements IFormattable. As a persisted object, the AutoCompletionServiceApplication class must be decorated with the System.Runtime.InteropServices.Guid attribute and assigned a unique guid. AutoCompletionServiceApplication overrides the abstract InstallPath and VirutalPath properties of its parent SPIisWebServiceApplication. AutoCompletionServiceApplication also overrides the ManageLink virtual property of SPServiceApplication.
AutoCompletionServiceApplication needs two methods to both provision and unprovision the service application and its instance. These methods will be called from the UI when an administrator creates or tears down a service application instance.
AutoCompletionServiceProxy inherits from SPIisWebServiceProxy and implements the IServiceProxyAdministration interface. IServiceProxyAdministration requires the GetProxyTypes, GetProxyDescription and CreateProxy methods to be implemented. Also of note, AutoCompletionServiceProxy is decorated with the SupportedServiceApplication attribute which tightly couples it to AutoCompletionServiceApplicationProxy. Refer to the accompanying sample project for the complete class listing.
AutoCompletionServiceApplicationProxy inherits from SPIisWebServiceApplicationProxy.
Add another class titled AutoCompletionServiceInstance.cs to your Visual Studio 2010 project. AutoCompletionServiceInstance inherits from SPIisWebServiceInstance. This class overrides the DisplayName and TypeName properties. Again, refer to the accompanying sample project for the complete class listing.
In SharePoint 2010, WCF web services are stored at the path [14 Hive]\WebServices. On most systems the full path to this location is C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\WebServices. In Visual Studio 2010, I’ll create a SharePoint Mapped Folder to this location by right-clicking on the AutocompleteDemo project in Solution Explorer and selecting Add > SharePoint Mapped Folder. Note the 14 hive’s WebServices folder at the bottom of the list.
Next, I’m going to expand the newly created WebServices mapped folder and right-click on the AutocompleteDemo folder below. From the context menu, I select Add > New Item. In the Add New Item dialog, I select the WCF Service template and name the new file YouCompleteMeService.cs.
I’m going to move the App.config file that was added automatically to be in the same folder as YouCompleteMeService.cs. Then I rename App.config to web.config and delete its contents. I’m going to create my own configuration file. In the web.config file I’ll turn on aspNetCompatibilityEnabled, define a default endpoint for our WCF service, and also turn on enableWebScript for AJAX compatibility. Refer to the accompanying sample project for the complete web.config listing.
For some reason, Visual Studio 2010 doesn’t automatically add a WCF Service Host declaration file to the SharePoint Project for me. At least in the VS2010 Beta, I’ll have to add this file manually. To do so, I just add another file to the AutocompleteDemo folder below WebServices mapped folder in the project. I select a Text file as the file type and name it YouCompleteMeService.svc. This Service Host file will only contain a few lines declaring the service and its factory.
I’m going to delete the YouCompleteMeService.cs, as I won’t be using it.
Now, I’ll add two more classes named AutoCompletionServiceApplicationHostFactory and AutoCompletionServiceApplicationHost to the root of the project. AutoCompletionServiceApplicationHostFactory inherits from ServiceHostFactory and overrides the CreateServiceHost method.
AutoCompletionServiceApplicationHost inherits from System.ServiceModel.ServiceHost and implements both the IFormattable and IDisposable interfaces.
Next, I expand the Features folder of the AutocompleteDemo Visual Studio project and right-click on Feature1. From the context menu, I click Add Event Receiver. In the newly created Feature1.EventReceiver.cs class, only the FeatureActivated method is salient to this application. In the FeatureActivated method, I check to see if an AutoCompletionService object has ever been created, and if not create it. Only one local AutoCompletionService will ever be needed. After an AutoCompletionService has been created for the first time, SharePoint’s service application management will become aware of the new service application and allow administrators to create or manage instances of the Auto Completion Service Application from Central Administration. I’ll make the admin pages to create and manage our service application in Part 2.
Part Two – The Service Application’s Admin Interface