Using the Web Service from Code

Before you can use a Web service, you obviously need to locate it and find out how you need to use it. Visual Studio .NET uses Web references to represent Web services wherever they are located. It also has tools to locate services, and you can browse your local computer; a Universal Description, Discovery, and Integration (UDDI) server; or the Internet in general.

Note

UDDI is a mechanism for Web service providers to advertise the existence of their services and for clients to locate Web services of interest.

When you find a service that you want to use, Visual Studio .NET will use the DISCO discovery service to retrieve the WSDL file that describes the service. Client code needs to be able to find the Web service at run time and to communicate with it. Adding a Web reference to your project uses the WSDL information to create a proxy class that takes care of finding and communicating with the service, so all you have to do is work with a local object that exposes the same methods as the remote service.

Note

If you’ve ever used remote COM objects from Microsoft Visual C++ code, you’ll see similarities in the way you use Web services.

The following exercise shows you how to use the Web service that you created earlier in the chapter. This exercise assumes that you have built and installed the service and that it’s running on a local Web server.

1. Create a new Visual C++ Console Application (.NET) project named TempClient. Leave the definition of the _tmain function as it is because you won’t require any command-line arguments.

2. Add a Web reference to the project, either by choosing Add Web Reference on the Project menu or by right-clicking the project in Solution Explorer and selecting Add Web Reference from the shortcut menu. This will bring up the Add Web Reference dialog box.

   

   You have three ways to locate the Web service. First, if it’s registered with the Microsoft UDDI service, you can click the UDDI links. Second, if you know the location of the service, you can enter a URL in the Address bar. If you installed the Converter service on a remote machine, enter the URL. Otherwise, the service lives on the local server, so you can use the third option and click the linked phrase Web Services On The Local Machine to display locally registered services.

   Note

   It might take several seconds to activate this link while the server uses dynamic discovery to build its list of services.

   Details of the dynamic DISCO file for the local server, which links through to the local Web services will display. As you’ll see from the following figure, I have a number of experimental Web services installed on my computer.

   

3. Find the Converter service in the list, and click it. The same test page that you’ve already seen will display.

   

   You can use the test page to retrieve more information about the service and see how the methods work.

4. Because we know that the service works and what it does, click the Add Reference button to create the reference proxy.

   When the process has finished, you’ll find that a new file named WebService.h has been added to the project, which simply includes a file named localhost.h. You’ll find that you get a header file generated for each Web service host. Because this example uses a service from the local machine, code is placed in a file named localhost.h. This header file defines #using directives and the definition for the proxy class. You’ll also see that a namespace localhost is used to contain the ConverterClass class. The namespace is named after the Web service host and is included so that you won’t get name clashes if you reference Web services with the same name on different hosts.

   The proxy code has been generated in C++, and if you want, you can browse the code in localhost.h to see how the proxy has been implemented.

   Note

   In Visual Studio .NET 7, the proxy class was created in Microsoft Visual C# and compiled into a separate DLL. Version 7.1 creates the proxy in C++ and compiles it into the project, so there is no separate proxy DLL.

5. Add an #include to include WebService.h in the TempClient.cpp file, and also add a using directive for the localhost namespace so that you won’t have to use fully qualified names.

6. Add code to the _tmain function to create and access the Web service.

   int _tmain() { Console::WriteLine(S"Web Service Test"); try { // Create a proxy object ConverterClass* conv = new ConverterClass(); // Call a conversion method... double fahrVal = conv->ConvertC2F(10.0); Console::WriteLine(S"10C is {0}F", __box(fahrVal)); } catch(Exception* pe) { Console::WriteLine(pe->Message); } return 0; }

   The proxy class that has been provided by you has the same name as the deployment project, so the class name here is ConverterClass.

   You can create a new ConverterClass object just like any other .NET object and call its ConvertC2F method to convert a value. This might not seem like a particularly impressive demonstration, but remember that the Web service could be installed anywhere on the Internet and could be written in any language. In fact, it’s not even necessary for the service to be written using the .NET Framework at all.

Debugging Web Services

Debugging a Web service is quite simple. Make sure that you’ve built a debug version of the Web service code. This is the default build configuration, so if you haven’t changed anything, you’ll have a debug version. To debug a Web service, place a breakpoint in the C++ code at the place you want to start debugging by clicking in the gray margin to the left of the code window. A red dot will show you where the breakpoint is located. Now press F5 to run the service under the debugger. After a few seconds, Internet Explorer starts, displaying the documentation of the Web service. You can now interact with the Internet Explorer window just as you did in the “Using the Web Service from a Browser” section earlier in this chapter.

Select the method that you want to debug, and bring up the test page, as shown in the figure on page 480. When you click Invoke, you’ll find yourself back in the Visual Studio .NET environment, where you can debug the C++ code in the normal way.

If You’re Not Using Visual Studio .NET

You can still use Web services even if you’re not using Visual Studio .NET. The wsdl.exe command-line tool supplied as part of the .NET Framework SDK will generate a proxy for you in exactly the same way as the wizard does in Visual Studio .NET.

The following command line shows how you could create a proxy by hand for talking to the Converter service:

wsdl /l:cs /protocol:SOAP http://localhost/Converter/Converter.asmx?WSDL

The /l (or /language) argument determines the language the proxy will be written in. You’ve got a choice of Microsoft Visual Basic (VB), Microsoft JScript (JS), or Visual C# (CS), but not C++. The default is CS if you don’t specify a language. The /protocol argument defines the protocol that’s going to be used to talk to the service. I’ve chosen SOAP, but you can also specify HttpPost or HttpGet. The final argument is the URL of the Web service, and you can also specify a WSDL file if you have one available.

You can build the proxy code into a DLL using the following command line:

csc /t:library /r:system.web.services.dll /r:system.xml.dll /r:system.data.dll Converter.cs

The command line tells the C# compiler to compile Converter.cs into a DLL and gives the references to the DLLs containing the .NET classes that will be used. Once you’ve built this DLL, you can add #using to any project to use the Web service.