As one of its extensibility mechanisms, Microsoft Office SharePoint Server 2007 (MOSS) offers a number of Web Services. Web Services are a critical part of a service-oriented architecture, enabling remote and heterogeneous systems to interact effectively. The Web Services that come with MOSS provide an easy way to access and manipulate data within SharePoint while maintaining security and supportability of the system. They are fairly simple to use and understand, but due to their simplicity, they may not be as optimized as a custom set of Web Services, which can provide different sets of operations.

So, what are Web Services? In short, Web Services are a set of standards and protocols that enable software systems to exchange information via XML. Web Services have been “in the works” since 1998 under a variety of names—for example, XML RPC and SOAP. The main reason for the tremendous growth of Web Services is how easy it is to understand the protocols and formats involved. Interoperability is also a major selling point. Web Services, unlike many previous attempts at distributed computing, made it possible for mainframes to talk to Unix-based applications or for Unix to talk to Windows applications. As a result, Web Services became a de-facto standard for exposing connectivity to an application. Each Web Service will typically expose its interface description, via the Web Service Definition Language (WSDL), and then implement a Simple Object Access Protocol (SOAP)–based endpoint capable of interpreting incoming messages in XML format (the request) and returning XML data back (the result).

That said, you might ask the following: when and why would anyone choose to use Web Services to interact with MOSS? The standard MOSS and WSS sets of APIs that are typically used to build Web Parts and ASP.NET applications can only run on a machine where WSS or MOSS is actually installed. Hence, Web Services are practically the only way that someone can access MOSS data from a remote machine. Whenever MOSS is the definitive source of data, or even just metadata, web services should be utilized as the integration mechanism of choice. MOSS Web Services are typically used for integration with desktop applications that connect to the collaborative workspaces, as integration to some line-of-business applications that may track a status of a workflow, or just for looking up data in a list.

What about the reverse? What are the technologies that allow consumption of external data within MOSS? There are several, including the following that are associated with Web Services:

With the foundation of Web Services firmly set, now we’ll focus on the detailed capabilities and usage of the Web Services within MOSS. At the end of this chapter you will be able to:

As platforms, WSS and MOSS are built on a staggering amount of reusable elements and features, which translate into a fairly large number of Web Services. Overall, there are more than 26 documented Web Service definitions, plus various Web Services for additional Application Services (e.g., for SlideLibrary functionality), and the endpoints are typically dynamically structured. That is, the access to the endpoint provides an implicit context to the location within the MOSS portal or web site. It is probably impractical to go into the detail of every single Web Service. Instead, after a brief introduction, we’ll focus on the commonalities between the Web Services and how to harness them.

There are 20 core Web Services that are associated with WSS (see Table 26-1, later in this chapter). As WSS is the heart and soul of MOSS, these Web Services provide the first level of data access. The majority of the Web Services are located at the \_vti_bin absolute directory, as seen in Figure 26-1. However, the services are also accessible from a relative directory as well. For instance, if there is a site in a location sitesHR, there would be access to the web services via sitesHR\_vti_bin. These directories, as seen in IIS in the figure, are essentially virtual directories that map to a directory within the WSS 12 hive on the physical filesystem: C:Program FilesCommon FilesMicrosoft Sharedweb server extensions12ISAPI. It is worth noting that these services run under the same application pool as the portal, but they have their own web.config file.

Figure 26-1. Web Services in IIS

The main exception to this rule is the Administration Web Service, which is installed within the administration site. The Administrative Web Service exists within the \_vti_adm virtual directory that corresponds to the C:Program FilesCommon FilesMicrosoft Sharedweb server extensions12ADMISAPI physical directory. When browsing for the Web Services within IIS, the browser starts from the root directory, and you can only use the web browser to study the structure of the Web Service endpoint, as seen in Figure 26-2. Based on the standard configuration, these Web Services cannot be called with HTTP Post or HTTP Get commands, and you must use real SOAP commands even to test the service—not a very friendly approach for a developer.

