C# AND .

NET FRAMEWORK

PROGRAMMING WEB SERVICES I. SOAP: SOAP is a lightweight, message-based protocol built on XML, HTTP, and SMTP. Two other protocols are desirable, but not re uired, !or a client to use a SOAP-enabled web ser"ice# a description o! the methods pro"ided b$ a particular ser"ice that can be understood and acted upon b$ clients, and a description o! all such ser"ices a"ailable at a particular site or %&L. The !irst o! these is pro"ided in .'(T b$ the )eb Ser"ice *escription Language +)S*L, protocol, -ointl$ de"eloped b$ Microso!t, ./M, and others. Two other protocols ha"e been proposed !or disco"er$# %**., a -oint e!!ort b$ a number o! companies including ./M and Microso!t, and *isco"er$, a proprietar$ o!!ering !rom Microso!t. WSDL and Discovery )S*L is an XML schema used to describe the a"ailable methods -- the inter!ace -o! a web ser"ice. *isco"er$ enables applications to locate and interrogate web ser"ice descriptions , a preliminar$ step !or accessing a web ser"ice. .t is through the disco"er$ process that web ser"ice clients learn that a ser"ice e0ists, what its capabilities are, and how to properl$ interact with it. A *isco"er$ +.disco, !ile pro"ides in!ormation to help browsers determine the %&Ls at an$ web site at which web ser"ices are a"ailable. )hen a ser"er recei"es a re uest !or a .disco !ile, it generates a list o! some or all o! the %&Ls at that site that pro"ide web ser"ices. Server-side Support The plumbing necessar$ to disco"er and in"o1e web ser"ices is integrated into the .'(T 2ramewor1 and pro"ided b$ classes within the S$stem.)eb.Ser"ices namespace. 3reating a web ser"ice re uires no special programming on $our part4 $ou need onl$ write the implementing code, add the 5)ebMethod6 attribute, and let the ser"er do the rest. Client-side Support 7ou ma1e use o! a web ser"ice b$ writing client code that acts as though it were communicating directl$ with the host ser"er b$ means o! a %&L. Howe"er, in realit$, the client interacts with a proxy. The -ob o! the pro0$ is to represent the ser"er on the client machine, to bundle client re uests into SOAP messages that are sent on to the ser"er, and to retrie"e the responses that contain the result. II. i) BUILDI ! A W"B S"#$IC" To illustrate the techni ues used to implement a web ser"ice in 38 using the ser"ices classes o! the .'(T 2ramewor1, build a simple calculator and then ma1e use o! its !unctions o"er the )eb. /egin b$ speci!$ing the web ser"ice. To do so, de!ine a class that inherits !rom S$stem.)eb.Ser"ices.)ebSer"ice. The easiest wa$ to create this class is to open 9isual Studio and create a new 38 )eb Ser"ice pro-ect. The de!ault name that 9isual Studio pro"ides is )ebSer"ice:. 9isual Studio .'(T creates a s1eleton web ser"ice and e"en pro"ides a )eb Ser"ice e0ample method !or $ou to replace with $our own code, as shown in the !ollowing e0ample.

C# AND .NET FRAMEWORK

S%eleton We& Class 'enerated &y $isual Studio . "( using S$stem4 using S$stem.3ollections4 using S$stem.3omponentModel4 using S$stem.*ata4 using S$stem.*iagnostics4 using S$stem.)eb4 using S$stem.)eb.Ser"ices4 na)espace WSCalc ; <<< =summar$> <<< Summar$ description !or Ser"ice:. <<< =<summar$> public class Ser"ice: # S$stem.)eb.Ser"ices.)ebSer"ice ; public Ser"ice:+ , ; <<3O*(?('# This call is re uired b$ << the ASP.'(T )eb Ser"ices *esigner .nitiali@e3omponent+ ,4 A 8region 3omponent *esigner generated code <<&e uired b$ the )eb Ser"ices *esigner pri"ate .3ontainer components B null4 <<< =summar$> <<< &e uired method !or *esigner support - do not modi!$ <<< the contents o! this method with the code editor. <<< =<summar$> pri"ate "oid .nitiali@e3omponent+ , ; A <<< =summar$> <<< 3lean up an$ resources being used. <<< =<summar$> protected o"erride "oid *ispose+ bool disposing , ; i!+disposing CC components DB null, ; components.*ispose+ ,4 A base.*ispose+disposing,4 A 8endregion << )(/ S(&9.3( (XAMPL( << The Hello)orld+ , e0ample ser"ice << returns the string Hello )orld << To build, uncomment the !ollowing lines << then sa"e and build the pro-ect << To test this web ser"ice, press 2E

