Developing a Web Service Client


Now that we’ve developed a few simple Web services, it’s time to write a client that makes use of it. Almost any part of an application, be it desktop-based or Web-based, can consume a Web service. A Windows Forms client can present the user with a user interface affected by a Web service, and a interfaceless client, such as a .NET component or even another Web service, can exercise some sort of autonomous operation that doesn’t require a human user to see the results.

As you’ve seen, the .NET Framework has a great deal of support for Web service development, and developing a client can be even easier than writing the service! It’s just a matter of implementing two tasks—finding the service you want to use and referencing it.

A Simple Windows Forms Client

Let’s whip up a simple Windows Forms client for the three Web services we’ve created. Each of these Web services exposes a single method that takes a user-defined value as a parameter and returns a string, so for each service we’ll provide a text box, a Submit button, and a label for the service to populate.

Start up a new C# Windows Forms Application project in Visual Studio .NET and call it SimpleClient. Add a text box, a button, and a label for each of the simple Web services we created earlier—simple1.asmx, simple2.asmx, and simple3.asmx (as shown in Figure 1-11). For simple1.asmx, the text box, the button, and the label should be called SvcInput1, Submit1, and SvcOutput1, respectively.

click to expand
Figure 1-11: A simple Windows Forms client for our Web services

With the basic framework set up, we’ll add in our calls to the Web services. But first we need to find them.

Finding Your Service

If you can access a Web page on a server by using an HTTP request, you can work with a Web service on the same server. Only problem is, with millions of Web servers out there, how do you find the service you want to use? We’ve already touched on UDDI— at this point, we need to make use of it.

Externally with UDDI

As mentioned earlier, UDDI is an open XML-based standard that allows companies to disseminate information about the Web services they have deployed to potential clients on the Web.

Four root UDDI servers (currently known as business registries) maintain and mirror a complete directory of available Web services to sites such as http://uddi.microsoft.com, which developers can browse and search to find a desired service. Their goal is to provide the location of the WSDL file for the service, which unambiguously defines the public interface (behavior) of an XML Web service and tells potential clients how to interact with it. We need to reference this information to make our client.

We’ll look more at UDDI in Chapter 4, but for now, it’s worth noting that UDDI isn’t just something you get at in your browser:

  • Windows Server 2003 contains a UDDI server for companies who want to publicize services available internally but not publicly on the Internet.

  • Visual Studio .NET has a link to the UDDI registries built into the Start Page it displays each time it boots up. Just click on the XML Web Services tab, and if you’re on line, you’ll get the home page for Microsoft’s UDDI server. Visual Studio .NET also has an upload feature that we’ll look at later in the chapter that helps you register your service.

Locally with DISCO

The alternative to using the business-centric UDDI directory is to use .disco and .vsdisco DISCO files for Web service discovery. DISCO is a Microsoft protocol that isn’t a standard, so its use tends to be restricted to Microsoft-centric environments, usually local servers on a LAN. If that’s not a problem and if you already know the server’s location, DISCO can offer you a more straightforward listing of the services available at that location, either generated automatically using .vsdisco files or manually with .disco files.

So, for example, you can advertise a top-level directory on your development server for your team to discover the services to code against without needing to formally register them on a UDDI server. With Dynamic Discovery switched on (it’s off by default), all you need to do is query the list of local discovery files kept in a file called default.vsdisco in the server’s root directory.

If you want to keep a tighter rein on what services are visible on your servers, you can manually create a default.disco file to do the same job, leaving out the undesirables that Dynamic Discovery includes. Each Web service has an autogenerated .disco file that can be found by appending ?disco to the address for the service’s .asmx file, in the same way that you append ?wsdl to the service’s address to generate the service’s WSDL file.

You’ll learn more about both dynamic and static discovery files in Chapter 4.

Adding a Reference

Back to our SimpleClient project in Visual Studio .NET. The upshot of our discussion about finding a service is that to locate our Web services’ WSDL files, we use Visual Studio to locate first their DISCO files and then their description files. Of course, we already know how to get to their WSDL files, but that might not always be the case. Likewise, UDDI entries might point to a service’s .disco or WSDL file—normally the latter.