Figure 26-2. Copy Web Service documentation

Looking at the files inside IIS, you can see that for each Web Service—for example, alerts.asmx—there are two additional files: alertsdisco.aspx and alertswsdl.aspx. These are two additional ASP.NET pages that would be used for integration with development applications. The first simulates the older .disco files, and the second simulates the dynamically generated WSDL definition, which, in the case of MOSS Web Services, is static. There are also some other Web Services that are not documented.

A brief study of the MOSS Web Services shows that they partially mimic the standard object model of WSS and MOSS, and as such, enable drill-down into data by successive calls to the site, web, and list Web Services if necessary. In order to use them, the programmer should be familiar with the SharePoint object hierarchy as well as any nuances of navigating the structure. Unlike in a pure object-oriented (OO) model, where one object or collection can instantiate another, in the Web Services world, you have to instantiate and create each object explicitly and then request it. Due to the granular nature of the Web Services, the developer sometimes has to make several invocations before being able to get the data or a method, which is somewhat tedious compared to standard OO practices.

Table 26-1 provides an overview of the available web services.

The most commonly used Web Services are List Data Retrieval Web Service, Site Data Web Service, and Lists Web Service. For instance, the index server uses Site Data Web Service internally while performing a server crawl. Each Web Service represents a unique aspect of WSS, and in most cases, different services will be used for specialized tasks.

The Web Services that are associated purely with MOSS are defined in Table 26-2.

Key Elements and Data Structures

Full discussion of all different classes and members would be overly repetitive, and would not add value to the already available WSS SDK. Just looking at some of the more popular Web Services, such as Lists in Figure 26-3, and a sample operation, Get Lists, as in Figure 26-4, shows the volume of information that each developer would have to process to learn all the details.

Figure 26-3. Operations and methods of the Lists Web Service

Thus, the question is how to simplify and distill this information in order for it to be useful in the long run. First, you need to familiarize yourself with the basic descriptions of these Web Services, and then mentally map them to the features and elements of WSS and MOSS. Once you are comfortable with this notion, you can further group and divide these based on their functionality and the type of operation they perform: do they represent an object within WSS, or are they a specialized class for data retrieval?

Once you look at the Web Service descriptions and peek at their operations, either online or via the SDK, the intent of their use becomes transparent. For instance, many people associate the People, Permissions, and Users Web Services with common user and security administrative activities, whereas Site Data, Webs, and Lists are typically used for management of sites and their metadata, as well as manipulation of list data. The next commonly used Web Services are Search (or SPSearch. asmx) and List Data Web Services, which are used to retrieve data. Clearly, the choice of a Web Service depends on your end goal.

Figure 26-4. The GetList operation of the Lists Web Service

Tip

But what about file operations? Where are they? There is the Versions Web Service’s AddAttachment operation, but nothing really specific to file upload and download. Unfortunately, Web Services as a technology is not an ideal choice for transporting large binary chunks of data. Instead, there is a different API, FrontPage RPC, discussed later in the chapter.

After looking at each Web Service, you can further explore each operation by clicking on it (as in Figure 26-4). Here you will be able to see typical Request and Response SOAP envelopes. Additionally, you can see placeholder information and its type within each operation, which gives a fairly good hint about the information that is expected. The Response part of the operation unfortunately needs a bit more explanation. The majority of the Responses contain fairly complex data, and the on-screen text, as seen here, simply does not provide detailed information:

	<GetListResult><xsd:schema>schema</xsd:schema></GetListResult>

Fortunately, the WSS and MOSS SDKs contain significant amounts of documentation on Web Service Request and Result details, including great code samples and sample complex schema structures that may be required of or returned from each Web Service. For operations that are not documented, use of the right tool or perhaps some light coding will typically help you understand the underlying data. There is simply no substitute to the way MOSS Web Services are treated in Visual Studio 2005.

Tip