C# AND .NET FRAMEWORK

<< 5)ebMethod6 << public string Hello)orld+ , << ; << return FHello )orldF4 << A A A 3reate !i"e methods# Add+ ,, Sub+ ,, Mult+ ,, *i"+ ,, and Pow+ ,. (ach ta1es two parameters o! t$pe double, per!orms the re uested operation, and then returns a "alue o! the same t$pe. 2or e0ample, here is the code !or raising a number to some speci!ied power# public double Pow+double 0, double $, ; double ret9al B 04 !or +int i B G4i = $-:4iHH, ; ret9al IB 04 A return ret9al4 A To e0pose each method as a web ser"ice, $ou simpl$ add the [WebMethod] attribute be!ore each method declaration. WSDL and a)espace )eb ser"ice will use a )eb Ser"ice *escription Language +)S*L, XML document to describe the web-callable end points. )ithin an$ )S*L document, an XML namespace must be used to ensure that the end points ha"e uni ue names. The de!ault XML namespace is http://tempuri.org, but $ou will want to modi!$ this be!ore ma1ing $our web ser"ice publicl$ a"ailable. )e can change the XML namespace b$ using the )ebSer"ice attribute# 5)ebSer"ice+'amespaceB Fhttp#<<www.Libert$Associates.com<webSer"ices<F,6 Calculator We& Service Pro'ra): using S$stem4 using S$stem.3ollections4 using S$stem.3omponentModel4 using S$stem.*ata4 using S$stem.*iagnostics4 using S$stem.)eb4 using S$stem.)eb.Ser"ices4 namespace )S3alc ; 5)ebSer"ice+'amespaceBFhttp#<<www.libert$Associates.com<webSer"ices<F,6 public class Ser"ice: # S$stem.)eb.Ser"ices.)ebSer"ice ;

C# AND .NET FRAMEWORK

public Ser"ice:+ , ; <<3O*(?('# This call is re uired b$ the <<ASP.'(T )eb Ser"ices *esigner .nitiali@e3omponent+ ,4 A 8region 3omponent *esigner generated code <<&e uired b$ the )eb Ser"ices *esigner pri"ate .3ontainer components B null4 <<< =summar$> <<< &e uired method !or *esigner support - do not modi!$ <<< the contents o! this method with the code editor. <<< =<summar$> pri"ate "oid .nitiali@e3omponent+ , ; A <<< =summar$> <<< 3lean up an$ resources being used. <<< =<summar$> protected o"erride "oid *ispose+ bool disposing , ; i!+disposing CC components DB null, ; components.*ispose+ ,4 A base.*ispose+disposing,4 A 8endregion 5)ebMethod6 public double Add+double 0, double $, ; return 0H$4 A 5)ebMethod6 public double Sub+double 0, double $, ; return 0-$4 A 5)ebMethod6 public double Mult+double 0, double $, ; return 0I$4 A 5)ebMethod6 public double *i"+double 0, double $, ; return 0<$4 A 5)ebMethod6 public double Pow+double 0, double $,

C# AND .NET FRAMEWORK

; double ret9al B 04 !or +int i B G4i = $-:4iHH, ; ret9al IB 04 A return ret9al4 A A A )hen $ou build this pro-ect with 9isual Studio .'(T, a *LL is created in the appropriate subdirector$ o! $our .nternet ser"er. ii) ("S(I ! *OU# W"B S"#$IC" .! $ou open a browser to $our web ser"iceJs %&L +or in"o1e the browser b$ running the program in 9isual Studio .'(T,, $ou get an automaticall$ generated, ser"er-side web page that describes the web ser"ice, as shown in the !ig below. Test pages such as this o!!er a good wa$ to test $our web ser"ice. We& Service We& Pa'e

3lic1ing a method brings $ou to a page that describes the method and allows $ou to in"o1e it b$ t$ping in parameters and pressing the .n"o1e button. The !ollowing !ig illustrates this.

C# AND .NET FRAMEWORK

(est Pa'e +or a We& Service ,et-od

.! $ou t$pe 3 into the !irst "alue !ield and 4 into the second !ield, $ou will ha"e as1ed the web ser"ice to raise 3 to the !ourth power. The result is an XML page describing the output, as shown in the !ig below# .,L Output /or a We& Service ,et-od

'otice that the %&L encodes the parameters o! K and L, and the output XML shows the result o! M: +KIKIKIK B M:,. iii) $I"WI ! (0" WSDL CO (#AC( The web ser"ice is described in )S*L. 7ou can see the )S*L document b$ appending ?WSDL to the web ser"ice %&L, li1e this#
http://localhost/WSCalc/Service1.asmx?wsdl

The browser displa$s the )S*L document, as shown in 2.? below

C# AND .NET FRAMEWORK

Sa)ple WSDL Output +or Calculator We& Service

