Writing Custom Web Services for SharePoint Products

and Technologies

Summary: Learn to create custom Web services for Microsoft
SharePoint Products and Technologies and how to use the
SharePoint Products and Technologies infrastructure to create a
document upload Web service for remote document access.
The accompanying downloadable sample provides a Web
service for working with documents remotely from an eternal
application. !"" printed pages#
$ote The information in this article also applies to Microsoft
%ffice SharePoint Portal Server &''() which is built on the
Windows SharePoint Services platform. The code samples can
be used on SharePoint sites created in a portal contet using
SharePoint Portal Server.
*ownload %*+,Writing+ustomWebServicesSampleSPPT.-.-.
+ontents
/ntroduction
0bout the Web Service Sample
Writing a +ustom Web Service
+reating a Sample *ocument 1pload Web Service
Troubleshooting 2uide
+onclusion
/ntroduction
3ou can build powerful solutions on the rich and robust
platform of Microsoft4 Windows4 SharePoint5 Services. 0s a
developer) you may want to use some of the capabilities of
Windows SharePoint Services to create custom Web services of
your own.
$ote 6ecause of the enhanced security model used by
Windows SharePoint Services) you need to take a couple etra
steps. To create a Web service for Windows SharePoint Services
using the 0SP.$-T Web Service template in Microsoft 7isual
Studio4 .$-T) you must create the Web service on a virtual
server that uses a different port than the virtual server that is
running Windows SharePoint Services. 0dditionally) you must
be a member of the local 0dministrators group for the server
that is running Windows SharePoint Services.
The following list summari8es the process for writing a custom
Web service. The remainder of this article drills deeper into the
details.
/f your default Web site !port 9'# hosts Windows SharePoint
Services) create a virtual server that uses a different port. The
new virtual server acts as the development Web server) and the
virtual server that hosts Windows SharePoint Services acts as
the deployment Web server.
+reate a Web Service Pro:ect on the development virtual
server.
2enerate and modify a static discovery !.disco# file and a .wsdl
file) save these files as .asp pages) and then register
theMicrosoft.SharePoint namespace with the page directive.
Modify the .disco and .wsdl files to support service
virtuali8ation.
When you finish developing the Web service) deploy its files to
the ,vti,bin virtual directory and the ,vti,bin;bin virtual
directory) which are located on the physical path for the
Windows SharePoint Services site.
$ote This article assumes that you have a solid understanding
of Microsoft .$-T <ramework) 0SP.$-T) and a programming
language such as + or Microsoft 7isual 6asic4 .$-T. <or
additional reference material not included in this article) see
the Microsoft SharePoint Products and Technologies Software
*evelopment =it !S*=#.
0bout the Web Service Sample
The %*+,Writing+ustomWebServicesSampleSPPT.-.- downloa
d provides a sample Web service for remote document access.
This pro:ect implements some of the document access methods
eposed by the Microsoft.SharePoint namespace)
namely)SP<ile.+heck/n) SP<ile.+heck%ut) SP<ile.1ndo+heck%ut
) and SP<ile+ollection.0dd. Without this custom Web service)
you must use Web *istributed 0uthoring and 7ersioning
!Web*07# or Microsoft %ffice <rontPage remote procedure call
!>P+# re?uests to provide remote document access.
To use this service on a server running Windows SharePoint
Services
*ownload %*+,Writing+ustomWebServicesSampleSPPT.-.-
and etract its contents to the following directory on a front@
end server running Windows SharePoint Services:
Local_drive:;+reatinga+ustomWebServiceSample
*ouble@click the build.bat file to compile the pro:ect and install
the Web service.
The following files are copied to the Local,drive:;Program
<iles;+ommon <iles;Microsoft Shared;Web Server
-tensions;A';isapi; directory:
SP<iles.asm
spfilesdisco.asp
spfileswsdl.asp
The following files are copied to the Local,drive:;Program
<iles;+ommon <iles;Microsoft Shared;Web Server
-tensions;A';isapi;6/$;directory:
WS+heck%ut.dll
WS+heck%ut.pdb
Writing a +ustom Web Service
The 7isual Studio .$-T integrated development environment
provides an 0SP.$-T Web service template that makes it easy
to create custom Web services for a computer running Windows
SharePoint Services. To use the template) however) you must
first create a virtual server in /nternet /nformation Services
!//S# on a port different from the one on which Windows
SharePoint Services is running.
To create a virtual server on a different port
+lick Start) point to 0dministrative Tools) and then
click /nternet /nformation Services !//S# Manager.
-pand the branch for the server computer to which you want
to add a virtual server. 1nder the server computer branch)
right@click the Web Sites folder) point to $ew) and then
click Web site.
/n the $ame bo) type a name for the new Web site.
/n the *escription bo) type the description of your virtual
server) and then click $et.
/n the -nter the /P address to use for this Web site bo) select
the /P address that you want to use) or use the default value
!0ll 1nassigned#.
/n the T+P port this Web site should use bo) type the port
number to assign to the virtual server) and then click $et.
$ote 7erify that this port number is not currently in use. 3ou
do not need to assign a host header because Windows
SharePoint Service handles hosting.
/n the Path bo) browse or type the path to the location on
your hard disk where you want to store your pro:ects.
/f you do not want to permit anonymous access to your virtual
server) clear the 0llow anonymous access to this Web
site check bo) and then click $et.
%n the Web Site 0ccess Permissions panel) select the
permissions that you want to use) and then click $et.
$ote <or best results in most cases) accept the default
permissions. 6y default) the >ead permission and the>un
Scripts !such as 0SP# permission are selected. Windows
SharePoint Services automatically adds the-ecute !such as
/S0P/ applications or +2/# permission to the appropriate
folders.
+lick <inish.
To create a Web Service Pro:ect in 7isual Studio .$-T
%n the <ile menu) point to $ew) and then click Pro:ect.
/n the Pro:ect Types bo) select 7isual 6asic Pro:ects or 7isual
+ Pro:ects) depending on which language you prefer.
/n the Templates bo) select 0SP.$-T Web Service.
/n the Location bo) type the following path:
http:BBServer_Name:portBProject_Name
+lick %=.
$ote %n a remote computer) you receive a CWeb 0ccess
<ailedC error message) which tells you that the path does not
correspond to the 1>L that you specified in the $ew
Pro:ect dialog bo. /f this occurs) follow these steps:
1nder What would you like to doD) verify that the >etry using a
different file share path check bo is selected) and then type
the following path in the Location bo:
\\Server_Name\NewVirtualRootPath
+lick %=.
+ompleting this step creates an empty 0SP.$et Web
Service pro:ect that includes a Service".asm file.
/n Solution -plorer) right@click Service".asm) and then
click 7iew +ode.
>emove the comments in the following lines:
EFWebMethod!#G Public <unction HelloWorld!# 0s String
E HelloWorld I CHello WorldC
E -nd <unction
+ompile the pro:ect.
3ou can now deploy your service to the virtual server running
Windows SharePoint Services.
To bind against a custom Web service for Windows SharePoint
Services) 7isual Studio .$-T re?uires a special set of .asp
pages based on the static discovery !.disco# file and the .wsdl
file for your Web service. 1se the command line utility installed
with 7isual Studio .$-T to generate a static discovery !.disco#
file and a .wsdl file) as described in the following procedure.
To create and edit a .disco file and a .wsdl file
0t the 7isual Studio .$-T command prompt) type the following
line) and then press -$T-> to create a Service".disco file and a
Service".wsdl file in the current folder:
*isco
http:BBserver_name:New_PortBProject_NameBService,".asm
%pen the Service".disco file and locate the following line:
FDml versionIC".'C encodingICutf@9CDG
>eplace the preceding line with the following lines:
FJK Page LanguageIC+LC /nheritsICSystem.Web.1/.PageC
JG FJK 0ssembly $ameICMicrosoft.SharePoint)
Microsoft.SharePoint) 7ersionI"".'.'.') +ultureIneutral)
Public=eyTokenIM"eNbce"""eNO&NcC JG FJK /mport
$amespaceICMicrosoft.SharePoint.1tilitiesC JG FJK /mport
$amespaceICMicrosoft.SharePointC JG
FJ >esponse.+ontentType I CtetBmlCP JG
Save the file as Service"disco.asp.
>epeat steps & through O to modify the Service".wsdl file and
save it as Service"wsdl.asp.
To modify the Service"disco.asp file and the
Service"wsdl.asp file to support service virtuali8ation
$ote The following code eamples) and subse?uent ones)
include etra line breaks to facilitate online display. To use
these eamples) please remove the etra line breaks.
%pen the Service"disco.asp file) and then locate the following
tag:
Fcontract>ef
refIChttp:BBserver_name:New_PortBProject_NameBService".as
mDwsdlC doc>efI
Chttp:BBserver_name:New_PortBProject_NameBService".asmC
mlnsIChttp:BBschemas.mlsoap.orgBdiscoBsclBC BG
Make the following changes in the Fcontract>efG tag:
Fcontract>ef refIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse)
SPWeb.%riginal6ase1rl!>e?uest#
R CDwsdlC) ECE#P JG doc>efIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse)
SPWeb.%riginal6ase1rl!>e?uest#) ECE#P JG
mlnsIChttp:BBschemas.mlsoap.orgBdiscoBsclBC BG
Locate the following tag:
Fsoap
addressIChttp:BBserver_name:New_PortBProject_NameBService
".asmC mlns:?"I
Chttp:BBtempuri.orgBC bindingIC?":Service"SoapC
mlnsIChttp:BBschemas.mlsoap.orgBdiscoBsoapBC BG
+hange the Fsoap addressG tag as follows) and then save the
changes:
Fsoap addressIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse)
SPWeb.%riginal6ase1rl
!>e?uest#) ECE#P JG mlns:?"IChttp:BBtempuri.orgBC
bindingIC?":Service"SoapC mlnsI
Chttp:BBschemas.mlsoap.orgBdiscoBsoapBC BG
%pen the Service"wsdl.asp file) and then locate the following
line:
Fsoap:address
locationIChttp:BBserver_name:New_Port/Project_NameBService
".asmC BG
Make the following changes to the soap:address line) and then
save the changes:
Fsoap:address locationIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse)
SPWeb.%riginal6ase1rl!>e?uest#) ECE#P JG BG
To copy the Web service files to the ,vti,bin virtual directory
+opy the Service"wsdl.asp file) the Service"disco.asp file)
and the Service".asm file to the ,vti,bin virtual directory. This
is the directory where all default Web services are stored.
+opy the corresponding assembly !.dll# file to the ,vti,binBbin
virtual directory.
$ote The ,vti,binBbin virtual directory is mapped to the
;;Server,$ame;Program <iles;+ommon <iles;Microsoft
Shared;Web Server -tensions;/S0P/ directory.
$et) you must include the service in the list of default
Windows SharePoint Services Web services that is displayed in
the 0dd Web >eference browser of 7isual Studio .$-T.
To include the Web service in the list of Web services on the
server
/n $otepad) open the spdisco.asp file of
the Local,*rive:;Program <iles;+ommon <iles;Microsoft
Shared;Web Server -tensions;A';/S0P/folder.
0dd the following lines to the end of the file within
the discovery element and save the file:
Fcontract>ef refIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse) spWeb.1rl R
CB,vti,binBService".asmDwsdlC)
ECE#P JG doc>efIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse) spWeb.1rl R
CB,vti,binBService".asmC) ECE#P
JG mlnsIChttp:BBschemas.mlsoap.orgBdiscoBsclBC BGFsoap
addressIFJ
SP-ncode.WriteHtml-ncodeWithQuote!>esponse) spWeb.1rl R
CB,vti,binBService".asmC) ECE#P JG