Do leverage the WSS SDK on its own, as it is not included in the MOSS SDK. Throughout this chapter, the Web Services that are listed as WSS Web Services are found in the WSS SDK only, and you will not find them in MOSS documentation.

Calling a Web Service method is one of the best ways to learn about its behavior and data. Although some of the operations may require a fairly complex request envelope, there are plenty of tools that can make this easy. With some of the Web Services, it is also possible to invoke a Web Service directly from InfoPath, or even create an application where the user can enter data that is passed on as a request to the Web Service. The magic of InfoPath lies in its ability to work with WSDL, and its ability to automatically create and lay out form elements based on an XML schema contained in simple WSDL.

In cases where WSDL uses more complex schemas to describe the Request and Response formats, programmers move up to more advanced tools, and eventually work with Visual Studio. Some of the Web Services, such as the Query Web Service or Site Data Web Service, utilize a lot of dynamic XML to specify parameters and then return dynamic XML based on the requested parameters.

Let us approach this by looking at some sample structures and same common data elements that are often used by different Web Services to retrieve data. Other elements tend to reflect the .NET object model in terms of their structure (Table 26-3).

	<Query>
	 <Where>
	  <Or>
	   <Eq>
	     <FieldRef Name="Author" />
	      <Value Type="Text">Piotr</Value>
	   </Eq>
	   <IsNull>
	     <FieldRef Name="Published"></FieldRef>
	   </IsNull>
	  <Or>
	 </Where>
	</Query>

	<ViewFields>
	 <FieldRef Name="ID" />
	 <FieldRef Name="Title" />
	 <FieldRef Name="Author" />
	 <FieldRef Name="FileLeafRef" />
	</ViewFields>

	<QueryOptions>
	<IncludeMandatoryColumns>TRUE</IncludeMandatoryColumns>
	   <DateInUtc>TRUE</DateInUtc>
	</QueryOptions>

The resulting response for most of the data queries also follows the familiar CAML format, which is actually very similar to the XML results provided in the .NET API from the SPListItemCollection (Table 26-4).

Using WebService Studio

Without a generic Web Service desktop application capable of speaking SOAP, it would be hard to inspect the functionality and inner workings of Web Services, especially in light of the big XML blobs just mentioned. Also, very few people are capable of reading the documentation and using everything as is. Luckily, there are many tools that are capable of dynamically reading the WSDL definition. For example, WebServiceStudio 2.0 is provided by the GotDotNet web site. When used to execute the same GetListCollection operation, you can see the request/response parameters in a friendlier format (Figure 26-6).

Figure 26-5. InfoPath designer as client to Web Services

Figure 26-6. WebService Studio

Warning

GotDotNet will be phased out by July 2007, but currently the direct access to the WebService Studio is:

http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=65a1d4ea-0f7a-41bd-8494-e916ebc4159c.

WebService Studio has several screens allowing the operator to utilize and look into different features while working with a Web Service (see Table 26-5).

Table 26-5. WebService Studio screens

Screen/Tab	Description
Invoke	Displays all operations of a web service, and allows the user to enter values to execute any of the operations, as well as to explore results in a tree-like structure.
Request/Response	Displays details of a SOAP request and a SOAP response, including any errors. If a Web Service calls, and the application shows an Error message; clicking Continue will allow you to inspect the nature of the error on this screen.
WSDL & Proxy	Displays all details of a WSDL definition, breaking it down into operations, elements, and endpoints.
Messages	Displays any messages that are executed during the execution. Essentially, this is nothing more than an application log.

WebService Studio, as well as other commercial tools, such as XMLSpy or Stylus Studio, allow for a quick inspection of a Web Service’s internals. Some of the tools work better than others, but generally they are worth their weight in gold. Instead of spending 5–20 minutes writing code to figure something out with Visual Studio, the tools let you know what each Web Service is capable of delivering in a very short time. These tools are also useful when you’re not necessarily interested in writing a full .NET application. You can use these tools if you already have an application that can handle XML and Web Services, and you’re simply interested in figuring out sample data and an XSLT transformation.

