Level: Introductory JJ Kuslich, Software Engineer, IBM
10 Jun 2005
Updated 10 Nov 2005 Web services and service-oriented architectures continue to move into the mainstream. With IBM Rational XDE Developer v2003 - .NET Edition and Microsoft Visual Studio .NET 2003 to support you, there really aren't any excuses left to avoid exploring Web services.
Editor's note
On June 5, 2006 IBM announced the withdrawal of the Rational Rose XDE product family listed below. The Rational XDE components are being withdrawn from the market; however, the Rational Rose components will continue to be supported and will be re-packaged into a new set of offerings.
For more comprehensive information on the product migrations with the IBM Rational June 2006 product release plans, please visit: http://www.ibm.com/software/rational/support/migrations/
You can not pick up a technical journal (or browse to one on the Web) these days without seeing at least one article on XML Web services. Service Oriented Architectures (SOA) are gaining popularity as corporations aim to integrate heterogeneous internal systems, as well as communicate effectively with business partners. Despite some of the hype behind Web services, there is little doubt that they have gained significant momentum in the past couple of years and are providing real value in the business world today.
IBM® Rational® XDE™ Developer v2003 - .NET Edition helps you build XML Web services. You can model, generate, and consume XML Web services with the XDE tools. XDE's tight integration with the Microsoft® Visual Studio® .NET 2003 integrated development environment (IDE) combines modeling and coding activities into a smooth and cohesive process.
In this article, I'll introduce you to the features in XDE related to XML Web services, and will help you start using them quickly and effectively through hands-on exercises. Note that although I'll focus on applying XDE Developer v2003 to software development within the .NET environment, a Java™ Platform Edition is also available.
To get the most out of this article, you should already be familiar with the basic concepts of the .NET framework and XML Web services, and know how to use Visual Studio .NET. You should also be familiar with the Unified Modeling Language (UML), and with the XDE modeling and code generation features. If you haven't used XDE before, you might want to take a look at my introductory article on an earlier version of the product. You can learn more about XDE and download an evaluation copy at the IBM® developerWorks® Web site.
Building a Web Service with XDE
The best way to show you the features of XDE that support building XML Web services will be to take you through some hands-on exercises. In this section I'll walk you through the step-by-step process for creating a simple XML Web service with XDE.
The example Web service that I'll show you how to build will provide a single method that will act as a lookup service for zip codes. That is, if the user provides a zip code, the Web service will return a city and state combination as a single string, such as "Seattle, WA."
To build this service, we'll proceed through four basic steps, covered in three hands-on exercises:
- Create an XDE Web service project
- Model the Web service structure with XDE and generate the source code
- Add business logic to the Web service using C#
- Build and test the Web service
Exercise 1: Create the XDE Web service project
The first step is to create a project to store and organize our Web service files. XDE and Visual Studio.NET are tightly integrated, making this step a snap. This exercise illustrates both steps 1 and 2 from the previous process outline, since these steps are closely related.
- Launch Visual Studio .NET 2003.
- Create an ASP.NET Web service project. You can use C# or Visual Basic .NET, but for this example we'll use C#.
- Name the service ZipLookerUpper. Alternatively, if you don't like my quirky, grammatically-challenged name, feel free to name the service something more straightforward such as ZipCodeService. Of course, I don't advocate silly names for real work projects. But don't say I didn't warn you if your service doesn't seem to be as much fun to use as mine.
These steps create an ASP.NET XML Web service project, but no XDE model has yet been built to represent it. Your screen should look similar to that shown in Figure 1.
Figure 1. Creating an ASP.NET Web service project
- With the project created, delete the default file named Service1.asmx that Visual Studio .NET generates for you. You could just rename it, but that approach can be slightly more error-prone than deleting the default file and adding a new file with the name that you want.
- In the Solution Explorer, right-click the project to add a new item. Add a new Web service file to the project and name it
ZipLookup.asmx as illustrated in Figure 2.
Figure 2. Adding a Web service file to the project
- In the Solution Explorer, right-click
ZipLookup.asmx and click View Code. Note that the namespace is called ZipLookerUpper (if that is how you named your project) and the Web service class is named ZipLookup.
- Right-click the ZipLookerUpper project in the Solution Explorer and click Synchronize. This generates an XDE model from your ASP.NET XML Web service project.
We've just created an XML Web service with an XDE model. The integration between XDE and Visual Studio .NET provides a smooth and straightforward process for creating and working with both the Web service code and the model. Let's examine the XDE model and take a closer look at some of the more significant elements.
Web Service Modeling in XDE
When an XML Web service is synchronized with XDE, it generates several model elements. Click the Model Explorer tab in Visual Studio .NET and expand the ZipLookerUpper namespace element. Your model should appear similar to that shown in Figure 3.
Figure 3. Model Explorer view of the synchronized Web service model
As with just about any XDE model of a .NET component or application, the referenced assemblies for the project are included, such as those in the System namespace of the .NET Framework. Underneath the ZipLookerUpper namespace, you will see a class representing the ZipLookup Web service created in Exercise 1. At this point it only has two inherited methods, Dispose and InitializeComponent, as well as a constructor. I'll show you how to add additional logic in the next exercise.
The model also shows a second element named ZipLookup with an icon that looks like a globe surrounded by 4 red corners. Click that shape in Model Explorer and look at the Stereotype property in the Properties window. This element is a class but it has a stereotype of NETWebService. This element also has an association with a stereotype of NETWebServiceProxy. The class with a stereotype of NETWebService represents the .asmx file. The unstereotyped class represents the code-behind file (for C#, it's a .cs file, and for VB.NET it's a .vb file). And the association with a stereotype of NETWebServiceProxy represents the relationship between the Web service and its code-behind file.
Exercise 2: Add Business Logic to the Web Service
At this point, the Web service doesn't actually do anything yet. We haven't created and exposed any methods that can be called to perform an operation, such as our zip code lookup. Adding business logic to a Web service is much like adding methods to a class in any other application, with one important addition: exposing an operation through the Web service interface. I'll demonstrate the configuration step in this exercise.
The ZipLookup Web service needs to provide a method that the client application can call to return a city/state combination when passed a zip code. To implement this, we'll create a simple method called Lookup that takes a single string parameter (the zip code) and returns a single string parameter (the city/state combination). While we could add this method by writing the code in the .asmx file and synchronizing with the model again, I will instead show you how you can model the method as an operation in XDE and then generate the corresponding C# code from the model.
- In Model Explorer, right-click the ZipLookup class. Make sure to select the unstereotyped class representing the code-behind logic, not the class with a stereotype of NETWebService, which represents the
.asmx file.
- Click Add UML > Operation.
- Name the operation LookupCityState.
- Right-click the LookupCityState operation, then click Add UML > Parameter.
- Name the parameter ZipCode to represent the input parameter that the caller will pass.
- In the Properties pane, set the Type Expression property to
String.
- To add the return value for the operation, right-click the LookupCityState operation, click Add UML > Parameter. Name the return value String. XDE will replace the name with the return type of the return value in the next step, since return values are not named. The name you type here is inconsequential.
- In the Properties pane, set the Kind property to
RETURN and set the TypeExpression property to String. Note that in Model Explorer, as illustrated in Figure 4, the parameter representing the return value has changed to indicate that it is a return value, not an input parameter, and returns a value of type String.
Figure 4. Return value of type String, as it appears in Model Explorer
- Click the ZipLookerUpper namespace, and then click the Synchronize button.
At this point, I've modeled the operation much as I would the operation for any class in any type of project. Listing 1 shows a snippet of code for the new operation.
Listing 1. Generated code for the LookupCityState operation
public String LookupCityState(String ZipCode)
{
return null;
}
|
However, in .NET, we need to do some extra work to make sure that our method is exposed through the Web service and can be called by external applications. The simplest way to do this in .NET is to add the WebMethod attribute to the operation. You can do this in the code-behind class of the .asmx file in the code editor, or you can add this attribute right to the XDE model, as I'll illustrate in the next step.
- In the Model Explorer, click the LookupCityState operation.
- In the Properties pane, type WebMethod in the LanguageAttributes Property text box.
- Click the ZipLookerUpper namespace again and then click the Synchronize button.
As shown in Listing 2, XDE generated the given attribute on the LookupCityState operation.
Listing 2. LookupCityState operation marked with the [WebMethod] attribute
[System.Web.Services.WebMethod]
public String LookupCityState(String ZipCode)
{
return null;
}
|
The final step in this exercise is to add the business logic to the LookupCityState operation. Add the code shown in Listing 3 to the method. Because the purpose of the example is to display the features of XDE, I've kept the code extremely simple. In real code we'd need to account for issues such as error handling, and we would most likely connect to a data source to perform the lookups.
Listing 3. Business logic for the LookupCityState method
[System.Web.Services.WebMethod]
public String LookupCityState(String ZipCode)
{
string result = string.Empty;
switch(ZipCode)
{
case "98188":
result = "Tukwila, WA";
break;
case "85023":
result = "Phoenix, AZ";
break;
}
return result;
}
|
Exercise 3. Build and test the Web service
The last step in constructing the Web service is to compile it and then put it through its paces. XDE made the process of modeling the Web service simple and straightforward; similarly, Visual Studio .NET makes the process of building and testing the Web service just as easy.
- In Visual Studio .NET, right-click the
ZipLookup.asmx file and click Set as Start Page. This tells Visual Studio .NET to go to this page in the browser when launching the Web service from within Visual Studio .NET.
- Open the Build menu and click Build Solution. Visual Studio .NET compiles the code that you wrote in earlier exercises.
- Open the Debug menu and click Start Without Debugging.
Launching the Web service in this way brings up a service help page (like the one depicted in Figure 5) that is automatically generated for you when you access an .asmx page from a Web browser without specifying a query string in the URL. The service help page provides information about the structure of the Web service, including the available operations. If you click on the Service Description link at the top, a description of the service in the Web Services Description Language (WSDL) is returned.
Figure 5. Auto-generated helper page for the ZipLookup Web service
The page contains a link at the top with the same name as the method we wrote earlier, LookupCityState. Clicking this link will return a page that allows you to invoke the operation on the Web service as indicated in the following steps:
- Click the link labeled LookupCityState. This returns a page showing the input parameters, as well as a text box for entering values. In this case there is only one input parameter, ZipCode.
- Type
98188 in the text box.
- Click the Invoke button.
This should return the XML code shown in Listing 4.
Listing 4. XML result from the invocation of the LookupCityState Web service operation
<?xml version="1.0" encoding="utf-8" ?>
<string xmlns="http://tempuri.org/">Tukwila, WA</string>
|
Consuming an XML Web Service
In this article, I won't go into the details of consuming the XML Web service we've built, because it doesn't involve XDE very much. Instead, I will give you the basic outline for consuming the service created above, and show you one interesting aspect of XDE related to consuming Web services. If you'd like to try it yourself, I encourage you to write a simple client application in Visual Studio .NET and give it a go. You can also look at the sample code I've provided that implements a simple client for the ZipLookup Web service.
The process for consuming a Web service is as follows:
- Create a client application
- In the client application, add a Web Reference to the Web service from Visual Studio .NET
- Write code in your client to call the method
- Synchronize the model and code
Once you synchronize the model and code, you will notice in the Model Explorer that the model for the client application reflects the Web reference as shown in figure 6. The highlighted ZipLookup class indicates the Web reference, and you can see in the Properties pane below that the stereotype is WebServicReference.
Figure 6. XML Web service reference modeled in XDE
Summary
Web services and service-oriented architectures continue to move into the mainstream. With XDE Developer v2003 - .NET Edition and Visual Studio .NET 2003 to support you, there really aren't any excuses left to avoid exploring Web services. Just as for other types of applications, XDE provides powerful yet easy-to-use modeling tools and straightforward code synchronization features to enable you to quickly model and generate .NET XML Web services. In addition, with XDE's tight integration with Visual Studio .NET 2003, you can take advantage of the convenient, time-saving Web services support built into Visual Studio .NET and ASP.NET.
Resources
About the author  | | | JJ Kuslich is a software engineer who designs and builds data-driven business applications. Over the years he has also worked as a software architect and project manager, and has written many articles along the way. He currently works in the Pacific Northwest and lives just 15 minutes from a dozen hiking trails that do his body (and mind) good. |
Rate this page
| 
