It’s nearly impossible to pick up a software-related journal
these days that doesn’t contain some mention of XML Web Services. This makes it
easy to think of Web Services as pure hype, but in reality they may shape the
next generation of software applications. XML Web Services are the other half
of ASP.NET (the first half is Web Forms). This chapter helps you understand
what XML Web Services are, and how you can use them in your .NET applications.
According to Microsoft’s initial marketing push for
.NET, XML Web Services are the cornerstone of .NET and the reason for its very
existence. In reality, you may use .NET to create both Windows Forms and Web
Forms applications without ever creating an XML Web Service. However, there are
good reasons why you should consider doing so.
There’s been a lot of interest in the FoxPro community over
the fact that Visual FoxPro can both create and consume XML Web Services. In
fact, VFP’s Web Service capabilities are what places it under the “.NET
umbrella”. Although it’s not a .NET language, Visual FoxPro allows you to
create XML Web Services that can be consumed by .NET and it can consume XML Web
Services created in .NET.
What is a Web Service?
A Web Service is a code module containing one or more
functions accessible via the
Internet. Desktop applications, Web applications, or even another Web Service can access Web Services. When you access a Web Service, you are making a function or method call over the Internet.
Internet. Desktop applications, Web applications, or even another Web Service can access Web Services. When you access a Web Service, you are making a function or method call over the Internet.
Web Services are:
·
Language independent – They can be written in
virtually any computer language and accessed by code written in any language
·
Platform independent – They can run on any
operating system and be accessed by client code running on any platform.
·
Self-describing – Each Web Service has
associated files that describe the services it provides and allows clients to
call its methods.
Although most of the software you run is physically located
on your own computer, running code on a computer that resides somewhere across
the Internet is actually a common occurrence—it happens all the time as you
surf the Web, although surfing the Web is not the same as accessing a Web
Service. So, first you’ll look at what happens when you surf the Internet, and
then see how Web Services takes this approach a step further.
As you navigate to different sites with your browser, you
request Web pages located on Web servers across the Internet. Behind the
scenes, especially when accessing Web pages with dynamic content, a Web server
runs code in response to your request and sends HTML, script code, and so on,
back to your computer. In this manner, you’re indirectly running code that
resides on a Web server.
When using technologies such as ASP or ASP.NET pages, the
code that’s being executed is often stored in methods of business components
located on the Web server. For example, in Chapter 10, “Building Web
Applications with ASP.NET”, you created a Web Forms application that allowed
users to view and edit orders for a specified customer. As shown in Figure 1,
when the user enters a Customer ID and clicks the Submit button, the Web server
instantiates the Orders business object and calls its GetOrdersByCustomerID method.
The Web Server produces an HTML list of customer orders to send back to your
browser.
Figure 1. When you access ASP or ASP.NET pages,
you are often indirectly causing code to be executed on a Web server.
For the most part, this approach works well. However, XML Web
Services let you take this paradigm a step further, giving you greater control.
They effectively allow you to call the GetOrdersByCustomerID method of the
Orders business object directly. Just think about how useful this is. If you are
able to call the method directly, you can retrieve a list of customer orders as
an XML string and manipulate it in your own software applications, and even
persist it to a local data store. Later in this chapter, you’re going to build
a Web Service allowing you to do just that.
This type of Web Service is private by nature, established
between business partners. You may have certain clients that you allow to
access the Web Service, but you certainly don’t want to provide free access to
the rest of the world. In contrast, there are other types of Web Services that
are intended for public consumption. For example, Fed-Ex™ has a public Web
Service letting you track packages. You simply pass your tracking number to the
Web Service and it returns a string containing tracking information.
At this point, you will build an ASP.NET XML Web Service and
explore the technologies behind Web Services along the way.
Creating a Customer Orders Web Service
To create a .NET XML Web Service:
1. Launch
Visual Studio .NET, and click the New
Project button on the Start
Page.
2. In
the left pane of the New Project
dialog (Figure 2), select Visual
C# Projects or Visual
Basic Projects, depending on the language you want to use. In the
Templates pane on the
right, select ASP.NET Web
Service.
3. Notice
the Name text box is
disabled and contains the text “WebService1”, and
if you’re creating the Web Service on your local machine, the Location text box contains the text “http://localhost/WebService1”. To change the name of the Web Service, you must change the name of the directory in the Location text box.
Change the name “WebService1” to “Customer Orders Web Service, and then click the OK button.
if you’re creating the Web Service on your local machine, the Location text box contains the text “http://localhost/WebService1”. To change the name of the Web Service, you must change the name of the directory in the Location text box.
Change the name “WebService1” to “Customer Orders Web Service, and then click the OK button.
Figure 2. You can choose to create a C# or Visual
Basic ASP.NET Web Service in the New Project dialog.
At this point, Visual Studio .NET briefly displays the Creating the Web dialog
while it creates a new ASP.NET Web Service from the template you have selected.
After a few moments, a new Web Service file is displayed in the IDE (Figure
3).
Figure 3. VS .NET automatically creates a Web
Service file when you create a new ASP.NET Web Service.
Rename this Web Service file so it’s a little more
descriptive. To do this, with the Web Service file selected in design mode, go
to the Properties Window and change the Name
property from “Service1” to “CustomerOrders” (Figure 4).
Figure 4. You change the name of the Web Service
in the Visual Studio .NET Properties Window.
You’ll take a closer look at this file soon, but you need to
do a little housekeeping first.
Renaming the project namespace
When you create a new Web Service, ASP.NET
automatically sets your project’s namespace to the same name as your project
(as it also does when building Windows Forms and Web Forms applications). To
change the default namespace in VB .NET, you must first close the
CustomerOrders page (you don’t need to do this in a C# project). Next, go to
the Solution Explorer and right-click on the project (the second node from the
top). From the shortcut menu, select Properties,
which launches the Property
Pages dialog. In the left pane of the dialog, under the Common Properties folder,
select General if it’s
not already selected.
If you’re using C#, in the right pane, change the Default Namespace from
“Customer_Orders_Web_Service” to “HW.NetBook.Samples”. If you’re using Visual
Basic .NET, in the right pane, change the Root
namespace to “HW.NetBook.Samples”. When you’re done, click the OK button to save
changes.
To change all existing references to the original namespace,
from the main menu select Edit |
Find and Replace | Replace in Files. In the Replace In Files dialog’s
Find what text box, enter
“Customer_Orders_Web_Service”. In the Replace
with text box, enter “HW.NetBook.Samples”, (make sure you enter
this with the exact case shown here). Click the Replace
All button. This launches a warning dialog—simply press OK to ignore the warning.
When the find and replace is finished, it displays a dialog indicating how many
occurrences were replaced. If you’re using C#, it should say “4 occurrence(s)
replaced”. If you’re using Visual Basic .NET, it should say “2 occurrence(s)
replaced”. Click the OK
button to close these dialogs.
Web Service virtual directories
When you use Visual Studio .NET to create a Web
Service, it automatically creates a virtual directory for you.
For more information on virtual directories, see Chapter 10,
“Building Web Applications with ASP.NET”.
This virtual directory contains your new Web Service project
and related files (Figure 5). However, as with Web Forms applications,
the actual Solution file is stored in a subfolder of the “My Documents\Visual
Studio Projects\” directory. Again, this means when you reopen your Web
Application after restarting Visual Studio, you will find your solution in this
folder.
Figure 5. Visual Studio .NET places a variety of
files in your Web Service’s virtual directory.
Before taking a closer look at these files first take a
behind-the-scenes look at the Web Service file.
A closer look at the Web Service file
You can view a Web Service file in either design view
or code view. To switch to code view, you select the click
here to switch to code view hyperlink on the page or
right-click the file and select View
Code from the shortcut menu. When you do this, you should see the
following class definition in C#:
public class CustomerOrders:
System.Web.Services.WebService
{
public CustomerOrders ()
{
//CODEGEN: This call
is required by the ASP.NET Web Services Designer
InitializeComponent();
}
// WEB SERVICE EXAMPLE
// The HelloWorld()
example service returns the string Hello World
// To build, uncomment the
following lines then save and build the project
// To test this web
service, press F5
// [WebMethod]
// public string
HelloWorld()
// {
// return
"Hello World";
// }
}
And in Visual Basic .NET:
Public Class CustomerOrders
Inherits
System.Web.Services.WebService
' WEB SERVICE EXAMPLE
' The HelloWorld()
example service returns the string Hello World.
' To build, uncomment
the following lines then save and build the project.
' To test this web
service, ensure that the .asmx file is the start page
' and press F5.
'
'<WebMethod()>
Public Function HelloWorld() As String
' HelloWorld = "Hello World"
' End Function
End Class
As you can see, this code defines a class named
CustomerOrders derived from the .NET Framework’s System.Web.Services.WebService
class. Also notice the method that is commented out at the bottom of the class
definition. As described in the comments above it, you can uncomment this code
and then build and run this sample Web Service, which you will do in the next
section
Running the “Hello World” Web Service
To run the sample “Hello World” Web Service, select all
of the commented code in the HelloWorld method (including the WebMethod
attribute), and then click VS .NET’s Uncomment icon button (Figure 6).
Alternately, to uncomment code, you can select Edit
| Advanced | Uncomment Selection from the main menu.
Figure 6.You can use the “Uncomment” button to
uncomment selected lines of code.
To save, build, and run the Web Service in one step, just
press the F5 button. After a few moments, a Web Service help page displays in
your Web browser. This page lists all of your Web Service methods and gives you
a link to Service method help pages that allow you to test your Web Service
methods (very cool!).
What’s nice about this is the page is generated and displayed
for any user who tries to call your Web Service without the proper parameters.
You can try this for yourself by typing the URL of your Web Service into your
browser’s Address box. For
example:
http://localhost/Customer Orders Web Service/Service1.asmx
The upper portion of the Web Service help page (Figure 7)
displays the name of your Web Service (CustomerOrders), and a single HelloWorld
operation—this is the method that you just uncommented. It also displays a
warning about changing the default namespace of your Web service—you’ll do this
a bit later.
Figure 7. Visual Studio .NET creates a Web
Service help page customized to your Web Service.
To test the Web Service, click the HelloWorld
hyperlink. This displays the Service method help page (Figure 8), which
includes a description of the operation and an Invoke
button that allows you to test the Web Service.
Figure 8. The Service method help page displays a
description of the operation and an Invoke button that allows you to call the
Web Service method.
At this point, click the Invoke
button. Behind the scenes, the Service method help page calls the HelloWorld
test method and displays the return value in a new browser window (Figure 9).
Figure 9. The Service method help page launches
another browser window that displays the return value passed back from the Web
Service method.
As you can see, although the code in the HelloWorld method
returns a simple string, it is converted into XML when it returns to the Web
Service caller. At this point, close the Browser window, so you can work
further with the Web Service project.
Web Service project files
Now that you’ve created a simple .NET Web Service, take
a quick look at the files within a Web Service project.
The global.asax file automatically added to your Web Service
project by Visual Studio .NET is exactly the same as the global.asax file that
it includes in new Web Forms projects. The same is also true of the Web.config
file. If you create a new Web Service project and compare these files to a new
Web Forms project, you’ll find no differences. For more information on these
files, see Chapter 10, “Building Web Applications with ASP.NET”.
The vsdisco file
There is one file you’ll find in Visual Studio .NET Web
Service projects you won’t find in a Web Forms application—the vsdisco file.
This file is a Web Services discovery file used by Visual Studio .NET as it
searches through folders on your development Web server looking for available
XML Web Services.
If you look in the Solution Explorer, you will see a file
named “Customer Orders Web Service.vsdisco”. If you double-click this file, VS
.NET opens it in the IDE. By default, it contains the following XML data:
<?xml versio_="1.0"
encodi_g="utf-8" ?>
<dynamicDiscovery
xmlns="urn:schemas-dynamicdiscovery:disco.2000-03-17">
<exclude pa_u104
?="_vti_cnf" />
<exclude
pa_h="_vti_pvt" />
<exclude pa_u104
?="_vti_log" />
<exclude pa_u104
?="_vti_Ucript" />
<exclude pa_h="_vti_txt" />
<exclude pa_u104 ?="Web References" />
</dynamicDiscovery>
As you can see, the file contains a <dynamicDiscovery>
root node with several <exclude> child nodes. The <exclude> nodes
contain a relative path to folders VS .NET should not search when it’s
going through the directories on your Web server looking for Web Services.
For more information, see the .NET Help topic “Deploying XML
Web Services in Managed Code”.
Using business objects
Now it’s time to reference and use the business objects
you created in Chapter 9, “Building .NET Windows Forms Applications”. Again,
there are a number of ways to accomplish
this, but the easiest method is adding the business object source code files to the Web
Service project.
this, but the easiest method is adding the business object source code files to the Web
Service project.
To add these source code files, right-click on your Web
Service project in the Solution Explorer and select Add
| Add Existing Item from the shortcut menu. In the Add Existing Item dialog,
navigate to the “Simple Windows Application” directory you created in the
previous chapter, and select the three business object source code files (Figure
10). These are Business.cs, Data.cs, and OrdersBusiness.cs. If you created
a Visual Basic .NET Windows Forms application, these files will have a “vb”
extension rather than a “cs” extension. After selecting all three files, click
the Open button.
Figure 10. You can add files belonging to one
.NET project to any other .NET project
After clicking the Open
button, the three files should be listed in the Solution Explorer.
Typically, with business objects that are going to be used from
multiple projects, you should create a separate Class Library project in Visual
Studio .NET and add your business object source code files to this project. You
can then compile a DLL containing just your business object classes. This DLL
can then be referenced from multiple projects
Creating custom Web methods
Now, you’re ready to add to the WebService file a
custom Web method that instantiates and calls a method of the Orders business
object. First, go back to the code-behind file (Service1.asmx.cs or
Service1.asmx.vb), and comment out the HelloWorld method you previously
uncommented. Make sure you also comment out the line containing “[WebMethod]”.
For more information on this attribute, see the section “The WebMethod attribute” later in this
chapter.
Next, add the following namespace reference to the top of the
code-behind file so you can access the Orders business object class.
In C#:
using HW.NetBook.Samples.Business;
In Visual Basic .NET:
Imports HW.NetBook.Samples.Business
Now, add the following method to the bottom of the
CustomerOrders WebService class definition—make sure it’s directly below the commented
out Hello World Web Method.
In C#:
[WebMethod (Description="Returns orders for the
specified customer")]
public DataSet GetOrdersByCustomerID(string custID)
{
// Instantiate the Orders
business object
Orders OrderObj = new
Orders();
// Call its
GetOrdersByCustomerID method
return
OrderObj.GetOrdersByCustomerID(custID);
}
In Visual Basic .NET:
<WebMethod(Description:="Returns orders for the
specified customer")> _
Public Function GetOrdersByCustomerID(ByVal custID As String) As
DataSet
' Instantiate the
Orders business object
Dim OrderObj As New
Orders()
' Call its
GetOrdersByCustomerID method
Return
OrderObj.GetOrdersByCustomerID(custID)
End Function 'GetOrdersByCustomerID
This Web method instantiates the Orders business object and
calls its GetOrdersByCustomerID method, passing the custID value it receives
from the client calling the Web Service. Notice the method specifies a DataSet
as the return value. Even though the return value is specified to be a DataSet,
if you call the Web Service, you actually get the DataSet returned in XML
format.
Unfortunately, Visual FoxPro 7 cannot work with the XML
returned from a Web Service in this fashion (this should be fixed in
Visual FoxPro 8). If you want to create a Web Service that a Visual FoxPro 7
client can consume, you explicitly convert the DataSet to XML and return the
XML string from the Web Service method as shown in the following code (for this
example, I leave the GetOrdersByCustomerID method returning a DataSet as shown
above).
In C#:
[WebMethod (Description="Returns orders for the
specified customer")]
public string GetOrdersByCustomerID(string custID)
{
// Instantiate the Orders
business object
Orders OrderObj = new
Orders();
// Call its
GetOrdersByCustomerID method
DataSet dsOrders =
OrderObj.GetOrdersByCustomerID(custID);
return dsOrders.GetXml();
}
And in Visual Basic .NET
<WebMethod(Description:="Returns orders for the
specified customer")> _
Public Function GetOrdersByCustomerID(ByVal custID As String) As
String
' Instantiate the
Orders business object
Dim OrderObj As New
Orders()
' Call its
GetOrdersByCustomerID method
Dim dsOrders As DataSet
= OrderObj.GetOrdersByCustomerID(custID)
Return
dsOrders.GetXml()
End Function
Before taking a closer look at what happens behind the scenes
with the Web Service, first look at the WebMethod and WebService attributes.
The WebMethod attribute
If you place a WebMethod attribute directly above a
method declaration, the method is exposed by Visual Studio .NET as a public
method of the XML Web Service. A WebService class can have multiple methods,
but only those that possess the WebMethod attribute are exposed as part of the
Web Service.
As you can see in the new method you created, the WebMethod
attribute also allows you to specify a method description. Table 1 lists
other properties of the WebMethod attribute that you can also set.
Table 1. WebMethod
properties
Property
|
Description
|
Default
|
BufferResponse
|
Specifies if ASP.NET should
buffer the entire response before sending it to the client.
|
true
|
CacheDuration
|
Specifies if the result set
of each unique parameter set should be cached, and if so, for how many
seconds.
|
0
|
Description
|
Gives a description for the
Web Service method.
|
“”
|
EnableSession
|
Specifies if session state is
enabled for a Web Service method.
|
false
|
MessageName
|
Specifies an alias for an
overloaded method name.
|
“”
|
TransactionOption
|
Specifies transaction options
for a Web Service method. Possible values are:
·
Disabled
·
Not Supported
·
Supported
·
Required
·
RequiresNew
|
Disabled
|
For more information on each of these properties, see the
.NET Help topic “Using the WebMethod Attribute”.
The WebService attribute
As shown in Figure 7 earlier in this chapter, when you
run the HelloWorld Web Service, the Web Service test page displays a warning
about changing the name of the Web Service’s namespace from
“http://tempuri.org/” to your own, unique namespace. To do this, you need the
WebService attribute.
The WebService attribute is applied to a Web Service by
placing it directly above the Web Service class definition. For example, place
the following attribute definition above the CustomerOrders WebService class
definition.
In C#:
[WebService(Namespace="http://servername/xmlwebservices/",
Description="Customer Orders Web
Service")]
In Visual Basic .NET:
<WebService(Namespace:="http://servername/xmlwebservices/",
_
Description:="Customer Orders Web
Service")> _
The first part of the WebService attribute declaration
specifies the Namespace property. Specifying this value replaces the Web
Service’s default “http://tempuri.org/” namespace. When creating a Web Service,
you can specify your own unique URL by using the Namespace property. As shown
in the second line of the declaration, you can also specify a Description
property, which provides a description for the entire Web Service class.
Running the Customer Orders Web Service
Now you’re ready to run the Customer Orders Web
Service. To do this, press the F5 key to save all changes, compile the Web
Service application, and run it. When your browser is launched, you should see
the Web Service help Page shown in Figure 11.
Figure 11. The WebService and WebMethod
attributes allow you to specify descriptions (and other properties) for your
Web Service and its methods.
Notice the top of the page displays the name of the Web
Service class, “CustomerOrders”. Beneath the name is the description you
supplied in the WebService attribute. At the bottom of the page is the
GetOrdersByCustomerID along with the description you supplied in the WebMethod
attribute.
If you click on the GetOrdersByCustomerID
link, the Service method help page is displayed (Figure 12).
Figure 12. The Service method help page displays
a user input control for each parameter of your Web Service method.
As you can see, the Service Method help page displays an
input text box for each parameter of a Web Service method. In this case, you
just have one—custID. Enter the value “QUICK” in the custID text box, and then
click the Invoke button. A
new browser window displays the XML returned from the method (Figure 13).
Figure 13. The Service method help page launches
a second browser window that contains the XML returned from the CustomerOrders
Web Service.
The Web Services Description Language (WSDL) file
Now that you’ve created and tested a Web Service, you
can take a closer look behind the scenes at some of the standards that make XML
Web Services possible. I’ll start with the Web Services Description Language
(WSDL) file.
A Web Service’s WSDL file (pronounced “wis-dle”) is roughly
equivalent to a COM server’s type library. Remember, a type library describes
the classes and methods publicly available in a COM server. In the same way, a WSDL file (also known as a
service description document) describes the public classes and methods
available in a Web Service.
Type libraries work great for COM servers, but they are
Microsoft-specific—and Web Services are not. So, when the W3C committee chose a
format to describe Web Services, they chose XML—a widely accepted,
platform-neutral, extensible standard. WSDL defines an XML grammar for
describing Web Services.
If you want to view your Web Service’s WSDL file, you do so
from the Web Service help page (Figure 11). If you click the Service Description link,
it launches a browser window that displays your Web Service’s WSDL file (Figure
14).
Figure 14. Visual Studio .NET automatically
generates a WSDL file for your Web Services.
As shown in Figure 14, the WSDL file contains information on
each public method, along with the method’s parameters and return value (not
shown in the figure). By default, when you create a Web Service in Visual
Studio .NET, your WSDL file is dynamically generated. You can also create a
WSDL file, place it on your Web server, and make its location known to your
customers (or the general public) so they can download the file and determine
how to access your Web Service.
A full explanation of the structure and contents of a WSDL
file is beyond the scope of this book. For more information, see the .NET Help
topic “XML Web Service Description”, which also contains a link to the WSDL
specification (http://www.w3.org/TR/wsdl).
SOAP
Another XML-based standard key to Web Services is
Simple Object Access Protocol (SOAP). SOAP is a protocol for exchanging
structured and type information on the Web.
You can actually view some of the SOAP formatting for your
Web Service from the Service Method Help Page. For example, here is the SOAP
request and response shown on the GetOrdersByCustomerID Service Method Help
Page.
Here is the SOAP request:
POST /Customer%20Orders%20Web%20Service/Service1.asmx
HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"http://servername/xmlwebservices/GetOrdersByCustomerID"
<?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>
<GetOrdersByCustomerID
xmlns="http://servername/xmlwebservices/">
<custID>string</custID>
</GetOrdersByCustomerID>
</soap:Body>
</soap:Envelope>
And here is the SOAP response:
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>
<GetOrdersByCustomerIDResponse
xmlns="http://servername/xmlwebservices/">
<GetOrdersByCustomerIDResult>
<xsd:schema>schema</xsd:schema>xml</GetOrdersByCustomerIDResult>
</GetOrdersByCustomerIDResponse>
</soap:Body>
</soap:Envelope>
For more information on the SOAP standard, check out the .NET
Help topic “XML Web Service Wire Formats”, which contains a link to the W3C Web
site (http://www.w3.org/soap).
Consuming Web Services
As mentioned earlier in this chapter, desktop
applications, Web applications, or other Web Services can consume Web
Services. In this section, you will
create a desktop application that accesses the Customer Orders Web Service.
The ability to access a Customer Orders Web Service from a
desktop application can be extremely useful. For example, if you have placed orders
with one of your suppliers, it would be great to call a Web Service on your
supplier’s Web site that allowed you to retrieve all of your orders and display
them within one of your own desktop applications. This is good for your
supplier, because they don’t have to pay a humanoid to research the information
and send it to you. It’s also good for you, because not only can you display
this information in your own custom application, you can now manipulate and
store the information in your own database.
Before going any further, close your Web Service application.
Next, to create a new Windows Application, from the Start
Page of VS .NET, click the New
Project button. In the left pane of the New Project dialog,
select either Visual C#
Projects or Visual Basic
Projects. In the Templates
pane on the right, select Windows
Application. In the Name
text box, enter “WinForms Web Service Consumer”, and specify the desired
location for your new project in the Location
text box (Figure 15). When you’re done, click the OK button to create your
new Windows application.
Figure 15. You can consume a Web Service from a
Windows application (shown here), a Web Forms application, or another Web
Service.
When Visual Studio .NET finishes creating your new project,
you see a new form named “Form1” in the IDE. You will use this form to display
the user interface controls and call the Web Service. This is different than
what you did in Chapter 9, “Building .NET Windows Forms Applications”, because
in this case, you just need a bare bones application to call your Web Service.
First, you need to make a few changes to the form. With the form selected in
the IDE, go to the Properties Window, change the Name
property to “WebServiceConsumerForm”, the Size
property to 640, 260, and the Text
property to “Web Service Consumer”.
Now you need to perform one additional step, which is
different depending on whether you’re using C# or Visual Basic .NET. In C#,
right-click on the form and select View
Code from the shortcut menu. At the bottom of the code-behind
file, find the line of code that calls Application.Run:
Application.Run(new Form1());
And change it to:
Application.Run(new WebServiceConsumerForm());
In Visual Basic .NET, go to the Solution Explorer,
right-click the project node (second from the top), and select Properties from the
shortcut menu. This launches the Property
Pages dialog. In the left pane, under the Common Properties node,
select General. In the
right pane, change the Startup
Object to “WebServiceConsumerForm”, and then click OK to save the change.
Now select Form1 in design mode and drag and drop a DataGrid
control from the VS .NET Toolbox onto
the form. If the Toolbox
is not visible in the IDE, select View
| Toolbox from the main menu. Change the DataGrid properties to the
values shown in Table 2.
Table 2. DataGrid properties
Property
|
Value
|
Name
|
grdOrders
|
Location
|
40, 30
|
Size
|
550, 140
|
Next, drag a Button from the VS .NET Toolbox to the form and
set its properties to the values shown in Table 3.
Table 3. Button properties
Property
|
Value
|
Name
|
btnCallWS
|
Location
|
345, 195
|
Size
|
100, 23
|
Text
|
Call Web Service
|
Next, drag and drop a TextBox from the Toolbox onto the form and
sets its properties to the values shown in Table 4.
Table 4. Text Box properties
Property
|
Value
|
Name
|
txtCustomerID
|
Location
|
185, 195
|
Size
|
135, 20
|
Text
|
(empty string)
|
When you’re done, your form should look like the form shown
in Figure 16.
Figure 16. This Windows form is used to access
the Customer Orders Web Service.
Adding a reference to the Web Service
Now it’s time to add a reference to the Customer Orders
Web Service to your project. To do this, go to Solution Explorer, right-click
the References node,
and select Add Web Reference
from the shortcut menu (Figure 17).
Figure 17. You can add a reference to a Web
Service to your project by right-clicking References in the Solution Explorer and
selecting Add Web
Reference from the shortcut menu.
Selecting this option launches the Add
Web Reference dialog. The left pane of the dialog displays
information about the UDDI Directory. You’ll look at this later, but for now,
you just want to reference the local Customer Orders Web Service.
The Address
combo box at the top of the dialog allows you to select a previously used Web
Service or enter a URL and file name for the Web Service you want to reference.
In this case, you want to enter a reference to your Web Service’s .asmx file:
When you enter this URL and press enter, it shows the
familiar Web Service help page displaying a description of the Web Service and
its operations (Figure 18). In the right pane, there are View Contract and View Documentation
hyperlinks. If you click the View
Contract link, it displays the WSDL file in the dialog’s left
pane. If you click the View
Documentation link, it displays any extra documentation you
created for your Web Service.
Figure 18. The Add Web Reference dialog allows
you to search for Web Services you can reference in your .NET projects.
To add a reference to the Customer Orders Web Service to your
project, click the Add Reference
button. If you look in the Solution Explorer, you can see this
adds a new localhost node
containing three new files (Figure 19). Visual Studio.NET uses the name
of this node as part of the namespace for the Web Service so, rename it to
something more informative. To do this, right-click on the localhost node, select Rename from the shortcut
menu, and then rename the node from “localhost” to “CustomerOrdersWebService”.
Figure 19. Adding a Web Reference to your project
adds three new files to your project.
Now, take a closer look at the files added to the project. In
order to see all of the file detail, click the Show All Files button at the top
of the Solution Explorer (Figure 20).
Figure 20. Click the Show All Files button to
display all file detail in your project.
Expand the CustomerOrdersWebService
node, and you’ll see three files. Reference.map is an XML file that maps URLs
to local cached copies of the Service1.disco and Service1.wsdl files.
Service1.disco is a Web Service discovery file. For more information on .disco
files, see the “Web Services Discovery” section later in this chapter.
Service1.wsdl is a local copy of the Customer Orders Web Service WSDL file.
If you expand the Reference.map node, you’ll see a file named
Reference.cs (or Reference.vb). Open this file by double-clicking it and you’ll
see the definition of a class named CustomerOrders based on the .NET
Framework’s SoapHttpClientProtocol class.
In C# (shown partially):
public class CustomerOrders :
System.Web.Services.Protocols.SoapHttpClientProtocol
{
...
}
And in Visual Basic .NET (shown partially):
Public Class CustomerOrders
Inherits
System.Web.Services.Protocols.SoapHttpClientProtocol
...
End Class
This is a proxy class you can use to call methods on the
Customer Orders Web Service. When you call a Web Service method, you don’t
actually call the method on a Web Service’s object directly. Rather, you
instantiate a local proxy class (based on the .NET Framework’s
SoapHttpClientProtocol class) that passes the call on to the Web Service (Figure
21).
Figure 21. When you add a Web Service reference
to your project, VS .NET automatically creates a local proxy class that you can
use to indirectly call methods of the Web Service.
Calling the Web Service
Now you’re ready to add code to the form to call the
Web Service. To do this, select the Form1.cs
[Design] tab (or Form1.vb), and double-click the Call Web Service button.
This adds a new btnCallWS_Click event handler method to the form.
Before adding code to this method, go to the top of the form
and add a reference to the CustomerOrders proxy class’ namespace.
In C#:
using
WinForms_Web_Service_Consumer.CustomerOrdersWebService;
And in Visual Basic .NET:
Imports
WinForms_Web_Service_Consumer.CustomerOrdersWebService
Now, go back to the bottom of the code-behind file and add
code to the btnCallWS_Click event handler method.
In C#:
private void
btnCallWS_Click(object sender, System.EventArgs e)
{
// Instantiate the Web Service proxy class
CustomerOrders CustomerOrdersWS = new CustomerOrders();
// Call the Web Service and store the returned DataSet into
dsOrders
DataSet dsOrders =
CustomerOrdersWS.GetOrdersByCustomerID(this.txtCustomerID.Text);
// Bind the DataSet to the Orders DataGrid
this.grdOrders.SetDataBinding(dsOrders,
dsOrders.Tables[0].TableName);
}
And in Visual Basic .NET:
Private Sub btnCallWS_Click(ByVal sender As
System.Object, _
ByVal e As
System.EventArgs) Handles btnCallWS.Click
' Instantiate the Web
Service proxy class
Dim CustomerOrdersWS As
New CustomerOrders()
' Call the Web Service
and store the returned DataSet into dsOrders
Dim dsOrders As DataSet
= _
CustomerOrdersWS.GetOrdersByCustomerID(Me.txtCustomerID.Text)
' Bind the DataSet to
the Orders DataGrid
Me.grdOrders.SetDataBinding(dsOrders, dsOrders.Tables(0).TableName)
End Sub 'btnCallWS_Click
In this method, the first line of code instantiates the CustomerOrders
Web Service proxy object. The next line calls the Web Service, passing the
value stored in the Customer ID text box, and storing the return value in the
dsOrders DataSet. The last line of code binds the DataSet to the DataGrid.
Running the Customer Orders Web Service consumer
Now it’s time to run the Customer Orders Web Service
consumer project. To do this, press F5, and Visual Studio .NET automatically
saves all changes, compiles the project, and runs it. To test the Web Service,
once the form displays, enter the text “QUICK” in the text box, and then click
the Call Web Service
button (Figure 22).
Figure 22. The Web Service Consumer form calls
the Customer Orders Web
Service to retrieve the orders for the specified customer, and then displays them
in the DataGrid.
Service to retrieve the orders for the specified customer, and then displays them
in the DataGrid.
If this is the first time your Web server has started up, it
will take several seconds before any records are displayed in the DataGrid.
However, subsequent calls should respond far more quickly (you can try other
customer IDs such as “QUEEN”, “OCEAN”, and “CHOPS”).
Before continuing to the next section, close the Web Service
Consumer form to avoid any conflicts.
Web Services Discovery
Do you want to be discovered or not? If your Web
Service is of a private nature, you probably don’t. You will only inform your
business associates of its existence and not tell the rest of the world.
However, you may want to create a Web Service intended for public consumption.
How can others learn about your Web Service and the details of how to call its
methods? This is accomplished by a process called discovery.
Discovery with UDDI
Universal Description, Discovery, and Integration
(UDDI) is a registry that allows you to locate Web Services. If you have a Web
Service you want to make public, you register information about your Web
Service in the UDDI directory, and others can learn about your Web Service by
searching the UDDI registry.
As you saw earlier in this chapter, when you add a Web
Reference to your project, Visual Studio .NET provides an interface you can use
to search the UDDI directory. Let’s go back to this form and use it to search
the UDDI directory.
Right-click the Add References node in
the Solution Explorer and select Add
Web Reference from the shortcut menu. This displays the Add Web Reference dialog
(Figure 23).
Figure 23. The Add Web Reference dialog allows
you to search the UDDI directory for Web Services exposed on the Internet.
In the left pane there are two hyperlinks. The UDDI Directory link
allows you to search for “real, live” Web Services, and the Test Microsoft UDDI Directory
link allows you to search for “test” Web Services. Click the UDDI Directory link
and the message “Downloading Web Service Files” appears in the right pane. After
several seconds, the UDDI Search Tool is displayed in the left pane (Figure
24).
Figure 24. The UDDI search tool allows you to
search for Web Services by name or by category.
The UDDI search tool allows you to search for Web Services by
Service name, Provider Name, or category. For example, type the word “weather”
into the Service Name text
box and click the Search
button. As of the writing of this book, several weather Web Services registered
with UDDI are displayed in the left pane of the Add
Web Reference dialog
(Figure 25).
(Figure 25).
Figure 25. There are multiple weather services
registered with UDDI.
Pick the “Weather Retriever” Web Service from the list (if
you don’t see this specific Web Service, just choose another one). Expand the
node of the “Weather Retriever” Web Service and you will see a more detailed
description of the Web Service (Figure 26). The Service Description
details that this Web Service retrieves Weather information based on a specific
zip code. Also, notice the link displayed under “Interface definitions”
references an .asmx file. It tells you that this is a .NET Web Service
(although it doesn’t have to be a .NET Web Service to work properly in this
example!)
Figure 26. Clicking the Interface definitions
link enables the Add Reference button, allowing you to add a Web Service
reference to your project.
Adding a Web Service reference from UDDI
If you click the Interface
definitions link, the message “Downloading Web Service files…” appears
in the right pane. After several seconds, the Web Services WSDL file appears in
the left pane, and the Add Reference
dialog is enabled. Click the Add
Reference button to add a reference to the Weather Fetcher Web
Service to your project. When you do this, Visual Studio .NET adds three files
to your project. Notice the URL for the Web Service is shown in reverse order (Figure
27).
Figure 27. The URLs for Web References added to
your project by Visual Studio.NET are shown in reverse order.
When you added the local Customer Orders Web Service to the
project, you renamed the “localhost” node to something more descriptive because
it is used as the namespace of the Web Service proxy class. However, with this
public Web Service, leave the name “as is” because it provides a unique
namespace.
Next, you’ll add some user interface controls to your
project’s Form1 that allow you to call the Weather Retriever Web Service and
display its results. Drag and drop the controls listed in Table 5 from
the Visual Studio.NET Toolbox
onto the form and set the corresponding properties listed in the table.
Table 5. Weather Web Service user interface
controls
Control
|
Property
|
Value
|
GroupBox
|
||
Name
|
grpWeather
|
|
Location
|
40, 249
|
|
Size
|
540, 165
|
|
Text
|
Weather
|
|
Label
|
||
Name
|
lblZipCode
|
|
AutoSize
|
True
|
|
Location
|
80, 30
|
|
Text
|
Zip Code:
|
|
TextBox
|
||
Name
|
txtZipCode
|
|
Location
|
145, 28
|
|
Size
|
135, 20
|
|
Text
|
(empty string)
|
|
Button
|
||
Name
|
btnCallWS2
|
|
Location
|
305, 28
|
|
Size
|
100, 23
|
|
Text
|
Call Web Service
|
|
TextBox
|
||
Name
|
txtWeather
|
|
Location
|
25, 70
|
|
MultiLine
|
True
|
|
Size
|
490, 75
|
Calling the Web Service
Now you are ready to add code to the form that calls
the Web Service and displays the
result. Double-click the btnCallWS2 button to automatically add a new event handler
method named btnCallWS2_Click to the form’s code-behind file. Before adding code to
this method, go to the top of the code-behind file and add a reference to the Web Service proxy object’s namespace.
result. Double-click the btnCallWS2 button to automatically add a new event handler
method named btnCallWS2_Click to the form’s code-behind file. Before adding code to
this method, go to the top of the code-behind file and add a reference to the Web Service proxy object’s namespace.
In C#:
using WinForms_Web_Service_Consumer.com.vbws.www;
And in Visual Basic .NET:
Imports WinForms_Web_Service_Consumer_Visual_Basic.com.vbws.www
Now add the following code to the btnCallWS2_Click method at
the bottom of the
code-behind file.
code-behind file.
In C#:
private void
btnCallWS2_Click(object sender, System.EventArgs e)
{
// Instantiate the WeatherRetriever Web Service proxy
WeatherRetriever WeatherRetrieverWS = new WeatherRetriever();
// Call the Web Service's GetWeather method
CurrentWeather WeatherReport =
WeatherRetrieverWS.GetWeather(this.txtZipCode.Text);
// Display the results
this.txtWeather.Text = WeatherReport.Conditions + "\r\n"
+
"Temperature: " + WeatherReport.CurrentTemp +
"\r\n" +
"Humidity: " + WeatherReport.Humidity + "\r\n"
+
"Barometer: " + WeatherReport.Barometer +
"\r\n" +
"Barometer Direction: " + WeatherReport.BarometerDirection;
}
And in Visual Basic .NET:
Private Sub btnCallWS2_Click(ByVal sender As
System.Object, _
ByVal e As
System.EventArgs) Handles btnCallWS2.Click
' Instantiate the
WeatherRetriever Web Service proxy
Dim WeatherRetrieverWS
As New WeatherRetriever()
' Call the Web
Service's GetWeather method
Dim WeatherReport As
CurrentWeather = _
WeatherRetrieverWS.GetWeather(Me.txtZipCode.Text)
' Display the results
Me.txtWeather.Text =
WeatherReport.Conditions & ControlChars.CrLf & _
"Temperature:
" & WeatherReport.CurrentTemp & ControlChars.CrLf & _
"Humidity:
" & WeatherReport.Humidity & ControlChars.CrLf & _
"Barometer:
" & WeatherReport.Barometer & ControlChars.CrLf & _
"Barometer
Direction: " & WeatherReport.BarometerDirection
End Sub
Running the Web Service consumer
Now you’re ready to run the Web Service. To do this,
just press F5 to save all changes, compile the project, and run the
application. When the form is displayed, enter a zip code in the Zip Code text box (for
example, “22903”), and then click the Call
Web Service button. After several seconds, you should see the
weather report for the specified zip code displayed in the text box at the
bottom of the form (Figure 28).
Figure 28. This form demonstrates how to call a
public Web Service discovered by means of UDDI.
Conclusion
As you see from this chapter, Microsoft has made it
very easy to both publish and consume Web Services in Visual Studio.NET.
Although you may not initially find a use for Web Services in your application,
as they become more and more mainstream, and as new, reliable Web Services
become more prevalent, you may find they give your desktop and Web applications
a level of interoperability they’ve never had before.
Posts
No comments:
Post a Comment