Suppose you’re looking to retrieve some Contacts data to use with a Web Part on another server, or perhaps another application simply requires information stored in a typical Contacts list (I’m assuming you have only some of the data, such as the GUID):

1. Open WebService Studio, or your favorite application.

2. Point to the WSDL file, and enter http://servername/sitepath/_vti_bin/sitedata.asmx?WSDL”.

3. Retrieve the WSDL by clicking the Get button.

4. Select the GetListItems operation.

5. Select the strListName element, and enter a GUID of a list as its value.

You can retrieve a GUID of a list by executing the GetListCollection method. By clicking Invoke, the results are populated with all lists. Next, you can find the Contacts list by looking at list Title elements, and retrieve the list’s GUID, or its InternalName:

1. Press Invoke.

2. The Output section shows a single Results string, as the data inside represents the dynamic XML.

3. Selecting the Request/Response page, you can see the detailed response within the GetItemsResult element, similar to the XML results shown here and in Figure 26-7:

   	<xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'
   	     xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'
   	     xmlns:rs='urn:schemas-microsoft-com:rowset'
   	     xmlns:z='#RowsetSchema'>
   	<s:Schema id='RowsetSchema'>
   	   <s:ElementType name='row' content='eltOnly' rs:CommandTimeout='30'>
   	      <s:AttributeType name='ows_ID' rs:name='ID' rs:number='1'>
   	         <s:datatype dt:type='i4' dt:maxLength='4' />
   	      </s:AttributeType>
   	...
   	   </s:ElementType>
   	</s:Schema>
   	<rs:data ItemCount="60">
   	   <z:row ows_ID='3' ows_ContentTypeId='0x010100424AAB20493AB5479311D949BB3EFCFF'
   	...
   	ows_RepairDocument='0' />
   	</rs:data>
   	</xml>
   

WebService Studio and related tools allow you to monitor low-level communication between the client and the server and may help you troubleshoot and understand the resulting XML.

Changing a Web Service Configuration with MOSS and IIS

The default configuration of Web Services within WSS and MOSS is quite different from a standard ASP.NET Web Service, which typically allows greater leeway in terms of using different protocols and also uses the default authentication.

Since Web Services primarily represent external connectivity as well as interoperability, you should be aware of their capabilities:

• They only support SOAP and SOAP12, and there are no HTTP POST or HTTP GET endpoints.

• Their authentication is configured to follow MOSS, which is typically NTLM or Kerberos and may not work well with other SOAP stacks.

Figure 26-7. SOAP Request and Response in WebService Studio

There is no real supported way to use HTTP POST and HTTP GET because of the web.config settings and the static definition of the WSDL. In web.config:

	<protocols>
	  <remove name="HttpGet" />
	  <remove name="HttpPost" />
	  <remove name="HttpPostLocalhost" />
	  <add name="Documentation" />
	</protocols>

