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.
There may be a temptation to manipulate data stored in content or configuration databases, just because it seems doable. However, this is an unsupported scenario that could lead to corruption of data and destruction of your portal. Use the provided APIs or Web Services for integration instead of directly manipulating the database.
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:
The BDC provides a specification for connectivity into databases or Web Services.
These Web Parts allow consumption of the data purely on the UI site, coming either in a generic XML format or in a more specific WSRP specification that is supported by many portal and line-of-business application vendors.
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:
Describe major Web Services associated with MOSS and WSS
Locate and invoke these Web Services through some standardized tools
Utilize any of these Web Services in code
Utilize other APIs, such as FrontPage RPC
Create your own Web Service that utilizes MOSS APIs
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.
This chapter assumes that you are already familiar with the Web Service technology as a core concept, and know how to utilize or create a simple ASP.NET Web Service on your own. Also, this chapter does not delve into the Web Services Extensions (WSE).
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.
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.
In the next section, we will work with a free tool that allows us to access these Web Services. Additionally, we’ll look at different ways to reconfigure IIS in order to make access easier and make it possible to access the services from other systems.
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.
Table 26-1. Available WSS 3.0 Web Services
Web Service |
File |
Description |
---|---|---|
Administration Web Service |
Admin.asmx |
Allows for simple management of the site, such as deleting and adding sites |
Alerts Web Service |
Alerts.asmx |
Allows for control of Alerts within the site |
Authentication Web Service |
Authentication.asmx |
Allows for simple authentication into the MOSS or WSS applications, especially if the Authentication mode is Forms |
Copy Web Service |
Copy.asmx |
Allows for copy of items between different locations |
Document Workspace Web Service |
DWS.asmx |
Allows for means of managing Document Workspace sites; primarily used by the Document Management pane |
Forms Web Service |
Forms.asmx |
Allows for control of forms used in the UI |
Imaging Web Service |
Imaging.asmx |
Allows for control of picture libraries |
List Data Retrieval Web Service |
DspSts.asmx |
The workhorse of data access that allows users to perform queries against data in lists |
Lists Web Service |
Lists.asmx |
Allows retrieval of list metadata and performance of simple operations against list data |
Meetings Web Service |
Meetings.asmx |
Allows for creation and management of Meeting Workspace sites |
People Web Service |
People.asmx |
Allows for control of security groups |
Permissions Web Service |
Permissions.asmx |
Allows for control of permissions within a container |
Site Data Web Service |
SiteData.asmx |
Another workhorse that can provide site metadata, list metadata, and list data |
Sites Web Service |
Sites.asmx |
Allows for management of site templates |
Search Web Service |
SPSearch.asmx |
Allows for access to Windows SharePoint Services search functionality; in MOSS scenarios, the MOSS search Web Service should be utilized (search.asmx) |
Users Web Service |
UserGroup.asmx |
Allows for control of users, user groups, and cross-site groups |
Versions Web Service |
Versions.asmx |
Allows for control of file versions |
Views Web Service |
Views.asmx |
Allows for controls of different views for each list |
Web Part Pages Web Service |
WebPartPages.asmx |
Allows for control of content on the Web Part Pages |
Webs Web Service |
Webs.asmx |
Allows for control of Webs, which represents subsites within a site and provides more granular control |
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.
You should be aware of the fact that there is a “soft” limit of 2,000 items per view. Performance will fall whenever more than 2,000 items are retrieved within a single operation. In such cases, you may opt to limit your queries, or use Views to access data. Guidelines are published on TechNet in a “Plan for software boundaries” article:
http://technet2.microsoft.com/windowsserver/WSS/en/library/2aa12954-2ea7-475c-9dce-663f543820811033.mspx?mfr=true |
The Web Services that are associated purely with MOSS are defined in Table 26-2.
Table 26-2. MOSS-only Web Services
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.
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.
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.
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.
Additional Web Service tools are available for other Office applications, such as Excel and Visio. As a developer you can use Visual Studio Tools for Office, and there is also a Web Services Toolkit for Office XP and Office 2003 applications, available from Microsoft’s download center.
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.
Most of the XML structures, unless defined directly in a Web Service schema (e.g., Site Data Web Service) are documented in the WSS SDK in the Collaborative Application Markup Language Core Schemas. While making Web Services very flexible, they also make it harder to use. It is almost impossible to work only with Visual Studio due to the dependencies in CAML and complex elements that are declared as XmlNode or String.
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).
Table 26-3. Common data elements
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).
Table 26-4. XML results provided in the .NET API from the SPListItemCollection
Property |
Description |
---|---|
|
All of the data is represented by properties within a |
|
This schema describes the elements and properties of the XML data set. |
Our first application will require a Web Service with a relatively simple signature, as mentioned previously; a lot of Web Services use GUIDs when referring to lists. Our application will connect to the Lists Web Service and retrieve some of the basic information about each list, including its Internal Name in the form of a GUID.
To retrieve data from InfoPath for our application, follow these steps:
Open InfoPath.
Select Design Form Template.
Select Web Service.
Select Receive Data.
Enter the location of your Lists service. In this case, with a portal installed directly on the root of my server, we enter http://localhost/_vti_bin/Lists.asmx and click Next.
In the next screen, select GetListCollection as an operation we are going to execute.
Enter the name for the data connection as Get List Collection Connection.
At this point, we simply need to drag and drop the necessary elements on the screen.
Expand the dataFields section in the Data Source until the List group is visible.
Drag the element onto the Drag Data Fields Here section and choose a Repeating Section control to represent the results, as seen in Figure 26-5.
There are no Query Fields for this operation, so we can just run the form in the preview mode.
From File Menu, select “Preview and Form.”
Click Run Query, and answer Yes to any warnings.
Every List at the site level is returned with some metadata.
This exercise can be repeated and enhanced with additional functionality for several other Web Services. However, retrieval of list data may be not be a simple drag-and drop wizard exercise. In many cases, Web Services will simply return a big XML blob.
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).
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):
Open WebService Studio, or your favorite application.
Point to the WSDL file, and enter http://servername/sitepath/_vti_bin/sitedata.asmx?WSDL”.
Retrieve the WSDL by clicking the Get button.
Select the GetListItems
operation.
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
:
Press Invoke.
The Output section shows a single Results string, as the data inside represents the dynamic XML.
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.
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:
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:
Open the IIS management console and navigate to the web site you’d like to configure, or a virtual directory.
Right-click the node and select Properties from pop-up menu.
Select the Directory Security tab.
Click the Edit button of the “Authentication and Access Control” section.
Change the Authentication Methods here.
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.
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:
Open Central Administration.
Click Application Management.
Navigate to Policy For Web Application.
Ensure that the appropriate application is selected from the drop-down list.
Click Add Users.
Select the appropriate Zone and then click Next.
Add the user account in the Choose Users Box (Figure 26-9).
Select Full Read, or select Full Control if the Web Service will interact with the data.
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.
First, create a new Windows Application Project.
Next, add references to the Web Services:
Right-click the root node of the project in Solutions Explorer.
Select Add Web Reference.
In the Add Web Reference dialog box (Figure 26-11), you have to navigate to the Web Service you will utilize. If working with a local server, you can select the "Web Services on the Local Machine” link and navigate to the Lists Web Service; if working with another server, enter the URL of the Web Service. If you intend on binding to a specific web site within your portal, enter its full path, such as:
http://servername/sitepath/_vti_vin/Lists.asmx
Next, when the documentation is displayed, validate that this is a correct web service and provide a proper name for the local reference, such as ListsWS.
You can study the Object Model of the newly referenced Web Service by right-clicking the reference and choosing View in Object Browser.
Next, we add few controls to the form:
To bind to a web service:
ListItems.Lists _listItems = new ListItems.Lists( ); /*Authenticate the current user */ _listItems.Credentials = System.NET.CredentialCache.DefaultCredentials; /*Set the Url property of the service for the path to a subsite.*/ _listItems.Url = "http://localhost/_vti_bin/Lists.asmx";
To retrieve data from the web service:
System.Xml.XmlNode nodeListItems = _listItems.GetListItems(listName, "", query, viewFields, rowLimit, queryOptions, "");
To display the data in a crude way:
/*Loop through each node in the XML response and display each item.*/ foreach (System.Xml.XmlNode listItem in nodeListItems) { textBox1.Text += listItem.OuterXml; }
Compile and run the code.
Click the button to populate the list combo box.
Select a list from a combo box and click the button to get list data.
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:
Web Services simply do not perform as well as these protocols, requiring larger-than-file XML messages (due to encoding) as well as larger memory requirements, due to chunking and serialization. Although some of these problems could be alleviated with use of Dime and WSE 3.0 extensions, they would still not match the performance of the APIs covered in this section.
Industry-wide support for these web services allows other document management and line of business applications to easily integrate with WSS and MOSS.
FrontPage RPC generally refers to a set of FrontPage Remote Procedure Calls that provide the functionality to create, upload, download, change, and move documents in a SharePoint server, typically via HTTP POST commands.
FrontPage RPC interacts with the server via a single specialized DLL (owssvr.dll), provides over 40 different method calls, and allows batching of commands via CAML Batch element, which reduces the number of round-trips required to complete an activity:
http://servername/[subpath/]_vti_bin/owssvrdll?Cmd=MethodName[&Param1=Value1 |
Some of the document management-related activities (among many others) are:
Check in document
Check out document
Get Docs MetaInfo
Get document
Get documents
Move document
Put document
Put documents
Uncheckout document
This API is well documented within the WSS SDK, and there are also a large number of applications and code samples in the community sites that utilize FrontPage RPC as a means of working with files within WSS and MOSS.
A sample document upload application is available through GotDot-Net.
The following contains an example of how to upload a file to a Share-Point library via the FrontPage RPC protocol:
http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=5451793d-288c-4fed-8e79-6c44ab0550e2 |
WebDAV, which stands for Web-based Distributed Authoring and Versioning, is an extension to the standard HTTP protocol that allows creating, changing, and moving documents over an HTTP protocol. Unfortunately, contrary to what its name suggests, it lacks good support for versioning of the documents. Consequently, this API is typically used more for interoperability rather than for building full-blown remote document management applications.
Within Microsoft’s developer section is part of an old Exchange server documentation:
http://msdn2.microsoft.com/en-us/library/ms985516.aspx |
You can download a sample DavCopy application from the SharePoint Products and Technologies directory:
http://www.microsoft.com/sharepoint/downloads/components/results.asp?s=A&c=davcopy |
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.
WSS directories are part of a “12 hive”: C:Program FilesCommon Files Microsoft Sharedweb server extensions12 where _vti_bin/ corresponds to the ISAPI directory, and _layouts corresponds to TEMPLATE LAYOUTS.
Your Web Service utilizes the WSS and MOSS APIs the same way as a standard Web Part or Web Application would:
Add the Microsoft.SharePoint
assembly
reference to your project.
Add appropriate using directives, such as:
using Microsoft.SharePoint; using Microsoft.SharePoint.Utilities;
Obtain the context for the Web Service:
SPWeb _web = SPContext.Current.Web;
Utilize the WSS API.
Modify the trust level policy if needed.
Utilize the AllowUnsafeUpdates
web
property if your Web Service modifies any WSS data.
Additional steps required to deploy Web Services to the _vti_bin directory include:
Generation of a static discovery and WSDL files
Deployment of Web Service files to the _vti_bin directory
Deployment of assemblies to GAC
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:
Open the command prompt and navigate to the location where disco.exe is installed.
When running disco.exe, enter the location of your .asmx file, such as http://servername/_layouts/appname/webservicename.asmx.
Replace the opening XML declaration with SharePoint references:
<%@ Page Language="C#" Inherits="System.Web.UI.Page"%> <%@ Assembly Name="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> <%@ Import Namespace="Microsoft.SharePoint.Utilities" %> <%@ Import Namespace="Microsoft.SharePoint" %> <% Response.ContentType = "text/xml"; %>
In the .disco file, replace the method name and
binding, and rename the file as
WebServiceName
disco.aspx:
<contractRef ref=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb. OriginalBaseUrl(Request) + "?wsdl", '"'), %> docRef=<% SPEncode. WriteHtmlEncodeWithQuote(Response, SPWeb.OriginalBaseUrl(Request), '"'), %> xmlns="http://schemas.xmlsoap.org/disco/scl/" /> <soap address=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb. OriginalBaseUrl(Request), '"'), %> xmlns:q1="http://tempuri.org/" binding="q1: HelloWorld" xmlns="http://schemas.xmlsoap.org/disco/soap/" />
In the .wsdl file, change the binding of the SOAP
address near the bottom of the file, and rename the file to be
WebServiceNamewsdl
.aspx:
<soap:address location=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb. OriginalBaseUrl(Request), '"'), %> />
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.