SharePoint’s _layouts directory is an ideal place to deploy code that extends every SharePoint site. This path is virtualized and exists as a subpath to every SharePoint site’s URL. For example, a SharePoint site that exists at the URL http://mysharepointserver/myorg/myteam would be able to access the layouts virtual directory through the URL http://mysharepointserver/myorg/myteam/_layouts/. This directory is served entirely through the file system and is mapped to the file path Program FilesCommon FilesMicrosoft SharedWeb Server Extensions12TEMPLATELAYOUTS. SharePoint uses files in this location for managing sites and for any resource or Web page that is part of every site. The layouts directory is also an ideal place to serve JavaScript files, CSS files, images, and Web service endpoints such as WCF SVC files.

In the sample code in this chapter, we’ll create the folder SOAjax.Services in the layouts directory to host our WCF endpoints and the folder SOAjax.Script to host the client runtime for our AJAX applications. Code that is run in the _layouts directory should be deployed to the global assembly cache (GAC).

Tip

A similar directory to layouts is the _vti_bin directory, which is virtualized just as layouts and is used by the SharePoint Web service API. This directory is located at Program FilesCommon FilesMicrosoft SharedWeb Server Extensions12ISAPI and is available through the Web-relative URL http://sharepointserver/mysharepointsite/_vti_bin/. As with code deployed to the layouts folder, you should create subdirectories for custom code and include your own web.config file for WCF configuration. Although some developers prefer _vti_bin, I’ll use _layouts in this chapter.

SharePoint includes support for ASMX services and has a relatively complete set of ASMX Web services. Unfortunately, these Web services aren’t AJAX enabled, and in many cases they aren’t very JavaScript friendly either. SharePoint also includes a URL protocol that implements a Web-style API. (For details on this, search on the Web for "SharePoint URL Protocol.")

To create a custom Web service API in SharePoint, there are three recommended options: WCF, ASMX, and HTTP handlers. Each option has its own benefits and drawbacks. ASMX Web services are used throughout the product itself, but this option isn’t recommended for developing new code. WCF is particularly challenging to integrate into the SharePoint environment. It might not be the best approach for commercial applications built on the current release of the SharePoint platform (as of service pack 1), but it is the best long-term approach. WCF is the most flexible option for developing service-oriented APIs for SharePoint. While WCF is not fully supported in the current release, it will be included in future releases.

To support WCF, additional configuration must be deployed to the SharePoint runtime. If you have full control over the SharePoint server, WCF is an option to consider. However, if you are creating and reselling third-party solutions, be cautious about taking a WCF approach within the SharePoint environment. If you are creating REST service endpoints serving XML content, you can still use WCF attributes to define the contract and simply wrap the service in an ASP.NET handler. This is the approach we’ll take in this chapter, and with this approach, you gain the benefits and flexibility of the WCF Web programming model without any configuration changes to the SharePoint runtime.

With an HTTP handler wrapping the WCF endpoint, you can easily move from HTTP handlers to WCF endpoints using the Web programming model without any change in functionality. HTTP handlers and handler factories can be registered through web.config, in the httpHandlers node. Using this technique (which was demonstrated at the end of Chapter 2), an IHttpHandlerFactory is created in an assembly and registered to a handler mapping in web.config. HTTP handlers can be used to wrap WCF Web service classes, giving you a great future-proof solution. I’ll demonstrate this technique throughout this chapter. First, you will see how to create a WCF service, including the data contract. Then you will wrap the service implementation with an HTTP handler using DataContractSerializer. With this technique, it’s trivial as to which technology services the request (HTTP handlers or WCF) because it is processed in the same manner.

To run WCF in the SharePoint application, you must alter the SharePoint runtime through a custom virtual path provider. This technique and instructions for integrating WCF with full access to the SharePoint site context is described in the document "WCF Support in SharePoint" available on the book’s companion content Web site at http://www.microsoft.com/mspress/companion/9780735625914. After WCF support is enabled, WCF must be run in ASP.NET compatibility mode as documented in Chapter 2. Because of this, I favor using an HTTP handler and wrapping the service implementation in the handler, but I’ll also demonstrate the WCF approach. You can run the same code samples through WCF endpoints by deploying an SVC file that utilizes WebServiceHostFactory.

More Information

In the code download for this chapter, support for WCF can be added to SharePoint by adding a specialized VirtualPathProvider to the SharePoint runtime through a custom HTTP module. The document "WCF Support in SharePoint," included in the book’s companion content, provides instructions for configuring WCF support in SharePoint.