In Visual Studio, right-click on the SimpleClient project entry in Solution Explorer and choose Add Web Reference from the shortcut menu. A rather large dialog box appears (as shown in Figure 1-12), offering you five choices:

  • Specify the location of a .disco or WSDL file directly

  • Browse Web services on the local machine

  • Browse UDDI servers on the local network

  • Search the UDDI directory of live Web services

  • Search the UDDI directory of Web services still in development

    click to expand
    Figure 1-12: The Add Web Reference dialog box

We’ll have to give the address of the .disco file directly in the dialog box’s Address text box. The addresses of the .disco files for the three simple Web services we created earlier are

  • http://localhost/wscr/01/simple1.asmx?disco

  • http://localhost/wscr/01/simple2.asmx?disco

  • http://localhost/wscr/01/simple3/service1.asmx?disco

Type the first address listed above and click Go. The dialog box will show the contents of the DISCO file, the WSDL file you can reference for the service, and other related material that developers might want to read.

Enter simple1 in the Web Reference Name text box and click the Add Reference button. After a small delay, the reference will have been added into the project (as shown in Figure 1-13), incorporating the service’s .disco and WSDL files and another file called Reference.map that details where the other two were found on the Web. Remember to click Solution Explorer’s Show All Files button if you can’t see these files.


Figure 1-13: Solution Explorer offers easy access to our Web service’s information.

Behind the scenes, Visual Studio .NET generates a proxy class for the service from the WSDL file that allows you to call Web methods as you would any other call. If you switch to the class view pane, you’ll see that the name of the class is derived from the names of the server and service, as shown in Figure 1-14.

The new class contains both synchronous and asynchronous versions of calls to each of the exposed Web methods that you can call directly. The serialization of the calls and their binding to the transport protocol nominated in the WSDL file is transparent. With the proxy class available to our Visual Studio .NET project, all we have to do is incorporate calls to the service into the client application.


Figure 1-14: Class view provides the name of the service proxy class and method signatures.

If you’re wondering why the service is called TryThisOut and not SimpleServices, it’s because we used the WebService attribute to give Simple1.asmx the name TryThisOut. For our client, all we need to do is instantiate an object of type Simple1.TryThisOut and call its WakeUp method when the Submit button is clicked, as follows:

private void Submit1_Click(object sender, System.EventArgs e) {     Simple1.TryThisOut svc1 = new Simple1.TryThisOut();     SvcOutput1.Text = svc1.WakeUp(SvcInput1.Text); }

The last line of code serializes a call to WakeUp using the contents of the SvcInput1 text box as the parameter, sends the request to the service, receives the string result back as a SOAP response, deserializes it, and then sends it to the SvcOutput1 label. As we noted earlier, .NET really does abstract a lot of the conversation with Web services unless you want to get involved. The idea of services as application plug-ins works really well here. As long as the signature of the method calls to the service’s proxy class remains the same, an application can call any plug-in without any need for changes to the code.

Save our simple client application and press F5 to try it out. As an exercise, you can add references to the remaining two services and tie calls to them into the click event of their respective buttons. If you get stuck, you’ll find the solution in the book’s sample files.

Adding a Reference Manually

If you don’t have a copy of Visual Studio .NET, you can achieve what adding a Web reference does in Visual Studio .NET by using a pair of command-line tools in the .NET Framework SDK (in the bin directory). Because the tools are command-line-based, you of course have more control over what they do and how they do it. As an example, we’ll use Web Matrix to build a Web Forms client for simple1.asmx. We’ll call it SimpleWebClient and add a text box, a button, and a label to the form, just as we did with the Windows Forms client. (See Figure 1-15.)

click to expand
Figure 1-15: A simple Web client

Disco.exe

We know where the WSDL file for simple1.asmx is, but we’ll use its .disco file to download it to our local drive instead. The first tool, disco.exe, downloads the resource files for a Web service to a place of your choosing, given the .disco file of the service on the network. The basic syntax for the call is

disco /out:directory_to_save_files url

