"Hand-on" Introduction to XML
Web Services
Author: Jeff Nuckolls
(May 2000)
|
Introduction
By now you probably have heard a lot of hype about XML Web Services.
The term Web Service is quickly becoming a regular house-hold name, right? Well
maybe that's an overstatement, but you're sure to see it in about every
technical article, magazine, or book recently published. The purpose of this
article is to give you a "hands-on" introduction to XML Web Services. This
article is intended for the application developer looking for a quick
Step-by-Step on how to build XML Web Services and/or for the business decision
maker looking to get a better understanding of what XML Web Services are and
how they can be used.
|
|
The code samples in this article were built using the
latest releases of Visual Studio .NET (version 7.0.9466) and the .NET Framework
(version 1.0.3705).
Click here
to download the source code for this article.
|
|
What is a XML Web Service?
In simplest terms, an XML Web Service can be defined as an
application accessible to other applications over the internet. At first
glance you might think a Web Service sounds
similar
to a Web Site; however this is not the case. The most distinctive differences
are as follows:
|
| Web Site
|
Web Service
|
| Has a user interface
|
Does not have a user interface
|
| Designed to interact with users
|
Designed to interact with other
applications
|
| Designed to work with web browsers
clients
|
Designed to work with any type of client
or device
|
|
Without going into the history and evolution of
distributed application development; XML Web Services as a concept is not
entirely new. However; XML Web Services takes a new approach to
resolving a fundamentally old business problem - application integration
. Today's business world is cluttered with legacy systems and modern-day
applications. This is the result of business critical dinosaurs that are too
big to kill, layered with years of good-idea technology needed to maintain
a competitive edge and/or increase profit margins. It is a fact that more
than 60% of all business transactions today are still printed, faxed, and/or
mailed. This can be directly attributed to the lack of seamless
integration between existing systems, applications, and/or partner systems,
because they don't speak the same language, for example (UNIX <> Windows,
EDI <> Commerce web site, COM <> CORBA, TCP <> IIOP, etc.).
XML Web Services address these business challenges by leveraging a set of
universally understood industry standard web protocols. These standard web
protocols are as follows:
-
XML - (eXtensible Markup Language) A human-readable
text format used to contain and define semi-structure and typed information.
For more information visit (http://www.w3.org/xml).
-
WSDL - (Web Services Description Language) A XML-based
file used to define the behavior of an XML Web Service and how a client can
use/interact with it.
For more information visit (http://www.w3.org/TR/wsdl).
-
SOAP - (Simple Object Access Protocol) A light weight
XML-based transfer protocol used to exchange well-formed XML and typed
information.
For more information visit (http://www.w3.org/2002/ws).
-
UDDI - (Universal Description Discovery and
Integration) UDDI is a Web Service itself that provides and means to publish
information about Web Services as well as provide a means for other to search
and discover information about Web Services.
For more information visit (http://www.uddi.org).
These terms are certainly worth further
investigation, and I encourage you to do so; however, for the purposes of this
article, I will not define them in detail.
|
When should I use a XML Web Service?
Before you go converting all of your classes and objects into XML
Web Services, it's important to understand some strengths and weaknesses. For
starters, I think it goes without saying, that any application can only be as
good as the programmer, technology, and/or standards used to define and develop
them. XML Web Services today rely on several new standards that unfortunately
lack some maturity, such as built-in security and/or transactions. As the SOAP
1.2 specification continues to evolve these short-comings become less of a
concern. However today, developers are still required to implement their own
ad-hoc solutions for handling security and transactions. There are certainly
ways around this, but it's beyond the scope of this article.
On a lighter note XML Web Services have broad appeal and several hundred
vendors have been collaborating to define the standards and specifications
including Microsoft, IBM, Sun, Oracle, etc. Currently there are several XML Web
Services in production, including some that you may already be using today,
such as Microsoft Passport (A Web Service used for single username and password
sign-in.). What makes XML Web Services so appealing is that they are
serialized as XML. This makes it the perfect medium for distributed
applications and transferring information across firewalls and between
disparate systems, devices, and platforms.
Figure 1 gives
a graphical depiction of XML Web Services in action.
|
Figure 1:
|
|
Based on the strengths and weaknesses
mentioned above you should consider creating and using XML Web Services when
creating reusable business logic or transferring information to:
-
Multiple client interfaces (Web, Windows, Wireless,
etc.)
-
Disparate platforms
-
Distributed applications
|
How do I create a XML Web Service?
Creating XML Web Services is made easy with Visual Studio .NET. Of
course, you can create XML Web Services using Visual Basic 6.0 and the SOAP SDK
Tool Kit, but this requires significantly more coding and a strong
understanding of XML. With Visual Studio .NET and the .NET Framework you
literally do not need to know any XML (although it helps) because the
.NET Framework does all the plumbing for you. This allows you to focus on the
business logic your Web Service will provide. The following is a step-by-step
walk through of creating a simple XML Web Service using Visual Studio .NET:
In this example we are going to create an XML
Web Service that accepts a parameter and returns some data from a database.
Step 1: (Open a New Web Service Project)
1) Select START -> PROGRAMS -> MICROSOFT VISUAL STUDIO .NET
-> MICROSOFT VISUAL STUDIO .NET
2) When Visual Studio .NET opens, select FILE -> NEW -> PROJECT
3) When the New Project dialog box opens, select VISUAL BASIC PROJECTS from the
Project Types pane, then select ASP.NET WEB SERVICE from the Templates pane.
4) Change the Project Name from WebService1 to MyService as in
Figure 2.
5) Click OK
|
| Figure 2: |
|
|
Step 2: (Add Some Code)
At this point Visual Studio .NET created a new web folder and
generated all the necessary files for your Web Service.
|
1) From the Solution Explorer window shown in
Figure 3, rename the file named
Service1.asmx to DataService.asmx.
2) From the Properties Window change the Name property from Service1 to
DataService.
3) With DataService.asmx selected, right-click and select VIEW CODE from the
option menu.
(This will display the DataService.aspx.vb file often
refered to as the "code-behind" file for the DataService.aspx file. In this
file you will notice that Visual Studio .NET has already provided some sample
code for you.)
4) Here we will not leverage the HelloWorld
sample code provided for us, but add our own to retrieve some information from
a database and return it to the client.
|
| Figure 3:
|
|
|
| Just below the HelloWorld function add
the following code:
|
|
'The
<WebMethod()> tag exposes this function as a Web Service.
'This
function accepts 1 parameter and returns a DataSet to the
'
calling client application.
<WebMethod()>
Public Function
GetAuthors(ByVal sValue As
String) As DataSet
'Declare your variables
Dim sSQL As
String =
"SELECT au_lname, au_fname, phone,
address, city, state, zip FROM Authors Where state='" + sValue + "'"
Dim sConn As
String</SPAN>="SERVER=localhost;UID=sa;PWD=;DATABASE=pubs;"
'A DataSet is an in-memory container of data from
a database or XML document.
Dim ds As
New DataSet()
'A DataAdapter is a connector between a DataSet
and database.
'A DataAdapter performs two actions:
'
1) Retrieves information from a database to fill a DataSet with data.
'
2) Updates changes to data in a DataSet back to a database.
Dim da As
New SqlClient.SqlDataAdapter(sSQL, sConn)
'Here we use the DataAdapter to fill the DataSet
with
' the results from the database query.
'We will call the table in the DataSet
"AuthorsList".
da.Fill(ds, "AuthorsList")
'Here we return the DataSet containing the
"AuthorsList"
'to the calling application.
Return ds
End
Function
|
|
|
4) Click F5 to Run and test your code. The .NET Framework provides a
simple client for you by default to test your XML Web Services. It also
provides some other helpful information about your Web Service such as the
Contract or WSDL file, SOAP headers and body, as well as the request/response
information. All of this is created for you by the .NET Framework.
|
|
Once the browser window is finished rendering you should notice the function
name as a link in the upper-left corner called "GetAuthors".
5) Click on the GetAuthors link. 6) Once the GetAuthors test page appears, you
can enter a parameter into the text box and invoke your Web Service. Enter "CA"
into the sValue text box and Click Invoke.
|
|
This example returns all of the California authors in
XML Format. You can have it return authors from other states by
entering other parameters, such as "MI" for Michigan or "UT" for Utah.
|
How do I consume and use a XML Web Service?
In the previous example we created a simple XML Web Service that
returned some results from a database. You may have noticed that it was
returned in XML format, but in our code we were returning results from the
database contained in a DataSet object. So why was it represented as XML in our
browser window? This is because a DataSet is serialized as XML. However; if the
calling client was developed using .NET then it would interpret the results as
a DataSet object and could then bind this object to a data-bound control.
Otherwise the client will receive well-formed XML.
|
Here I will demonstrate how to create a
simple .NET client application that consumes the XML Web Service we have just
created.
Step 1: (Create a New ASP.NET Web Project)
1) Select START -> PROGRAMS -> MICROSOFT VISUAL STUDIO .NET ->
MICROSOFT VISUAL STUDIO .NET
2) When Visual Studio .NET opens, select FILE -> NEW -> PROJECT
3) When the New Project dialog box opens, select VISUAL BASIC PROJECTS from the
Project Types pane, then select ASP.NET WEB APPLICATION from the Templates
pane.
4) Change the Project Name from WebApplication1 to MyClient.
5) Click OK
|
Step 2: (Add a Reference to a Web Service)
At this point Visual Studio .NET created a new web folder and generated all the
necessary files for your ASP.NET Web Application.
|
1) From the Solution Explorer window shown in, rename
the file named WebForm1.aspx to Default.aspx.
2) Create a reference to our XML Web Service by right-clicking on References in
the Solution Explorer window and selecting Add Web Reference, as shown in
Figure 4.
3) Once the Add Web Reference window opens, enter "http://localhost/MyService/DataService.asmx"
into the Address text box, then press the Enter button.
(Here we entered in a the URL directly to the
XML Web Service we created earlier; however you could easily select a XML Web
Service publicly available over the internet by selecting the link to the UDDI
Directory from the left pane. UDDI contains information about commercially
available Web Service published for reuse; sometimes for a fee.)
|
Figure 4:
|
4) Once the WSDL information is displayed in the right
pane as shown in Figure
5, select the Add Reference
button. This completes the Add Reference process.
|
| Figure 5:
|
|
|
Step 3: (Add Some Web Controls)
Once we have created a Web Reference to the Web Service, we can add some Web
Controls and code to interact with it.
1) From the Toolbox Window, Drag-and-Drop the following Web Controls and modify
the (ID) and Text properties for each Web Control as follows:
|
| Web
Control
|
(ID)
|
Text
|
| Label
|
lblState
|
State:
|
| Textbox
|
txtState
|
|
| Button
|
cmdGetAuthors
|
Get Authors
|
| DataGrid
|
grdAuthors
|
|
|
2) Once you have added and modified all the
appropriate Web Form Controls, it's time to add some code. Double-click the
"Get Authors" button; this will take you to the code-behind file where we will
add some code.
3) Add the following code to the cmdGetAuthors_Click event:
|
|
Private
Sub cmdGetAuthors_Click(ByVal
sender As System.Object,
ByVal e As System.EventArgs)
Handles cmdGetAuthors.Click
'Create a new instance of the Web Service
Dim ws As
New localhost.DataService()
'Here you are passing text from the Textbox
control
'to the Web Service's GetAuthors function.
'The results (A dataSet containing a list of
authors.) are then
'set to the DataGrid's DataSource property.
grdAuthors.DataSource = ws.GetAuthors(txtState.Text)
'Once the DataGrid's DataSource property has been
set
'we need to bind the results to the DataGrid
making them it
'to the end-user.
grdAuthors.DataBind()
End
Sub
|
|
4) Click F5 to Run and test your code.
5) Once the browser window comes up, enter "CA" for California into the Textbox
and click the Get Authors button.
This will return a list of Authors from the XML Web Service we created in the
first example over HTTP. The results should resemble
Figure 6.
|
Figure 6:
|
|
|
Final Thoughts
Now that you have had a brief introduction to XML Web Services, seen its
strengths and weaknesses, and walked through the creation and consumption
of them; you are probably ready to delve in a little deeper. I highly
recommend further reading on WSDL, SOAP, and UDDI. You can find more
information on these standards online at www.w3.org. For advance topics and/or
examples you might want to review some of the following links:
http://msdn.microsoft.com
http://www.gotdotnet.com
http://www.aspalliance.com
http://www.dotnetjunkies.com
|
Author Bio:
Jeff Nuckolls (MCSE, MCSD, MCP+I, ASE) is an industry leading Software
Architect with a background in Software, Network, and System Engineering.
Specializing in Microsoft .NET Development tools and technologies, he actively
contributes to technical articles, whitepapers, and user groups while also
speaking at several conferences and formal training events. Jeff can be reached at
jeffnuck@microsoft.com.
|
