Creating a Web Service | Observing the User Experience: A Practitioners Guide to User Research

In this section you ll learn what s involved in creating a Web service and how ATL Server helps simplify many of the tasks involved in this process for you.

Creating a Web Service by Hand

To create a Web service by hand (without using any libraries or frameworks), you have to complete a number of tasks. The following steps outline the tasks you normally need to perform to correctly handle the reception of a SOAP message:

Determine the intended recipient of the message (e.g., the HelloWorld function).
Parse the XML of the message and marshal the parameters (e.g., inputString ) into real C++ data types (e.g., a string).
Call the intended recipient of the message ( HelloWorld ) with the expected parameters ( inputString ).
After the function, take the output parameters and return value and generate a SOAP HTTP response message to send back to the client.

This doesn t even account for a situation where you intend the Web service to be callable from any client, in which case WSDL for the Web service also needs to be generated.

As you can clearly see, there s a lot of code involved in creating a Web service infrastructure, and most of this code actually needs to be duplicated for every exposed function. All of these issues must be resolved before you can focus on implementing your Web service functionality. Plus, all of this work only enables you to create Web service services ”it doesn t include the infrastructure code required to create a Web service client!

Creating a Web Service with ATL Server

ATL Server is designed to solve the problems mentioned in the preceding section for you and make creating a Web service easy. ATL Server does this by allowing you to focus on implementing your application logic and not on the underlying infrastructure code.

Using the ATL Server Web Service Wizard

From the Visual Studio .NET New Project dialog box, choose the Visual C++ Projects folder, and then choose the ATL Server Web Service project.

You ll notice that the wizard dialog box that appears is nearly identical to that of the ATL Server Project Wizard described earlier. In fact, it s the same wizard, just with different default settings. The Application Options tab has the Create as Web Service box checked by default. Almost all the options and settings described earlier for ATL Server are available for ATL Server Web services. A few options are unavailable (they re grayed out). In the Application Options tab, the Validation Support and Stencil Processing Support options aren t available, because those options apply only to ATL Server projects that will handle Web page requests (i.e., SRF-based pages). Similarly, the locale and codepage options are unavailable because Web services don t use SRF files. On the Developer Support Options tab, the Attributed Code check box can t be unchecked, because ATL Server Web services require the use of attributes.

The ATL Server Web Service Wizard will generate the following Web service files ( assuming that the project s name is MyProject):

MyProject.h: Contains your Web service implementation
MyProject.disco: The Web service .disco file
MyProject.htm: A description of the Web service