The most common way to extend SharePoint is by adding Web Parts. (You can also add pages without Web Parts using SharePoint Features, which is the recommended approach for full-page AJAX applications, but I won’t cover Features in this book.) Web Parts exist as classes that inherit from System.Web.UI.Controls.WebPart and are a pre-AJAX technology deeply rooted in the SharePoint platform. Code for Web Part applications must be deployed to the GAC or the Web application’s bin directory, just as you would deploy code to a typical ASP.NET Web application. Web Part assemblies and namespaces must also be registered in web.config, and they can be added to the Web Part gallery through the Sites Settings link from the root-level SharePoint site.

If you’re new to SharePoint, you’ll want to read the sidebar "Setting up the SharePoint Developer Environment," but seasoned SharePoint developers probably want to skip to the section "Deploying Code Through Web Parts."

Setting up the SharePoint Developer Environment

The recommended SharePoint development environment is an instance of Windows Server 2008 or Windows 2003 Server running Windows SharePoint Services 3.0 or MOSS. While WSS is available as a free download from http://microsoft.com/SharePoint, Windows Server is required to run it. Before you get started, identify an instance of Windows Server for your development environment, either in a virtual environment or a dedicated computer, with Visual Studio 2008 installed as your development environment. The following steps apply to an environment with Windows SharePoint Services 3.0 fully installed.

Tip

While you can run Windows Server as a virtual environment on a product such as Virtual PC, I prefer to run Windows Server 2008 as my main development operating system. This can be an ideal platform for development and everyday use if you have access to a license through the Microsoft Developer Network.

After installing SharePoint and configuring a default Web application (which is done for you in a basic installation), the following steps configure the SharePoint instance for development by enabling debugging and full trust. These steps are intended for development only. Experienced SharePoint developers will not want to run in full trust but to configure CAS (code access security) from an installation package.

First you should enable error messages in the layouts directory. (I’ll talk about the layouts directory soon). To do this, open Program FilesCommon FilesMicrosoft Shared Web Server Extensions12TEMPLATELAYOUTSWeb.config, and set customErrors to "Off":

<customErrors mode="Off" />

Next open the Web application’s Web.config file. This file will exist in the root of your SharePoint Web application. By default, it is located at inetpubwwwrootwssVirtualDirectories80, although this could be a different path depending on your configuration. There will be multiple directories in this path, with one that is used for the SharePoint Central Administration application. The folder you want to edit is the one used by the Web application you are targeting. To verify the location of the Web application, view the Web site properties in IIS Manager. Make the following changes to the SharePoint Web application’s web.config file:

1. Set trust to Full. For production applications, you should create a custom trust level for your code, although that is outside the scope of this book.

   <trust level="Full" originUrl="" />

2. Set customErrors to Off:

   <customErrors mode="Off" />

3. Enable full error messages by enabling the call stack in the SafeMode element:

   <SafeMode MaxControls="200" CallStack="true" DirectFileDependencies="10"
   TotalFileDependencies="50" AllowPageLevelTrace="false">

4. Enable AspNetCompatibilityMode for WCF. Add the following element at the end of Web.config, just before the close of the configuration tag:

   <system.serviceModel>
       <serviceHostingEnvironment aspNetCompatibilityEnabled="true" />
   </system.serviceModel>

   Because the SharePoint object model is designed to run as an ASP.NET Web application with full code impersonation, enabling ASP.NET compatibility mode allows the WCF code to run and behave just as native SharePoint code.

5. Add the following handler element to the httpHandlers node, which is used by ASP.NET to serve the Microsoft AJAX Library script files:

   <add verb="GET,HEAD" path="ScriptResource.axd"
       type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions,
       Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
   validate="false"/>

6. Finally, for all projects that contain Web Parts or controls that will be added to an ASP.NET page, you need to add a SafeControls entry. The SafeControls entry allows your code to execute. Because anyone with rights can create page content in SharePoint, SharePoint adds this safeguard to ensure that users don’t create content that bypasses security and runs arbitrary code on the server. The virtualized SharePoint application runs in safe mode, meaning that only controls that are registered on the server through a SafeControls entry can execute.

   <SafeControl Assembly="SOAjax.SharePoint" Namespace="SOAjax.SharePoint"
       TypeName="*" Safe="True" AllowRemoteDesigner="True" />

Tip

Code for this book is available online at http://www.microsoft.com/mspress/companion/9780735625914. The code for this chapter is in the file Chapter 11.zip. This chapter’s code requires Windows SharePoint Services 3.0 either on Windows Server 2003 or Windows Server 2008. On Windows Server 2008, you will need to run Visual Studio as an administrator to work with this chapter’s code samples.