Web Service Guidelines
Applies to: SharePoint Foundation 2010
The Microsoft SharePoint Foundation Web services provided by the Microsoft.SharePoint.SoapServer namespace include methods for accessing content on a Web site—such as for working with lists or site data—as well as methods for customizing meetings, imaging, document workspaces, or search.
Whenever possible, it is recommended that you use the new client-side object model to work remotely with SharePoint Foundation data, instead of using the legacy ASP.NET Web services described here.
SOAP interfaces that are used in these services provide Microsoft .NET Framework developers with object models for creating solutions that work with SharePoint Foundation remotely from a client or custom application. The interfaces are defined through the server-side object model of the Microsoft.SharePoint assembly, and their design is optimized to reduce the number of round trips transacted between client computer and server.
Most Web services provide their functionality through the /_vti_bin virtual directory, which maps to the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI physical directory in the file system. The Administration Web service uses the /_vti_adm virtual directory, which maps to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ADMISAPI.
SharePoint Foundation does not require the implementation of a particular version of SOAP. The SOAP response in any transaction with SharePoint Foundation is managed by the .NET Framework.
Guidelines for Using the ASP.NET Web Services
You can create a project in Microsoft Visual Studio, such as a Windows Forms application or console application, which uses a SharePoint Foundation Web service to interact with SharePoint site and list data. After you create a project, you must set a reference to the Web service you want to implement in your code, specifying the full path to the Web service in relation to the site containing the data.
To add a reference to a SharePoint Foundation Web service in Visual Studio
In Solution Explorer, right-click References, and then click Add Service Reference.
In the Add Service Reference dialog box, click Advanced, and in the Service Reference Settings dialog box, click Add Web Reference.
In the Add Web Reference dialog box, for URL type the absolute URL for the Web service, specifying a path that includes the Web site for which the Web service will be available. For example, if you want to add a reference to the Lists Web service, specify a path in the following format:
If you are using methods in the Administration Web service, instead, specify a path that goes to the administration port and that uses _vti_adm as the virtual directory, as follows.
For a list of the default ASP.NET Web services that are provided by SharePoint Foundation, see SharePoint Foundation 2010 Web Services.
Type a Web reference name, and then click Add Reference.
Instantiating a Service
Instantiate a Web service within code by using a constructor as follows: Web_Reference.Service_NameServiceInstance = new Web_Reference.Service_Name(). Web_Reference represents the name used for the reference to the Web service in Visual Studio, and Service_Name represents the name of the class that provides methods which can be called through the Web service.
Establishing User Credentials
To establish system credentials for the current security context in which the application is running, add the following line after the previous line, which authenticates the user or group under which the code is running by passing their default credentials to the Web service from the system credential cache.
ServiceInstance.Credentials = System.Net.CredentialCache.DefaultCredentials
ServiceInstance.Credentials = System.Net.CredentialCache.DefaultCredentials;
The following basic programming tasks demonstrate how to use one of the default Web services that are provided in SharePoint Foundation:
For information about how to create a custom ASP.NET Web service that implements the SharePoint Foundation server-side object model, see Walkthrough: Creating a Custom ASP.NET Web Service. For information about creating a custom WCF service that implements the object model, which is the recommended way to create a Web service in SharePoint Foundation, see Walkthrough: Creating and Implementing a Custom WCF Service in SharePoint Foundation.