The default Web service generated by the wizard is a simple Hello World “ style Web service that shows how a basic ATL Server Web service works:

 [    uuid("989438E7-DC64-4C1E-9B7D-18AE00BA8EE2"),    object  ]  __interface IMyProjectService  {    // HelloWorld is a sample ATL Server Web service method. It shows how to    // declare a Web service method and its in-parameters and out-parameters    [id(1)] HRESULT HelloWorld([in] BSTR bstrInput, [out, retval] BSTR *bstrOutput);    // TODO: Add additional Web service methods here  };

First, embedded IDL is used to declare a COM interface that describes the Web service.

Through attributes, embedded IDL is now available to all COM developers and Web service developers. The COM-like syntax was chosen for a few very specific reasons. The benefit of choosing a COM-like syntax is that it enables COM developers to protect their existing investment. In terms of a similar coding style, it helps COM developers protect their existing investment in their knowledge of COM development. In terms of similar code (embedded IDL), it enables COM developers to easily protect their investment in existing code, making it easy for these developers to expose existing or new COM objects as Web services if they desire (with just a few lines of code).

The IDL attributes are used to specify the parameters of the Web service methods being exposed. In the wizard-generated code example, the HelloWorld method has two parameters, both of which are BSTRs: bstrInput and bstrOutput (in the next section we describe Web service types and their mappings to XSD). The IDL in attribute is used to specify that the bstrInput parameter is a part of the SOAP request , and the IDL out attribute is used to specify that the bstrOutput parameter is part of the SOAP response (in the next section we describe all the SOAP attributes in detail). Listing 10-2 shows the sample Hello World Web service.

Listing 10.2: Hello World Web Service

 [    request_handler(name="Default", sdl="GenProject1WSDL"),    soap_handler(      name="MyProjectService",      namespace="urn:MyProjectService",      protocol="soap"    )  ]  class CMyProjectService : public IMyProjectService  {  public:  // This is a sample Web service method that shows how to use the  // soap_method attribute to expose a method as a Web method    [ soap_method ]    HRESULT HelloWorld(/*[in]*/ BSTR bstrInput, /*[out, retval]*/ BSTR *bstrOutput)    {      CComBSTR bstrOut(L"Hello ");      bstrOut += bstrInput;      bstrOut += L"!";      *bstrOutput = bstrOut.Detach();      return S_OK;    }  // TODO: Add additional Web service methods here  }; // class CMyProjectService

The CMyProjectService class implements the Web service described by the interface we examined previously.

The request_handler attribute (described earlier in the context of normal ATL Server Web applications) now has the additional sdl parameter, which specifies the handler name for retrieving the WSDL for the Web service. The soap_handler attribute specifies that the request handler is also a SOAP Web service (i.e., it will contain methods that will need to be able to decode incoming SOAP and encode outgoing messages as SOAP). The class inherits from the IMyProjectService interface and implements the HelloWorld method.

The soap_method attribute specifies which methods from the IMyProjectService interface are to be exposed via SOAP. The HelloWorld method is implemented as any COM method would be implemented, without any special processing required as a Web service method.

Consuming ATL Server Web Services

In this section we describe how to consume ATL Server Web services using Visual Studio .NET s Add Web Reference dialog box. You can use the options on this dialog box to consume any kind of Web service that exposes a WSDL description. The dialog box generates a proxy class that you can use to invoke a method on the Web service by simply calling the matching method in the proxy class. The dialog box generates an ATL Server native C++ proxy for C++ projects (in 2002), in 2003 managed C++ projects generate managed C++ proxies (native remains ATL Server).

In Solution Explorer, right-click the project to which you want to add the Web service proxy class and choose Add Web Reference. Enter the location of the Web service s WSDL for the address, for example, http://localhost/MyProjectService/ MyProjectService.dll?Handler=GetWSDL . The Add Web Reference dialog box lists the WSDL that you ve selected. You have the option of viewing the documentation for the Web service (if it exists). Click the Add Reference button to generate the proxy class. For example, if you re adding a Web reference to a Visual C++ project, an ATL Server proxy class will be generated using the sproxy.exe tool. The Build Output window should appear and show something like the following:

 ------ Build started: Project: Proxy1, Configuration: Debug Win32  Creating Web service proxy file...  /out:MyProjectService.h  Build log was saved at "file://c:\Code\Proxy\Debug\BuildLog.htm"  Proxy1 - 0 error(s), 0 warning(s)  ---------------------- Done ----------------------     Build: 1 succeeded, 0 failed, 0 skipped

As the output suggests, the Web service proxy class is generated in the file MyProjectService.h.

The generated proxy class will have methods that map to the methods in the Web service. In this example, there will be a HelloWorld method in the proxy class that can be called to invoke the HelloWorld method in the Web service:

 HRESULT HelloWorld(    BSTR bstrInput,    BSTR* __retval  );

To invoke the method, create an instance of the proxy class and simply call the method as you would normally:

 #include "MyProjectService.h"  int main()  {    CoInitialize(NULL);    {      MyProjectService::CMyProjectService svc;      CComBSTR bstrOut;      svc.HelloWorld(CComBSTR(L"Joe"), &bstrOut);      printf("%ws\n", bstrOut);      return 0;    }    CoUninitialize();  }

When you run your program, it will output Hello Joe! .

You ve covered the basics of creating and consuming ATL Server Web services in Visual Studio .NET. Now it s time to become more familiar with using ATL Server.