mlns:?"IChttp:BBschemas.microsoft.comBsharepointBsoapBdire
ctoryBC bindingIC?":Service"SoapC
mlnsIChttp:BBschemas.mlsoap.orgBdiscoBsoapBC BG
$ote The tet appearing before
CSoapC
in the binding attribute of the soap element !in this eample)
bindingIC?":Service"SoapC
# specifies the name of the class that is defined in the Web
service.
1sing the Web Service
3ou are ready to use your custom Web service by creating a
Windows application in 7isual Studio .$-T.
To use the custom Web Service
%n another computer) open 7isual Studio .$-T.
%n the <ile menu) point to $ew) and then click Pro:ect.
/n the Pro:ect Types bo) select 7isual 6asic Pro:ects or 7isual
+ Pro:ects) depending on which language you prefer.
/n the Templates bo) select Windows 0pplication.
Specify a name and path for the pro:ect) and then click %=.
%n the default form) add a command button to invoke the new
Web service.
0dd a Web reference to the Web service:
>ight@click the pro:ect) and then click 0dd Web >eference.
/n the wi8ard) type the following 1>L) and then click %pen to
download the service contract for the Web service:
http:BBServer_nameB,vti,binBService".asm
$ame this reference WSSServer.
0dd the following using directive to the pro:ect:
using System.$etP
/n the +lick event for the new button) add the following lines of
code:
WSSServer.Service" ,svc I new WSSServer.Service"!#P
BBto use the following line use System.$et in the using section
,svc.+redentials I +redential+ache.*efault+redentialsP
string ,>etval I ,svc.HelloWorld!#P
Message6o.Show!,>etval#P
+ompile the pro:ect and run it) and then click the button to test
the Web service.
+reating a Sample *ocument 1pload Web Service
3ou can use the method described earlier in this article to
create a Web service that uploads documents into the Shared
*ocuments document library on the computer that is running
Windows SharePoint Services. This Web service uses service
virtuali8ation to determine the site contet) and then uploads
the document to the Shared *ocuments document library
folder.
To create the 1pload service
1se the method described in the previous section to create a
Web service pro:ect. $ame the pro:ect 1ploadSvc and name
the Web service class and constructor 1pload<ile.
/n Solution -plorer) right@click Service".asm and rename the
file 1pload<ile.asm.
0dd a reference to the assembly for Windows SharePoint
Services !Microsoft.Sharepoint.dll#. 6y default) this assembly is
listed with the other assemblies in the global assembly cache.
The assembly for Windows SharePoint Services is also located
in the following directory:
+:;Program <iles;+ommon <iles;Microsoft Shared;web server
etensions;A';/S0P/
0dd the following Web method to the 1pload<ile.asm.cs file as
a member of the 1pload<ile class:
SWebMethodT
public string 1pload*ocument!string file$ame) byteST
file+ontents) string path<older#
U
if ! file+ontents II null#
U
return C$ull 0ttachmentCP
V
try
U
SPWeb site I SP+ontrol.2et+ontetWeb!+ontet#P
SP<older folder I site.2et<older!path<older#P
string file1rl I file$ameP
SP<ile file I folder.<iles.0dd!file1rl) file+ontents#P
return file.Time+reated.ToLong*ateString!#R C::C R
file.TitleP
V
catch !System.-ception ee#
U
return ee.Message R C::C R ee.SourceP
V
V
0dd the following using directives to the pro:ect:
using System./%P
using Microsoft.SharePointP
using Microsoft.SharePoint.Web+ontrolsP
+ompile the Web service pro:ect.
+reate and modify the .disco and .wsdl files and modify the
spdisco.asp file as described in previous sections) but replace
Service" with 1pload<ile. Save the files
as 1pload<iledisco.asp and 1pload<ilewsdl.asp respectively.
+opy the .asm file and the .asp versions of the .disco and
.wsdl files to the ,vti,bin virtual directory) and copy the
corresponding assembly to the ,vti,binBbin virtual directory.
To use the 1pload service
%pen 7isual Studio .$-T) and then create a standard Windows
application.
0dd a Web reference to the Web service that you created in the
preceding procedure. $ame the Web referenceWSSServer.
0dd a button and two tet boes to the default form in the
Windows application) one tet bo in which to enter the path of
the file to upload and another tet bo in which to specify the
destination document library !for
eample)http:BBServer_NameBsitesBTarget_SiteBDocument_Lir
ar!#.
0dd the following lines of code to the +lick event for the
button.
WSSServer.1pload<ile svc*ocLib I new
WSSServer.1pload<ile!#P
svc*ocLib.+redentials I +redential+ache.*efault+redentialsP
string strPath I tet6o".TetP
string str<ile I strPath.Substring!strPath.Last/nde%f!C;;C# R
"#P
string str*estination I tet6o&.TetP
<ileStream fStream I new <ileStream!strPath)
System./%.<ileMode.%pen#P
byteST bin<ile I new byteS!int#fStream.LengthTP
fStream.>ead!bin<ile) ') !int#fStream.Length#P
fStream.+lose!#P
string str I svc*ocLib.1pload*ocument!str<ile) bin<ile)
str*estination#P
Message6o.Show!str#P
0dd the following using directives to the pro:ect:
using System.$etP
using System./%P
+ompile the pro:ect and run it.
Troubleshooting 2uide
%btaining the SharePoint Site +ontet
0t run time) if your custom Web service cannot use
the 2et+ontetWeb function to obtain the SharePoint site
contet successfully) you receive the following error message
when you try to use the Web service:
System.0rgument-ception: 7alue does not fall within the
epected range. 0t Microsoft.SharePoint.SPSite
When you create a custom Web service for your SharePoint
site) you must retrieve an instance of the SPWeb class by
invoking the2et+ontetWeb function on the SP+ontrol ob:ect.
To successfully invoke 2et+ontetWeb) your custom Web
service must run within the same 0pp*omain as your
SharePoint site. To do this) move your .asm file to
the ,vti,bin virtual directory) and move the assembly for the
Web service into the ,vti,binBbin virtual directory.
Testing your +ustom Web Service
0fter you deploy your .asm file and your assembly) test your
Web service. To test your Web service successfully) you must
create a test application in 7isual Studio .$-T that uses S%0P
to invoke the Web service methods. 6y default) custom Web
services for Windows SharePoint Services only honor S%0P
re?uests from their clients. /f you try to test your Web service
using a protocol other than S%0P) you receive the following
error message:
Microsoft.SharePoint.SP-ception: The security validation for
this page is invalid and might be corrupted. Please use your
Web browserEs 6ack button to try your operation again.
0dding a Web >eference to your +ustom Web Service from
7isual Studio .$-T
To bind against a custom Web service for Windows SharePoint
Services) 7isual Studio .$-T re?uires a special set of .asp
pages. /f you add a Web reference to the .asm file for the
service without the re?uired .asp pages) you receive the
following error message:
C<ile not foundC when adding a Web reference to the 0SM. file
from 7isual Studio.$-T.
0fter you use the .disco file and the .wsdl file to create the two
new .asp files and move them to the
appropriate ,vti,bin virtual directory) you can successfully add
a Web reference to the Web service from 7isual Studio .$-T. 6e
sure to add the Web reference to the .asm file for the Web
Service. *o not add the Web reference to either of the newly
created .asp files. /f you do so) the Web service may appear
to work in 7isual Studio .$-T) but at run time you receive the
following error message:
0dditional information: Possible S%0P version mismatch:
-nvelope namespace http:BBschemas.mlsoap.orgBwsdlB was
unepected. -pecting
http:BBschemas.mlsoap.orgBsoapBenvelopeB.
+onclusion
6y employing the techni?ues covered in this article) you can
effectively create custom Web services that etend and
enhance the power of Windows SharePoint Services for your
own SharePoint@based solutions. 1se the sample download to
upload documents to a library and to check files in to or out
from a remote application.