(ach method is !ull$ described in a structured XML !ormat. This is the in!ormation used b$ SOAP to allow the client browser to in"o1e $our web ser"ice methods on the ser"er. III. C#"A(I ! (0" P#O.* /e!ore $ou can create a client application to interact with the calculator web ser"ice, $ou must !irst create a pro0$ class. The !ol1s at Microso!t ha"e pro"ided a tool called wsdl that generates the source code !or the pro0$ based on the in!ormation in the )S*L !ile. To create the pro0$, enter wsdl at the )indows command-line prompt, !ollowed b$ the path to the )S*L contract. 2or e0ample, $ou might enter#
wsdl http://localhost/WSCalc/service1.asmx?wsdl

The result is the creation o! a 38 client !ile named Service.cs, an e0cerpt o! which appears in the !ollowing e0ample. 7ou must add the namespace WSCalc because $ouJll need it when $ou build $our client +the tool does not insert it !or $ou,. Sa)ple Client Code (o Access t-e Calculator We& Service using S$stem.Xml.Seriali@ation4 using S$stem4 using S$stem.)eb.Ser"ices.Protocols4 using S$stem.)eb.Ser"ices4 namespace )S3alc ; 5S$stem.)eb.Ser"ices.)ebSer"ice/indingAttribute+ 'ameBFSer"ice:SoapF,

C# AND .NET FRAMEWORK

'amespaceBFhttp#<<www.libert$Associates.com<webSer"ices<F,6 public class Ser"ice: # S$stem.)eb.Ser"ices.Protocols.SoapHttp3lientProtocol ; public Ser"ice:+ , ; this.%rl B Fhttp#<<localhost<)S3alc<ser"ice:.asm0F4 A 5S$stem.)eb.Ser"ices.Protocols.Soap*ocumentMethodAttribute+ Fhttp#<<www.libert$Associates.com<webSer"ices<AddF, &e uest'amespaceB Fhttp#<<www.libert$Associates.com<webSer"ices<F, &esponse'amespaceB Fhttp#<<www.libert$Associates.com<webSer"ices<F, %seBS$stem.)eb.Ser"ices.*escription.Soap/inding%se.Literal, ParameterSt$leB S$stem.)eb.Ser"ices.Protocols.SoapParameterSt$le.)rapped,6 public S$stem.*ouble Add+S$stem.*ouble 0, S$stem.*ouble $, ; ob-ect56 results B this..n"o1e+FAddF, new ob-ect56 ;0,$A,4 return ++S$stem.*ouble,+results5G6,,4 A public S$stem..As$nc&esult /eginAdd+S$stem.*ouble 0, S$stem.*ouble $, S$stem.As$nc3allbac1 callbac1, ob-ect as$ncState, ; return this./egin.n"o1e+FAddF, new ob-ect56 ;0, $A, callbac1, as$ncState,4 A public S$stem.*ouble (ndAdd+S$stem..As$nc&esult as$nc&esult, ; ob-ect56 results B this.(nd.n"o1e+as$nc&esult,4 return ++S$stem.*ouble,+results5G6,,4 A This comple0 code is produced b$ the )S*L tool to build the pro0$ *LL $ou will need when $ou build $our client. The !ile uses attributes e0tensi"el$, but with $our wor1ing 1nowledge o! 38 $ou can e0trapolate at least how some o! it wor1s. The !ile starts b$ declaring the Ser"ice: class that deri"es !rom the class SoapHttp3lientProtocol, which occurs in the namespace called S$stem.)eb.Ser"ices.Protocols public class Ser"ice: S$stem.)eb.Ser"ices.Protocols.SoapHttp3lientProtocol The constructor sets the %&L propert$ inherited !rom SoapHttp3lientProtocol to the %&L o! the .asmx page $ou created earlier. The Add+ , method is declared with a host o! attributes that pro"ide the SOAP goo to ma1e the remote in"ocation wor1. The )S*L application has also pro"ided as$nchronous support !or $our methods. 2or

C# AND .NET FRAMEWORK

