Last week I attended a follow-up meeting with the staff of a local customer that had just completed a major deployment of SharePoint Services. The results, as the CIO reported to me that morning, were a very excited IT department that had seen a rapid adoption of SharePoint across their global enterprise. He said the purpose of the meeting was to focus on additional ways they could use SharePoint within their application infrastructure. The CIO explained how they had a variety of Windows Forms and Web-based applications that needed access to the data that appeared to be locked within their multiple SharePoint databases.

Up to this point their developers had been unable to either access or successfully integrate any of this data with anything other than their SharePoint sites. While I listened, it became clear that this meant leveraging the extensive Web service infrastructure available within SharePoint. In this article, I will explain, as I did that morning, how this built-in set of Web services exposes a variety of portal and data services to any application capable of connecting and consuming Web services.

The Infrastructure Design
The SharePoint Services infrastructure (see Figure 1) is defined as a common set of .NET application components built on top of Windows Server 2003. This set of services is composed of two closely related applications - Windows SharePoint Services (WSS) and SharePoint Portal Server (SPS). WSS provides the core application components designed to provide team-based collaboration features, and a variety of application services that include document management and site creation. SPS on the other hand is a server add-on product that extends WSS and is designed for the creation of enterprise portals environments. Although SPS offers additional enterprise-grade capabilities it leverages the features and functionality of WSS for most of its core services.

Being built on a common architecture allows both WSS and SPS to take advantage of the same SQL Server 2000 content store. These back-end databases are used to store all site content, including documents, list data, and Web Part properties, as well as user names and rights. By their design these content database servers are not identical and this allows a distributed enterprise portal structure. It is important to remember that all data for a specific site resides in only one content database. SQL Server 2000 as the database engine provides backup and failover protection to prevent the entire service from being interrupted when any single database server fails. Depending on the topology. the configuration database handles all administration of the deployment, directing requests to the appropriate content store and managing load balancing for each back-end database.

Any time the front-end server receives a request for a page in a particular site, it checks the configuration database to determine which content database contains the requested site data. In a server farm running Windows SharePoint Services, the front-end Web servers are stateless clones. A request can be routed to any Web server through load balancing, and any site can be served by any Web server. The Web server connects to a back-end database to retrieve data so that it can construct and return the Web page to the client. If any Web server fails within a server farm, requests can be routed to other Web servers. The most obvious benefit of this configuration allows the addition of capacity to the deployment by adding more Web servers. It is always important to remember that documents and other end-user data are not stored on the Web servers but within the specific back-end content and configuration databases.

Where Are the Services?
As they started to consider the possible locations that their data could be stored it became obvious that Web services were the answer. SharePoint Services provides a variety of Web services that enable the easiest way to find and retrieve enterprise data. These location-independent interfaces are able to both locate and retrieve data requests regardless of the actual data storage location. By default SharePoint provides Web service within the Microsoft.SharePoint. SoapServer namespace. This namespace is physically contained in the Microsoft.SharePoint.dll.

This namespace implements the server-side interface for calling SharePoint-based XML Web services. It contains classes that implement the Windows SharePoint Services Web service and Web services for working with Web Part Pages and Web Parts. In addition, most of the methods within the defined classes are not designed to be called directly from the server but remotely from client applications. The Simple Object Access Protocol (SOAP) interfaces used in these services provide .NET developers with object models that are used to create solutions that work with both WSS and SPS. Table 1 shows the classes of the Microsoft.SharePoint.SoapServer namespace and a brief description of each.

As shown in Figure 2 the SharePoint Web services ASMX pages are stored within IIS in either the _vti_bin virtual directory or _vti_adm of the SharePoint directory. These directories are mapped to the physical path of Local_Drive:/Program Files/Common Files/Microsoft Shared/Web Server Extensions/60/ISAPI in the server file system.

SharePoint implements a variety of Web services (see Table 2). As with any .NET Web service you can access the default Documentation Handler for any of these Web services by entering the Web service URL:

http://Virtual_Server/[sites/][Site_Name/][Subsite_Name/]_vti_bin/Service_Name.asmx

Any methods that are part of the Administrative service specify a path that goes to the administration port and uses the _vti_adm as the virtual directory, as shown in:

http://Virtual_Server /_vti_adm/Admin.asmx

Within the browser you can review the different methods and service Descriptions of any of the Web services. For example, Figure 3 shows the default documentation handler for the Lists.asmx Web service.

Making the Connection
By far the most common Web service to leverage is the Lists Web service. Lists are probably the most pervasive user interface within SharePoint Services. The Lists.asmx service provides direct access to retrieving and updating any list collection maintained within SharePoint. To create a reference within a Microsoft Visual Studio .NET project to a Web service in Windows SharePoint Services, right-click References in Solution Explorer and click Add Web Reference in the shortcut menu. For example, Figure 4 shows adding a reference to the List Service.

Once the Web Reference is created you are ready to access the List Service. For example, the GetListCollection method of the Lists service returns the names, URL, and Globally Unique Identifiers (GUIDs) for all the lists contained in a site. Listing 1 can be used to retrieve all the current lists and schema information from the top-level portal site.

As you can see from Listing 1, the first thing we need to establish is credentials for the current security context in which the application is running. This can be done by adding the following code, which authenticates the current user by passing their default credentials to the Web service from the system credentials cache.

listService.Credentials = System.Net.CredentialCache.DefaultCredentials

The CredentialCache is used to store system credentials for Internet-based resources. By default, when the System.NET.Credential Cache.GetCredentials method is called this compares the URI authentication type provided with any stored in the cache and returns the first set of matching credentials. The DefaultCredentials property is used to represent the system credentials for the current security context in which the application is running. For client-side applications, these are typically the current users' Windows credentials. However, within ASP.NET applications these default credentials are either the logged-in user, or the current user being impersonated. It is also important to remember that this property only applies to NTLM, negotiate, and Kerberos based authentication.

Retrieving List Data
The GetListCollection method of the Lists service returns the names, URL, and GUIDs for all the lists in the current site using an XML node fragment based on the Collaborative Application Markup Language (CAML). CAML is an XML based meta-language that is used extensively within both WSS and SPS to define sites, lists, tables, views, and forms. As an XML-based structure we can easily interrogate and inspect the return values within the XML Structure. One of the most important pieces of data being returned is the GUID that uniquely identifies each list within SharePoint Services. This GUID represents the unique identity of the SharePoint list.

At this point one of the developers in the room spoke up and asked about a contact list for sales prospects he had been working with. Now that we were able to get the GUID as the list unique identifier he wanted to retrieve the entire list of contacts based on a query. Listing 2 is an example that we came up with using the GUID returned from the above code and a CAML query to return the list of specified contacts.

As the meeting started to wind down, I began looking around the conference room at the now smiling group of developers. This once frustrated group had finally come to understand how they could easily integrate and extend their portal infrastructure using Web services. I noticed how they had feverishly been taking notes and shaking their heads in agreement throughout the meeting. It became obvious from their comments that they were just beginning to explore the myriad of services offered within SharePoint Services.

Of course, throughout this article and that meeting we only covered a very small portion of the things you can do with these Web services. The rest is up to you to explore.