where url points to the location of the service’s .disco file. The /out flag is optional but handy when the default is to save the files in the directory that you make the call from. If the .disco file requires authentication before it allows access, disco.exe has /password, / username, and /domain flags to let you set the relevant information. For a full list of flags, search for disco.exe in the .NET SDK or type disco /? at the command prompt.

For our example, open a command prompt, navigate to the SDK bin directory, and at the prompt, type the following:

disco /out:WebClient_directory http://localhost/wscr/01/simple1.asmx?disco

We get the following response and downloaded files:

Disco found documents at the following URLs: http://localhost/wscr/01/simple1.asmx?disco http://localhost/wscr/01/simple1.asmx?wsdl The following files hold the content found at the corresponding URLs: WebClient_directory\simple1.disco <- Π    http://localhost/wscr/01/simple1.asmx?DISCO WebClient_directory\simple1.wsdl <- Π    http://localhost/wscr/01/simple1.asmx?wsdl The file WebClient_directory\results.discomap holds links Π    to each of these files.

Wsdl.exe

Now that we have local copies of the discovery files for the simple1.asmx Web service, we need to generate a proxy class for the Web service. We do this with wsdl.exe, which takes the WSDL file and returns a standard .cs file containing the proxy class:

Wsdl /out:name_of_file_to_contain_proxy_class  /language:language  url

Again, wsdl.exe uses the /out, /password, /domain, and /username flags for the same purpose as disco.exe. Three other useful flags are the /language flag, which lets you set the language the class is written in (the default is C#); the /namespace flag, which lets you set the namespace for the generated proxy class; and the /protocol flag, which lets you set the transport protocol the proxy will use to send to and receive from the Web service. The default protocol is SOAP. Again, a complete list of flags can be found in the .NET SDK or by typing wsdl /? at the command prompt.

Note

In some cases, you have to alter the WSDL file for a service before you can run wsdl.exe on it or add the reference in Visual Studio .NET. You’ll learn why in Chapter 3.

To generate the proxy class for simple1.asmx, we make one of the following calls, depending on whether we want the class in C# or in Visual Basic .NET:

Wsdl /out:Simple1Proxy.cs simple1.wsdl

or

Wsdl /out:Simple1Proxy.vb /language:VB simple1.wsdl

With the proxy class file available, we need to compile it into an assembly and then make a reference to the assembly. Again, depending on the language of choice, the call to make is

csc /out:Simple1Proxy.dll /t:library /r:System.XML.dll /r:System.Web.Services.dll Simple1Proxy.cs

or

vbc /out:Simple1Proxy.dll /t:library /r:System.XML.dll /r:System.Web.Services.dll Simple1Proxy.cs 

Manual References

Now we have the proxy assembly ready, and all we need to do is create an instance of the class and call a method on it, as we did with the Windows Forms client. Again, we attach our call to the click event of the Submit button:

void Submit1_Click(Object sender, EventArgs e) {     TryThisOut svc1 = new TryThisOut();     SvcOutput1.Text = svc1.WakeUp(SvcInput1.Text); }

Or, in Visual Basic .NET:

Sub Submit1_Click(sender As Object, e As EventArgs)    Dim svc1 As New TryThisOut()    SvcOutput1.Text = svc1.WakeUp(SvcInput1.Text) End Sub

With the code ready, all that’s left is to deploy our Web form to a Web application and the proxy assembly to the bin directory for that application. We simply call up SimpleWebClient.aspx (as you see in Figure 1-16) to prove it.

click to expand
Figure 1-16: A simple Web Forms client is just as effective as a Windows Forms client.

That’s it for building simple services and clients that use them. The basics aren’t that hard to grasp, but as you can imagine, building on the foundation we’ve just covered can get tricky quite quickly. Indeed, we’ll spend the rest of this book exploring exactly how far we can go from here. But first, let’s get our services out on the Web.




Programming Microsoft. NET XML Web Services
Programming MicrosoftВ® .NET XML Web Services (Pro-Developer)
ISBN: 0735619123
EAN: 2147483647
Year: 2005
Pages: 172

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net