And finally, within the WSDL we have only two ports declared that support SOAP and SOAP12 bindings. Here is a snippet from alertswsdl.aspx:

	  <wsdl:service name="Alerts">
	    <wsdl:port name="AlertsSoap" binding="tns:AlertsSoap">
	      <soap:address location=<% SPHttpUtility.AddQuote(SPHttpUtility.
	HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> />
	    </wsdl:port>
	    <wsdl:port name="AlertsSoap12" binding="tns:AlertsSoap12">
	      <soap12:address location=<% SPHttpUtility.AddQuote(SPHttpUtility.
	HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> />
	    </wsdl:port>
	  </wsdl:service>

Next is the matter of providing good access to clients. As long as the Web Service clients are within the MS Windows and Active Directory sphere of influence, there is probably nothing to worry about. However, providing proper access to other platforms brings forth the questions of authentication and security.

Authentication methods are configured within IIS, as seen in Figure 26-8. To modify authentication settings:

1. Open the IIS management console and navigate to the web site you’d like to configure, or a virtual directory.

2. Right-click the node and select Properties from pop-up menu.

3. Select the Directory Security tab.

4. Click the Edit button of the “Authentication and Access Control” section.

5. Change the Authentication Methods here.

Figure 26-8. IIS Authentication configuration

The optimal method for configuring a dual type of access typically requires using two virtual servers pointing to the same database, each configured with a different setting:

• Virtual server 1 should use Integrated Windows Authentication.

• Virtual server 2 should use Basic Authentication and be configured for SSL if the access needs to be secure.

Warning

Don’t change the authentication settings for the _vti_bin virtual directory to Basic Authentication, as the Search element of MOSS uses Web Services. Changing the settings at a directory level may break Search.

Also, when exposing your server to the Internet, configure SSL to ensure that the communications and passwords are not exposed.

The last common problem with use of Web Services is proper authorization. Whereas a site administrator would readily configure access for individual user accounts, Web Services tend to access it behind the scenes, and occasionally they may not have access to data, purely due to a simple omission. In this case, the Web Service access should be granted the same way that a MOSS search account (a non-expiring service account) is configured, via Policy for Web Applications:

1. Open Central Administration.

2. Click Application Management.

3. Navigate to Policy For Web Application.

4. Ensure that the appropriate application is selected from the drop-down list.

5. Click Add Users.

6. Select the appropriate Zone and then click Next.

7. Add the user account in the Choose Users Box (Figure 26-9).

8. Select Full Read, or select Full Control if the Web Service will interact with the data.

9. Optionally select Account Operates As System (for accounts that have Full Control) if you don’t want this access to be logged individually, but rather as System.

Consumption of Web Services is one of the strong points of Visual Studio. A typical Web Service consumer will be a command application, a desktop application, or a service. Other applications may require some additional security configuration in the code, so for the sake of simplicity, we’ll focus on a standard desktop application calling Web Services.

Here, in just few lines of code, we’ll be able to recreate the same functionality as in InfoPath and WebService Studio combined. As shown in Figure 26-10, we will use two Web Services to retrieve lists from the server, and then, once we obtain the GUID of each list, we will be able to retrieve data from the list.

Consuming Web Services is very easy in Visual Studio 2005, as the Intellisense quickly allows you to select a proper method, and allows you to see its signature and its type.

As mentioned earlier, there are two related APIs that can be utilized with WSS and MOSS for remote operations. As such, they are closely related to Web Services that effectively perform similar activities.

The key difference between these APIs is that they perform very specialized activities, namely file upload and download operations. The main reasons why these are important are:

Custom Web Services can be developed the same way as a typical Web Application, or, with few additional steps, your Web Service can be placed side-by-side with other Web Services installed with WSS and MOSS.

Assuming that you are familiar in developing a Web Application for the WSS platform within the _layouts directory, you can follow the same steps in developing all of the business functionality for your Web Service.

Your Web Service utilizes the WSS and MOSS APIs the same way as a standard Web Part or Web Application would:

Additional steps required to deploy Web Services to the _vti_bin directory include:

Only the first step is nontrivial, and uses disco.exe, which is a part of the .NET 2.0 SDK, typically located at C:Program FilesMicrosoft Visual Studio 8SDKv2.0Bin:

If you need to utilize Microsoft Office SharePoint Server 2007 data or functionality from a non-MOSS machine, most likely you will use Web Services or FrontPage Remote Procedure Call APIs. In some scenarios, you will find out that the Web Services provided are too generic or too chatty, and instead you will build your own set of Web Services.

Either way, this chapter has provided information on how and when you should access MOSS data from an external system that does not have MOSS APIs installed, as well as a simplified way to understand the nuances of each Web Service provided.

Use of Web Services is similar to the use of MOSS and WSS APIs: you must bind to a specific location, and then walk through the object model hierarchy to access the data.