- Overview of Web Services and .NET
- Creating a Simple Web Service
- Using a Web Service Within an Application
- Summary
- Q&A
- Workshop
This chapter is from the book
This chapter is from the book
This chapter is from the book
Creating a Simple Web Service
Visual Studio .NET provides a template for creating a new Web Service using managed C++ and the .NET Framework. The template provides the basic foundation for writing a Web Service. However, once the base Web Service code is created, the rest of the implementation is up to you.
Creating the New Project
You start creating a new Web Service by selecting the New, Project menu item from the main menu and selecting the Managed C++ Web Service option, as shown in Figure 11.2.
){kind=link}
Figure 11.2 The New Project dialog with the Managed C++ Web Service project selected.
Name the new Web Service WebService and select the OK button to create the Web Service project. Table 11.1 lists the files created and their descriptions.
Table 11.1 Managed C++ Web Service Files Created by Visual Studio's Template
|
Filename |
Description |
|
WebService.cpp |
The main Web Service source file. |
|
WebService.asmx |
The Web Service description file that describes the service. This file will only contain a reference to the Web Service class. |
|
WebService.h |
The header file for the Web Service source file. This file includes the class declaration of the Web Service. |
|
WebService.vsdisco |
The discovery file for the Web Service. |
|
Web.config |
A Web configuration file that controls how the Web Service is treated on the Web server. |
|
Global.asax |
A Web Service description file that describes the Global class within the Web server. |
|
Global.asax.h |
The Global class declaration and definition. The Global class is derived from HttpApplication and provides entry points for when the application starts and ends, when a session begins and ends, and when a request begins and ends. |
|
AssemblyInfo.cpp |
This file contains the custom attributes for the Web Service assembly. Attributes are a new feature within Visual Studio .NET that allow common pieces of code to be substituted with replacement tags. You will learn more about attributes in Hour 16. |
|
Stdafx.cpp |
A common C++ file for any global classes. By default, there isn't anything defined other than the include file stdafx.h. |
|
Stdafx.h |
A common include file for the WebService project. Includes the .NET Framework components required for the Web Service. |
Compiling and Debugging the Default Web Service
Compiling and running the default Web Service builds a "Hello, World!" Web Service. The building of a Web Service differs, however, in the building of a regular application. It also includes the deployment of files onto your local Web server (IIS). After your Web service DLL has been built, a temporary XML document is created listing the files that will be deployed to your IIS Web publishing directory. The files that are published and needed to use the Web service include WebService.asmx, Global.asax, Web.config, and WebService.vdisco. Furthermore, the DLL that contains your actual Web Service is placed in a subdirectory named bin. Once the temporary XML file is built, the build process then invokes the Web deployment tool named VCDeploy.exe, which performs the necessary file operations to place your Web Service files onto your local Web server. All this happens by default without you having to make any necessary project setting changes, leaving you to concentrate on your code instead.
It is worth looking at to see how Visual Studio deals with debugging the Web Service. Open the WebService.cpp file and place a breakpoint on the return value statement, as shown in Listing 11.1.
Listing 11.1 WebService.cpp—MyCPPWebService HelloWorld() Method Implementation
1: #include "stdafx.h"
2: #include "WebService.h"
3: #include "Global.asax.h"
4:
5: namespace WebService
6: {
7: // WEB SERVICE EXAMPLE
8: // The HelloWorld() example service returns the string "Hello, World!".
9: // To test this web service, ensure that the .asmx file in the deployment
10: //path is set as your Debug HTTP URL, in project properties and press F5.
12:
13: String __gc* MyCPPWebService::HelloWorld()
14: {
15:
16: // TODO: Add the implementation of your Web Service here
17:
18: return S"Hello World!";
19:
20: }
21: };
After you set the breakpoint, pressing F5 will compile the Web Service and start the debugger. Once the Web Service is started, the page shown in Figure 11.3 is displayed in your Web browser. It shows the Web Service name and the available operations for the Web Service. In this case, only the HelloWorld operation is available, which directly relates to the only method provided in the MyCPPWebService class.
){kind=link}
Notice the URL in the address bar. It points to the WebService.asmx file, which contains the information for the Web Service. The .asmx file is similar to the .aspx file of an ASP.NET application, except it is named differently to distinguish between Web Services and Web applications.
Figure 11.3 The Web browser interface for testing MyCPPWebService.
Click the HelloWorld hyperlink in the Web browser to show the next page in the Web browser, as shown in Figure 11.4. This Web page shows the actual SOAP that is used to communicate with the Web Service. It shows both the POST and the response when the HelloWorld operation is called.
){kind=link}
Figure 11.4 The Web browser interface for the HelloWorld operation showing SOAP used to execute the Web Service method.
The Invoke button on the Web page actually executes the HelloWorld operation and triggers the debug breakpoint that you set. Continuing with the Web Service reveals the XML results, as shown in Figure 11.5. Notice that the string returned is the same string returned from the C++ code in Listing 11.1. The .NET Framework takes care of all the mess dealing with XML to format the request from the client and the response from the Web Service.
){kind=link}
Figure 11.5 The Web browser showing XML output from invoking the HelloWorld method of the Web Service.
Changing the Web Service
Now that you've seen how a Web Service works, it is time to change it into a Web Service with a little more substance. Instead of a simple HelloWorld() method, the Web Service will have a new Web Service method to return the current system date and time in a formatted string. Additionally, another Web Service method will calculate the area of a rectangle and return the results.
Change the MyCPPWebService class definition to add the CurrentDateTime() and RectangleArea() methods, as shown in Listing 11.2.
Listing 11.2 WebService.h—MyCPPWebService Declaration with CurrentDateTime() and RectangleArea() Methods
1: #using <System.Web.Services.dll>
2:
3: using namespace System;
4: using namespace System::Web;
5: using namespace System::Web::Services;
6:
7: namespace WebService
8: {
9: public __gc class MyCPPWebService : public WebService
10: {
11:
12: public:
13: [System::Web::Services::WebMethod]
14: String __gc* HelloWorld();
15:
16: [System::Web::Services::WebMethod]
17: String __gc* CurrentDateTime();
18:
19: [System::Web::Services::WebMethod]
20: double RectangleArea( double dWidth, double dHeight );
21: };
22: }
The CurrentDateTime() declaration is similar to the HelloWorld() declaration in that it returns a String and doesn't take parameters. However, the RectangleArea() method is different in that it returns a Double and takes two Double parameter values. Each declaration has the System::Web::Services::WebMethod attribute in front of it to signify that the method is accessible via the Web Service. Any methods that do not have this attribute are not accessible.
Of course, these functions currently don't do anything because they haven't been defined. Open the WebService.cpp file. Add the two functions immediately following the HelloWorld function. To get the current date and time, you can use the .NET Framework structure System::DateTime. This structure defines a property named Now that returns the current date and time object whose member variables correspond to the exact time that function was called (that is, the current date and time at that moment). After that is done, you can simply convert it to a String object and return it. The Rectangle method is a little simpler—simply return the result of multiplying the two parameters. Your code should look similar to Listing 11.3.
Listing 11.3 Defining the Rectangle and CurrentDateTime Web Service Methods
1: #include "stdafx.h"
2: #include "WebService.h"
3: #include "Global.asax.h"
4:
5: namespace WebService
6: {
7: String __gc* MyCPPWebService::HelloWorld()
8: {
9: return S"Hello World!";
10: }
11:
12: String __gc* MyCPPWebService::CurrentDateTime(void)
13: {
14: return System::DateTime::get_Now().ToString();
15: }
16:
17: double MyCPPWebService::RectangleArea( double dWidth, double dHeight )
18: {
19: return dWidth*dHeight;
20: }
21: };
Looking at the SOAP generated to handle a Web Service method such as RectangleArea(), you would see the following:
POST /WebService/WebService.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://tempuri.org/RectangleArea" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <RectangleArea xmlns="http://tempuri.org/"> <dWidth>double</dWidth> <dHeight>double</dHeight> </RectangleArea> </soap:Body> </soap:Envelope> HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <RectangleAreaResponse xmlns="http://tempuri.org/"> <RectangleAreaResult>double</RectangleAreaResult> </RectangleAreaResponse> </soap:Body> </soap:Envelope>
As you can see, the block shown for the POST shows the two parameters, dWidth and dHeight, as Double. The result is shown in the HTTP block as RectangleAreaResult and is also Double.
When you run the Web service this time, you will see three methods you can invoke: the original HelloWorld() method and the CurrentDateTime() and RectangleArea() methods. Selecting the CurrentDateTime hyperlink shows the XML results, as displayed in Figure 11.6.
){kind=link}
Figure 11.6 The Web browser showing XML output from the CurrentDateTime() Web Service method.
When you select the RectangleArea hyperlink, the Web browser opens a form, shown in Figure 11.7, for you to enter values for the parameters required by the RectangleArea() method. When you click the Invoke button, the RectangleArea() method is called on the Web Service and the values are passed in as parameters. The result is calculated and returned in the same way as the other methods.
){kind=link}
Figure 11.7 The RectangleArea() parameter input form for testing.