Help
Customizing WCF Services in SharePoint 2010
SharePoint 2007 provided the capability to add custom ASMX web services. Web Services could be deployed to the LAYOUTS folder, or could be deployed to the ISAPI folder and supported accessing site settings and list data under the SharePoint user context. Since SharePoint 2007 was built on the ASP.NET 2.0 model, it did not natively support web service enhancements that were introduced with Windows Communication Foundation (WCF) in .NET Framework 3.0 and 3.5 or the additional WCF-based service frameworks like ADO.NET Data Services (now WCF Data Services).
For those familiar with writing custom ASMX services for 2007, there were some pitfalls. Since SharePoint requires dynamic service endpoints (the ability to call the web service using any site-relative virtual path under the /_vti_bin/ folder), you had to hand-tool your WSDL files to dynamic service locations. This had to be done every time your changed your web-service signature. Not terribly complicated, but certainly tedious.
The good news is that SharePoint 2010 is based upon ASP.NET 3.5 and now supports WCF custom services including SOAP, REST, and WCF Data Services. The even better news is that is makes it easy to deploy custom WCF services with dynamic endpoints by supporting a number of custom Service Host Factory implementations that can auto-generate. This means it is not necessary to modify the SharePoint web.config to deploy your service endpoint configurations. In this article, I will walkthrough and highlight the important aspects of the SharePoint 2010 support for custom WCF services.
Step 1: Create a VS2010 Empty SharePoint Project
Visual Studio 2010 now includes templates for developing just about every type of SharePoint customization including Web Parts, List Handlers, custom Site Definitions, List Templates, etc. It does not include a template for a SharePoint Web Service, so we will want to start with the Empty SharePoint Project template. The will automatically create a project that includes references to the core Microsoft.SharePoint assembly, and includes special capabilities for defining Features, and automatically packaging and deploying your solution as a WSP.
NOTE: Make sure to select a Farm-Tr.
To support a custom WCF we need to perform a few additional steps:
- Add a reference to the Microsoft.SharePoint.Client.ServerRuntime assembly. This assembly contains the Service Host Factory classes, as well as some attributes we need later on.
- Add a SharePoint Mapped Folder to the ISAPI folder, and create an empty text file with the .SVC extension. Note that it is always a good practice to create a sub-folder when deploying your custom code to the SharePoint file system. It helps keep you custom code separate from the original installed files.
Step 2: Add Your Service Contract and Implementation
The next step is to add the WCF service contract and implementation. For my sample, I have written a very simple service that returns the Url of the current SharePoint context. This is a good way to verify that the service endpoints generated for us by SharePoint are dynamic.
The important thing to note here are the attributes required on the implementation class. These attributes allow SharePoint to automatically support metadata exchange endpoints, and is the secret sauce that allows us to develop custom WCF services without having to deploy endpoint configuration to the SharePoint web.config.
Step 3: Configure Your Service Host Definition
IIS-hosted WCF services are registered using a special content file (.svc files) that contain a processing instruction that allows the WCF infrastructure to activate the service to respond to incoming messages. The primary attribute in the ServiceHost processing instruction is the Service attribute that defines the type name and assembly or code-behind reference for the service.
The Microsoft.SharePoint.Client.ServerRuntime supports a number of service host factory classes depending on whether you are implementing SOAP, REST or WCF Data Services:
- SOAP = MultipleBaseAddressBasicHttpBindingServiceHostFactory
- REST = MultipleBaseAddressWebServiceHostFactory
- Data Service = MultipleBaseAddressDataServiceHostFactory
SharePoint custom WCF services need to utilize one of these factories to dynamically generate the service endpoint during execution. In my sample, below I have selected the service factory for a SOAP web service.
The important element of defining your service host is to include the Factory attribute and select the appropriate service host factory class for your implementation.
Step 4: Build, Deploy, and Test Your Service
One of the benefits of the new SharePoint 2010 templates in Visual Studio 2010 is that they now support automatically packaging and deploying your solution as a WSP.
When you are ready to test your custom service, right-click on the project node, then select Deploy from the menu. Your assembly will be automatically deployed to the GAC, and your .SVC file will be deployed to the SharePoint ISAPI folder. When it comes time to deploy to production, you can just pass your WSP file to your SharePoint Administrator and he can easily add your solution to the SharePoint farm.
One of the easiest ways to quickly test if your service is working is to access the service from a browser and verify that it is correctly generating the WSDL for our service (if you are deploying a SOAP service).
Open your browser and browse to:
http://yoursite/_vti...ervice>.svc/MEX
You need to be sure to include the /MEX at the end since the service being deployed is using a Metadata Exchange Endpoint.
Step 5: Invoke Your Service from an Application
The last step is to invoke your service from an application. InfoPath has native support for invoking data connections that call SOAP web services. In InfoPath 2010, RESTful services are also now supported.
In the following sample, I created a simple console application.
SharePoint 2010 has dramatically improved the developer experience for accessing SharePoint from applications including the new RESTful ListData service, the Client Object Model, and the ability to extend SharePoint with our own custom web services using the latest flavors of SOAP, REST and WCF Data Services.
In this article I demonstrated that the new Service Host Factory classes make developing custom services considerably more powerful, flexible and convenient than ASMX services in SharePoint 2007. The out-of-box ASMX services and custom ASMX services are still supported on SharePoint 2010, but I expect that most developers will want to take advantage of the new WCF support and move up to .NET 3.5.
Source Code: SharePointBits.Samples.WCFService.ZIP
Chris Beckett is the author of the forthcoming Microsoft® SharePoint® 2010 Plain & Simple (Microsoft Press).