e0ample, !or the Add+ , method, it also created /eginAdd+ , and (ndAdd+ ,. This allows $ou to interact with a web ser"ice without per!ormance penalties. To build the pro0$, place the code generated b$ )S*L into a 38 Librar$ pro-ect in 9isual Studio .'(T and then build the pro-ect to generate a *LL. /e sure to write down the location o! that *LL, as $ou will need it when $ou build the client application. To test the web ser"ice, create a "er$ simple 38 3onsole application. The onl$ tric1 is that in $our client code $ou need to add a re!erence to the pro0$ *LL -ust created. Once that is done, $ou can instantiate the web ser"ice, -ust li1e an$ locall$ a"ailable ob-ect# )S3alc.Ser"ice: the)ebS"c B new )S3alc.Ser"ice:+ ,4 7ou can then in"o1e the Pow+ , method as i! it were a method on a locall$ a"ailable ob-ect# !or +int i B N4i=:G4 iHH, !or +int - B :4- =:G4-HH, ; 3onsole.)riteLine+ F;GA to the power o! ;:A B ;NAF, i, -, the)ebS"c.Pow+i, -,,4 A This simple loop creates a table o! the powers o! the numbers 2 through 9, displa$ing !or each the powers 1 through 9. The complete source code and an e0cerpt o! the output is shown below A Client Pro'ra) to test t-e calculator 1e& service using S$stem4 << dri"er program to test the web ser"ice public class Tester ; public static "oid Main+ , ; Tester t B new Tester+ ,4 t.&un+ ,4 A public "oid &un+ , ; int "ar: B E4 int "arN B O4 << instantiate the web ser"ice pro0$ )S3alc.Ser"ice: the)ebS"c B new )S3alc.Ser"ice:+ ,4 << call the add method 3onsole.)riteLine+F;GA H ;:A B ;NAF, "ar:, "arN, the)ebS"c.Add+"ar:, "arN,,4 << build a table b$ repeatedl$ calling the pow method !or +int i B N4i=:G4 iHH, !or +int - B :4- =:G4-HH, ;

C# AND .NET FRAMEWORK

3onsole.)riteLine+F;GA to the power o! ;:A B ;NAF, i, -, the)ebS"c.Pow+i, -,,4 A A A Output (excerpt): E H O B :N N to the power o! : B N N to the power o! N B L N to the power o! K B M N to the power o! L B :P N to the power o! E B KN N to the power o! P B PL N to the power o! O B :NM N to the power o! M B NEP N to the power o! Q B E:N K to the power o! : B K K to the power o! N B Q K to the power o! K B NO K to the power o! L B M: K to the power o! E B NLK K to the power o! P B ONQ K to the power o! O B N:MO K to the power o! M B PEP: K to the power o! Q B :QPMK 7our calculator ser"ice is now more a"ailable than $ou might ha"e imagined through the web protocols o! HTTP-?et, HTTP-Post, or SOAP. 7our client uses the SOAP protocol, but $ou could certainl$ create a client that would use HTTP?et# http#<<localhost<)S3alc<Ser"ice:.asm0<AddR0BNKC$BNN .n !act, i! $ou put that %&L into $our browser, the browser will respond with the !ollowing answer# =R0ml "ersionBF:.GF encodingBFut!-MFR> =double 0mlnsBFhttp#<<www.libert$Associates.com<webSer"ices<F>LE=<double> The 1e$ ad"antage SOAP has o"er HTTP-?et and HTTP-Post is that SOAP can support a rich set o! datat$pes, including all o! the 38 intrinsic t$pes +int, double, etc.,, as well as enums, classes, structs, and A*O.'(T *ataSets, and arra$s. Also, while HTTP-?et and HTTP-Post protocols are restricted to name<"alue pairs o! primiti"e t$pes and enums, SOAPJs rich XML grammar o!!ers a more robust alternati"e !or data e0change. S("PS +O# C#"A(I ! (0" P#O.* open "isual studio command prompt got to !# paste the url copied in +that is the url chnaged to wsdl, press enter a !ile will be created in 38 .n the "isual studio c8 console t$pe.Fnamespace wscalcF a!ter usingI statements.

10

C# AND .NET FRAMEWORK

.n the command prompt, t$pe csc 2t:li&rary Service.cs clic1 enter A dll !ile will be created in 2# got to new->pro-ect->console application write the client program in the console ?o to colution e0plorer. right clic1 re!erence Add re!erence+i.e add s$stem.we.ser"ices, clic1 o1 again rightclic1 re!erences->add re!ernces .n the window displa$.clic1 browse.and add the dll !ile created earlier clic1 o1

11