Professional ASP.NET 1.0 Special Edition- P37 potx

Now that we've had a foundation in UDDI and WSDL, let's shift our discussion towards actually using WSDL to build a proxy class that is capable of calling a Web Service. Building Web Service Proxies A proxy does work on behalf of others. A good example is proxy web server software. Users configure their web browser to use a proxy server and make requests for Internet resources, such as http://msdn.microsoft.com/ to the proxy. The proxy then makes a request on the behalf of the browser to the requested URL. We can use proxy classes to represent the Web Service we want to call. In the previous chapter we created a class named Fibonacci, that supports a single method called GetSeqNumber. We compiled the class into a .NET assembly and deployed it to an ASP.NET application's \bin directory (on the server). We can use this assembly as both a Web Service and a local class inside an ASP.NET page. For example, we could write the following ASP.NET page (using VB .NET): <script runat="server"> Public Sub Page_Load(sender As Object, e As EventArgs) Dim fibonacci As New Fibonacci() result.Text = Fibonacci.GetSeqNumber(5) End Sub </script> Index of 5 in the Fibonacci Series is: <asp:literal id="result" runat="server"/> However, we've also implemented this class as a Web Service, which means that we also have the ability to call the GetSeqNumber method via SOAP over a network. The question is, can we expect applications that wish to use our Fibonacci Web Service to work with the raw SOAP messages (the HTTP and XML) directly? Probably not. Consumers of our Web Service should not have to formulate their own XML messages, and then encapsulate those messages in HTTP in order to send them to the appropriate destination. The same is true for receiving messages. What consumers should use is a proxy representation of the Web Service. Fibonacci Proxy The WSDL describes the Web Service and because the WSDL is so complete, we can create a proxy class using tools that are capable of reading the WSDL. For example, we can build a proxy class for our Fibonacci Web Service that will have a class named Fibonacci and a method named GetSeqNumber. The proxy class does not contain the actual implementation (the code that calculates the sequence number), since this is not described in the WSDL. The implementation still resides within the Web Service we're calling. However, the proxy does look and feel the same. It has the same class name and same method name/parameters as a local Fibonacci class, but the methods wrap calls to the remote Fibonacci Web Service. For example, here's the VB .NET pseudo-code for a proxy implementation of Fibonacci: Public Class Fibonacci Inherits SoapHttpClientProtocol Public Sub New() MyBase.New Me.Url = "http://[Server]/Fibonacci_cs.asmx" End Sub Public Function GetSeqNumber(ByVal fibIndex As Integer) As Integer Dim results() As Object = Me.Invoke("GetSeqNumber", _ New Object() {fibIndex}) Return CType(results(0),Integer) End Function End Class In this pseudo-code we have a class named Fibonacci, and a single function named GetSeqNumber. The proxy function name and parameters look identical to the Web Service implementation, but the actual implementation (highlighted) is obviously different. Here we have two lines of code. The first line uses the Invoke() function to call the Web Service and return a result. The second line uses the VB .NET CType() function to cast the return data, results(0), to an Integer: Public Function GetSeqNumber(ByVal fibIndex As Integer) As Integer Dim results() As Object = Me.Invoke("GetSeqNumber", _ New Object() {fibIndex}) Return CType(results(0),Integer) End Function Let's expand this a little further. Imagine if our Fibonacci Web Service was implemented on a server residing in New York, while the application that wished to call it was in Seattle. Our Seattle application could examine the WSDL of the New York Fibonacci Web Service, and construct a proxy class similar to the example above. The application could then write a ASP.NET page that, when requested, would use the local proxy to call the Fibonacci Web Service in New York. The New York Web Service would then perform the work and return the result back to the application in Seattle that called it: The ASP.NET Page that uses the Fibonacci proxy might look as follows (written using VB .NET): ' Seattle ASP.NET application <script runat="server"> Public Sub Page_Load(sender As Object, e As EventArgs) Dim fibonacci As New Fibonacci() lblResult = Fibonacci.GetSeqNumber(5) End Sub </script> Index of 5 in the Fibonacci Series is: <asp:label id="lblResult" runat="server"/> To the Seattle developer who is coding the application, it appears as if Fibonacci is a local class, when in fact the class is a proxy of the New York Web Service. Now that we know what a proxy is used for, let's talk about how can we automate its creation? Creating Proxy Classes There are four ways to create proxies for Web Services:  Use Visual Studio .NET and add a Web Reference to a new project.  Use the command-line wsdl.exe utility available with the .NET Framework SDK.  Use the Microsoft SOAP toolkit.  As long as the platform is capable of sending and receiving HTTP and is capable of parsing strings (or supports XML) you've got everything you need to communicate with a Web Service, so we could roll our own using the technology of our choice. Although all the examples in this chapter will use ASP.NET Web Services, the .NET technology used to create the proxies could be applied to any Web Service so long as it uses SOAP. Because this book is about .NET, we're only going to focus on the first two options for building proxies: Visual Stuido.NET and the wsdl.exe command-line tool. The second option, using the command-line tool wsdl.exe, is applicable if you don't have Visual Studio .NET. However, using Visual Studio .NET, is by far the easiest method available. Let's start by looking at how we build a proxy using Visual Studio .NET. After we use both Visual Studio .NET and the command-line tool to build and use a proxy, we'll come back and examine the auto-generated proxy class in more detail. For both examples we'll use the Fibonacci Web Service we created in the previous chapter. Visual Studio .NET If you've built an application using Visual Basic 6 you're probably familiar with the AddReference option, available from any VB project under Project|Add Reference, that allowed us to reference a component we wanted to include in our project. Including a reference allows us to early-bind to the object, instead of late binding. Early binding simply allows us to know the data types at run-time/compile time, while late binding would force the code to determine the data types at run-time. For example, late-bound code would be as follows (this code is written in Visual Basic 6 and so makes use of the Object data type): Dim objAdo As Object Set objAdo = CreateObject("ADODB.Connection") With late-bound code we would treat an instance of ADODB.Connection as an Object type and VB would be responsible for calling the appropriate methods at run-time. Late binding is expensive, and we want to avoid it where possible because the application needs to infer the appropriate data types to use at run-time. Instead of writing late-bound code, we could use the AddReference option in VB to add a reference at design time. Our code would then become: Dim objAdo As New ADODB.Connection VB would treat objAdo as an instance of type ADODB.Connection at run-time. Visual Studio .NET continues to support the concepts of early and late binding, as well as the Project | Add Reference option. However, we have a new option specifically designed for Web Services: Project | Add Web Reference. Add Web Reference Just as we can early-bind to local classes, Visual Studio .NET supports the capability to early-bind to Web Services. When we add a Web Reference to a Visual Studio .NET project (the AddWebReference option is available to all Visual Studio .NET projects and languages) VisualStudio.NET will do all the work required to connect to the Web Service, parse the WSDL, and it will generate a proxy class that we can use. Using the Fibonacci Web Service Let's look at an example using our Fibonacci Web Service. Before we can create the Web Reference we need to know the location of the WSDL for the Web Service we want to create the reference to. For example, the address of the WSDL for the VB .NET Fibonacci implementation of the ASP.NET Web Service on my server is http://localhost/WebServices/Fibonacci_vb.asmx?WSDL. Next, let's create a new Visual Studio .NET project. Since this book is about ASP.NET, we'll create a new ASP.NET Web Application using Visual Basic .NET as our language. Once Visual Studio .NET creates the new Web Application we're presented with a design page. We can drag-and-drop elements onto this page. For this example, we'll need a textbox, a label, and a button: We'll leave the names of each of these items the same, that is, TextBox1, Button1, and Label1. Now we're ready to add our Web Reference. We have two options, we can either select Project | Add Web Reference or we can right-click on the References in the Solution Explorer and select Add Web Reference. Both open the Add Web Reference dialog box: Within this dialog box we can browse services provided by UDDI (the link to Microsoft UDDI takes us to the Microsoft UDDI implementation), browse Web References on the local server (for Web Services we created with Visual Studio .NET), or enter the address ourselves. Enter the address of our Fibonacci Web Service: On the left-hand side of the Add Web Reference dialog we can view the WSDL. Essentially what has happened is that Visual Studio .NET fetched the WSDL from the location we specified and validated it. The Add Reference button is now enabled and we are able to add a reference to the Web Service described by this WSDL to our current project (at which point Visual Studio .NET will create a proxy). Go ahead and press Add Reference. Visual Studio .NET will quietly create a new section in our Solution Explorer entitled Web References. Behind the scenes Visual Studio .NET has parsed the WSDL, created a proxy object that represents the Web Service (the namespace of the proxy is the name of the server the WSDL was served from, in our case localhost), and cached a local copy of the WSDL. This is all visible to us if we expand the Web References section with the Solution Explorer : We can now write code in our Web Application to use the Fibonacci Web Service. Double-click on Button1 and write some code for the Button1_Click event handler. Once the code view is open, write the following to call the GetSeqNumber of the Fibonacci Web Service: Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click Dim fibonacci As New localhost.Fibonacci() Dim indexIntoSeries As Integer indexIntoSeries = TextBox1.Text Label1.Text = fibonacci.GetSeqNumber(indexIntoSeries) End Sub We first create an instance of the proxy, fibonacci, by calling New localhost.Fibonacci(). Changing the namespace in this example from localhost to some more meaningful value, such as MathServices, is as simple as right-clicking on localhost in the Solution Explorer and selecting rename. Next, we declare a local variable, indexIntoSeries. This is used as the parameter value for the call to GetSeqNumber(). Next, we extract the value from TextBox1 and assign it to indexIntoSeries - so the user must enter an Integer value. We then use our instance, fibonacci, calling the GetSeqNumber() method and passing in the value of indexIntoSeries. When the call completes, an Integer is returned, the value of which we assign to Label1.Text. Here's a high-level rundown of what occurs when we run this application and click on Button1:  ASP.NET creates an instance of the proxy, and calls it, passing in the value of TextBox1.  The proxy then calls the Fibonacci Web Service via SOAP which, in turn, computes the result, and sends it back to the proxy via SOAP.  The proxy then de-serializes the SOAP message (converts the values within the SOAP message to .NET types) and returns an Integer value, which is displayed to the end user. Let's take a look at the sourcecode that Visual Studio .NET created. Viewing the Source for the Proxy Behind the scenes Visual Studio .NET has obviously done a lot of work for us - it's created the proxy that can send and receive the SOAP requests and responses. We can access, and modify, the sourcecode that Visual Studio .NET creates and compiles for our proxy. It's not available to us by default, but if we right-click on our project in Solution Explorer and select Add Existing Item, a file selection dialog box is opened. The location that the file dialog box is currently accessing is the root directory of our project. We should see a folder named localhost (or another name if you renamed the Web Reference). If we open this folder we find the source to our proxy. On my server the source file is Fibonacci_cs.vb. [...]... proxy's CookieContainer and call the GetSession method We've encapsulated all of this work in one ASP.NET page, but it could just as easily be applied to an entire web application, which would allow us to use ASP.NET Session state for Web Services across our application Let's look at another feature that ASP.NET Web Services make easy- converting any web site into a Web Service From Web Site to Web Service... compilers is identical and after executing this statement the result is a dll file named fibonacci_cs.dll We can copy either of these dll files (we only need one of them) to an ASP.NET application's \bin directory We can then build an ASP.NET application that uses this proxy, just as we did with Visual Studio NET For example: Private Sub Page_Load(sender As Object, e As EventArgs)... by simply setting /n:MathSamples The /out parameter allows us to name the source file created by wsdl.exe By /out: default the name of this source file is [service name].[language extension] ASP.NET Web Services support three protocols: HTTPGet, HTTPPost, and SOAP By default SOAP is the protocol used for client proxies and is what WSDL /protocol: will instruct the proxy class to... proxy server with /proxydomain: The name of the proxy user's domain to authenticate to the proxy server with Rather than hard-coding the URL specified in the WSDL document, a URL can be stored in ASP.NET configuration system's section We can use /appsettingsurlkey: the appsettingsurlkey parameter with wsdl.exe to name the key that corresponds to the value stored in the configuration... slow Web Service Another inherited property of the proxy, Url, allows us to set the end-point URL that the proxy sends requests to Setting the URL When we build a proxy from a WSDL document generated by ASP.NET, the default end point of the service is already provided Here's a snippet of the WSDL for our Fibonacci Web Service: ... web proxy server then issues the request and returns the result to the caller If the web proxy server requires credentials, these can be set as part of the System.Net.WebProxy class Maintaining State ASP.NET Web Services use HTTP as the transport protocol for messages Additional transport protocols can be used to route SOAP, including SMTP and UDP, but HTTP will be the most commonly used protocol Accordingly,... HTTP protocol features, such as cookies Just as we would with a browser-based application, we can use HTTP cookies to pass 'additional' data along with SOAP messages The most common use of cookies in an ASP.NET Web Service would be to maintain a Session on the server that is providing the Web Service For example, the following Web Service (written using VB NET) uses Session state to retain values on the... SetSession(key As String, item As String) Session(key) = item End Function _ Public Function GetSession(key As String) As String Return Session(key) End Function End Class This ASP.NET Web Service has two functions defined as Web Services: SetSession() - allows us to pass a key and item (both strings) and uses the key value to create an entry in Session for the value GetSession()... cookies within our proxy This is done by creating an instance of a CookieContainer class and assigning that instance to the proxy's CookieContainer property If we intend to maintain state through the use of ASP.NET session state within the Web Service we need to re-present the HTTP cookie on each subsequent use of the proxy by our application The Cookie that the proxy receives is only valid for the life of... (IsNothing(sessionCookie)) Then sessionExample.SetSession("name", "rob") cookieCollection = sessionExample.CookieContainer.GetCookies( _ New Uri("http://localhost")) Session("sessionCookie") = cookieCollection( "ASP.NET_ SessionId") Else sessionExample.CookieContainer.Add(sessionCookie) End If lblSession1.Text = sessionExample.GetSession("name") End Sub Value: . proxy is ninety seconds. The following VB .NET code illustrates a simple Add Web Service that performs slowly due to a call to Thread.Sleep( 200 00) that forces the thread to wait 20 seconds. .NET project. Since this book is about ASP. NET, we'll create a new ASP. NET Web Application using Visual Basic .NET as our language. Once Visual Studio .NET creates the new Web Application. into a .NET assembly and deployed it to an ASP. NET application's in directory (on the server). We can use this assembly as both a Web Service and a local class inside an ASP. NET page.