Click here to Skip to main content
Click here to Skip to main content

Introduction to .NET Web Services

, 25 Jun 2003
Rate this:
Please Sign up or sign in to vote.
Introduction to .NET web services.

What’s a Web Service?

The buzz word around IT these days is Web Services. A web service is not a website that a human reads. It is not anything with which an end user would directly interact. A web service is a standard platform for building interoperable distributed applications. It allows you as a developer, to interact with other information providers without worrying about what they are running either at the backend or even their front-end. Take for example a company stock ticker that you may wish to have, say on your website or intranet. The data could possibly be coming from a major news site like MSN or NASDAQ. The way you would currently achieve this is either by buying access to their database or by ‘scraping’ their home page HTML for the relevant data and converting it into your format. Suppose they go ahead and change their web design, all the scraping code you would have written would be rendered useless. Even if you buy access into their system, they may be running a technology that is incompatible or too hard to work with your own.

So what do you do? This is where web services help out. In short, Web Services are pieces of program logic that are programmatically available via the Internet. These pieces of program logic which are in the form of objects, can be invoked from any client over HTTP (Hypertext Transfer Protocol). It functions primarily through XML in order to pass information back and forth through HTTP. By allowing data interchange in the standard XML format, anybody can pick up the data and use it. Basically, you can author a web service and make its properties and methods available to other developers across the web, without writing vast amounts of documentation for an API or distributing DLLs to everyone who wishes to use them. In a typical web services scenario, a business application sends a request to a service at a given URL, using the SOAP protocol over HTTP. The service receives the request, processes it, and returns a response. An often-cited example of a web service is that of a stock quote service, in which the request asks for the current price of a specified stock, and the response gives the stock price. This is one of the simplest forms of a web service in that the request is filled almost immediately. A Web Service is defined as "a component of programmable application logic that can be accessed using standard web protocols". It's basically a component, or an assembly in ASP.NET, that can be accessed over the web.

The concept of sending messages between servers or remotely calling functions is not new. Technologies such as DCOM (Distributed Component Object Model) and CORBA (Common Object Request Broker Architecture) are well-known proprietary protocols that have been in use for years. What is new is, web services use a standard protocol called SOAP to transfer messages over HTTP. SOAP makes it possible for applications written in different languages running on different platforms to make remote procedure calls (RPC) effectively, even through firewalls. DCOM doesn't use port 80, which is reserved for HTTP traffic; this causes DCOM calls to be blocked by firewalls. SOAP calls use port 80, which makes it possible to call procedures that exist behind firewalls.

We can use ASP.NET to create a web service on the .NET platform, and can be built using any .NET language. The reasoning for choosing ASP.NET for this purpose is quite logical. We don't need to reinvent the plumbing -- that is, at a high level, the capability to serialize our data as XML, transport the data using HTTP, and de-serialize the XML back to meaningful data. Instead, we want a framework that makes building web services easy, allowing us to focus on the application logic, not the plumbing. ASP.NET provides this framework for us. Building web services using ASP.NET will require IIS to run the application. Web services built using ASP.NET will have .asmx file extensions. It is the end point for accessing your web services. Like .aspx files, .asmx files are automatically compiled by the ASP.NET runtime when a request to the service is made. If a .asmx file is requested by a browser, the ASP.NET runtime returns an XML web service help page that describes the web service.

The Web Service Description Language (WSDL)

How do you explain to others, the functions that your web service exposes and the parameters each function accepts? You might do it informally by writing a document that provides this information, or you might simply verbalize it for someone who needs to invoke your web service. This informal approach has at least one serious problem: When a developer sits down to build a client for your web service, his development tool (for example, Visual Studio .NET) cannot offer him any help, because that tool has no idea about the web service's functions and parameters. Providing a formal description in a machine-readable format solves this problem. The Web Service Description Language (WSDL) is an XML-based grammar for describing web services, their functions, parameters, and return values. Being XML-based, WSDL is both machine and human-readable, which is a big plus. Every web service must have a WSDL. The WSDL supplies the detailed information about the web service's functionality and how to access this functionality, to the clients. Rather than creating an actual WSDL file, ASP.NET generates the WSDL information dynamically. If a client requests the web service’s WSDL file (either by appending ?WSDL to the ASMX file’s URL or by clicking the "Service Description" link in the web service help page), ASP.NET generates the WSDL description, which is then returned to the client and displayed in the web browser. Because the WSDL file is generated when it is requested, clients can be sure that the WSDL contains the most current information.

Accessing an XML web service through a proxy class

You can access a web service from within an application, by creating a web service proxy class. The Microsoft .NET framework SDK includes a built-in command line tool called Wsdl.exe which is used to generate proxy classes for consuming web services. The word "consume" in this context means, to use the web service, to call the web service and to send it the appropriate information as parameters, to receive information back from the web service formatted as SOUP message, and then to be able to display that information. Using Wsdl.exe to create proxy classes makes it easy to invoke the web services. The proxy class encapsulates all the complexities of calling a web service, so that you as the consumer of the web service don't have to know SOUP, don't have to know where the web service resides, don't have to know anything about how to take XML message and deserialize it into a set of classes. All that you have to know is, this is actually all done for you by the proxy class. The proxy class will handle all the SOAP requests/responses. Basically what you can say is, a proxy class serves as an intermediate between the web service provider and the web service consumer.

So whenever the client application calls a web service method, the application actually calls a corresponding method in the proxy class. This method takes the name of the web service method that is being called and its arguments, and then formats them so that they can be sent as a request in a SOAP message. The web service receives this request and executes the method call, sending back the result as another SOAP message. When the client application receives the SOAP message containing the response, the proxy class decodes it and formats the results so that the client application can access them. The information is then returned to the client. The proxy class has the same methods and properties of the web service class, but it it does not contain the actual implementation. It simply acts as a 'go-between' your code and the web service, so that you don't have to deal with the complicated details of the web service in XML. The proxy class contains methods that can make either synchronous or asynchronous calls to web services. Synchronous methods are represented by the name of the actual method call, and asynchronous methods are represented by the name of the method call preceded by Begin and End. The .NET framework uses a common design pattern for all asynchronous calls. For example, for the Delete method call, there is a BeginDelete and an EndDelete used to call the Delete method asynchronously.

To generate a proxy class, you need to complete the following steps:

  1. Use the Wsdl.exe tool to generate the source code file for the proxy class.
  2. Compile the source code file for the proxy class.
  3. Copy the compiled proxy class into the ASP.NET application's /bin directory.

To compile a proxy class for the WeatherService web service, for example, you would execute the Wsdl.exe tool from a command line prompt like this:

wsdl.exe /l:vb http://www.yoursite.com/Services/WeatherService.asmx?wsdl

The /l switch indicates the language used for generating the source code file for the proxy class. Because you want to generate a Visual Basic class, you supply the argument vb. The web address supplied to the tool is the address of the Web Service Description Language (WSDL) file for the web service. You can always retrieve the WSDL file for a web service by appending the query string ?wsdl to its address. The WSDL file is an XML file that contains the description of all the methods and properties of a web service. This file is generated automatically for you. Executing the Wsdl.exe tool generates a file named WeatherService.vb that contains the source code for a Visual Basic class file. This class file is the proxy class, and before you can use this proxy class, you first need to compile it by executing the Visual Basic command-line compiler like this:

vbc /t:library /r:System.dll,System.Web.Services.dll,
                               System.Xml.dll WeatherService.vb

This statement references all the needed assemblies to compile the WeatherService.vb file to a DLL file. After the class is compiled, you need to copy it to your ASP.NET application's /bin directory so that it is visible to your ASP.NET pages. If you have the Microsoft .NET Framework SDK Documentation installed on your computer, you can view more information about this tool over here.

Alternatively, Visual Studio .NET can generate these proxy classes for you by choosing "Add Web Reference" from the Project menu. When creating a web reference through the "Add Web Reference" dialog box, what you are really doing is creating proxy classes. Visual Studio .NET uses the WSDL to create this proxy class. The proxy class is a local representation of the properties and methods of a remote web service class. So by creating the proxy class, you can call a web service’s methods as if the web service resided locally. The "Add Web Reference" dialog box basically allows you to browse for web services and add web references to your Visual Studio .NET projects. At the very top of the "Add Web Reference" dialog box, you have an address bar where you can type in the exact URL to the web service. The URL for the web service can be a location on your local machine, or on servers within your company's local area network, or the Internet for commercial web services. To find web services, you can browse to a web service description page (.asmx or .wsdl), or a discovery page (.disco or .vsdisco).

Discovery of Web Services (DISCO) is a Microsoft-specific technology used to locate web services in a particular directory on a server. There are three types of discovery files: .disco files, .vsdisco files and .map files. The .vsdisco files are placed in the web service application, whereas .disco files are accessed via the ASMX page. Like WSDL data, the .disco information for an ASP.NET web service is not a physical file. The .NET framework generates this file when a client requests it (by appending ?DISCO to the ASMX’s URL). For instance, if the URL to an XML web service is www.yoursite.com/Services/WeatherService.asmx, then a discovery document is automatically generated with a URL of www.yoursite.com/Services/WeatherService.asmx?DISCO. This .disco file contains references to files in the current web service only. All three DISCO files contain XML that can help clients locate web service files. A .disco file contains markup that specifies references to a web service’s WSDL file and other DISCO documents. A .vsdisco file (also known as "Dynamic discovery"), on the other hand, returns markup (which also contains references to the web service's WSDL file and DISCO documents) when requested. If a potential client requests a .vsdisco file, the .NET framework analyzes the directory in which the .vsdisco file is located, as well as that directory’s subdirectories. The .NET framework then generates markup (using the same syntax as that of a .disco file) that contains references to ALL web services in that directory and the directory’s subdirectories. For security reasons, developers can specify in the .vsdisco file that certain directories should not be searched when the markup is generated. Normally, the .vsdisco file contains only markup specifying which directories should not be searched. It is important to note that developers usually do not view .vsdisco markup. Although a developer can open a .vsdisco file in a text editor and examine its markup, .vsdisco files are intended to be requested (i.e., viewed in a browser). Every time this occurs, new DISCO markup is generated and displayed.

Developers benefit from .vsdisco files, because the files contain a small amount of data and provide up-to-date information on the web service files provided by a server. However, .vsdisco files generate more overhead than .disco files do, because a search must be performed every time a .vsdisco file is accessed. You will typically place a .vsdisco file at the root of a server. When accessed, this file locates the .disco files for web services on the system and uses these .disco files markup to return information about the entire system. Once a user locates an XML web service, the user can then call the methods of the XML web service. This makes dynamic discovery a powerful ability for the user, but a potential security risk for your server. In most cases, you will not want dynamic discovery to be enabled, and by default, dynamic discovery is disabled when the .NET framework is installed. This does not mean that the XML web services are not available, it just means that the server will not provide a directory of the available services. Clients will still be able to use XML web services, but you will need to provide the exact location of the service to them.

Two items control the dynamic discoverability of an XML web service on the server. The first item, the machine.config file, controls the overall discoverability of the server. The machine.config file, located in the \%windows%\Microsoft.NET\Framework\Version\Config folder, is an XML file that contains settings that control web applications on the server. This file contains an element that is commented out by default. To enable dynamic discovery, you need to remove the comment characters.

<!--<add verb="*" path="*.vsdisco" 
type="System.Web.Services.Discovery.DiscoveryRequestHandler, 
System.Web.Services, Version=1.0.3300.0, Culture=neutral, 
PublicKeyToken=b03f5f7f11d50a3a" validate="false"/>-->

The second item is a discovery file. The discovery file may be the default discovery file, default.vsdisco, or an XML web service-specific discovery file. The discovery file is an XML file that contains information about the location of the XML web service files. To make a particular XML web service discoverable, you need to enable discovery in the machine.config file and create and deploy a discovery file with the application. If you are using Visual Studio .NET, this discovery file is automatically created for you, when you create a project. The discovery file is an XML file that simply lists the paths where XML web services will not be found. An example is shown below.

<?xml version="1.0" encoding="utf-8" ?>
<dynamicDiscovery xmlns="urn:schemas-dynamicdiscovery:disco.2000-03-17">
     <exclude path="_vti_cnf" />
     <exclude path="_vti_pvt" />
     <exclude path="_vti_log" />
     <exclude path="_vti_script" />
     <exclude path="_vti_txt" />
     <exclude path="Web References" />
</dynamicDiscovery>

Note: When dynamic discovery is enabled, all XML web services and discovery documents existing on the web server beneath the requested URL are discoverable. Therefore, care must be taken when enabling dynamic discovery, as it could unintentionally expose sensitive data, if the web server is not on a secure network with a firewall.

After you have located an XML web service for your application to access, by using the Add Web Reference dialog box, clicking the Add Reference button will instruct Visual Studio .NET to download the service description to the local machine and then generate a proxy class for the chosen XML web service. You can use the Web Reference URL property to specify the URL to the XML web service. The Add Web Reference sets the URL property by default to the URL of the XML web service you select, which is a static URL. A web reference can use either a static URL or a dynamic URL. If you leave the URL Behavior set to the default value of static, the proxy class sets the URL property using a hard-coded URL when you create an instance of the class. If you set the URL Behavior property of the web reference to dynamic, the application obtains the URL at run time from the <appSettings> element of your application's configuration file (web.config). When you specify a dynamic URL after adding a web reference, Visual Studio .NET updates the proxy class to obtain the URL from the configuration file. So by adding the web reference, Visual Studio .NET will connect to the web service, parse the WSDL, and generate the proxy class which you can use to program with.

Creating a web service is similar to creating a COM (Component Object Model) component that provides application logic to a client application. You create a web service to provide specific functionality to client applications over the Web. To create a web service, you first choose a programming language in which you want to create the service and create a class that inherits from System.Web.Services.WebService.

Conclusion

As you can see, the Microsoft .NET framework does a lot of work for you in helping you easily build web services. Many aspects of web service creation and consumption such as generating WSDL, proxy classes, and DISCO files are handled by the .NET framework itself. While Visual Studio .NET provides a feature-rich integrated development environment for .NET development, it's not required to create .NET web services. Applications can also be created using your favorite text editor and the command-line tools that ship with the Microsoft .NET Framework SDK.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Saumendra Poddar
Web Developer
Canada Canada
No Biography provided

Comments and Discussions

 
Questionwebservice sample with json PinmemberMehdipirmoradian21-Mar-14 13:38 
GeneralMy vote of 3 Pinmembernagaraju@techacesoft4-Apr-13 3:00 
QuestionWeb Service - ASP.net for Beginners Pinmemberetechpulse1-Jan-13 22:10 
GeneralMy vote of 4 PinmemberSamitha Gunarathna19-Dec-12 1:21 
GeneralMy vote of 5 PinmemberMahsa Hassankashi3-Feb-12 5:41 
Questionvery Good Work PinmembersamTheDev@gmail.com7-Nov-11 13:49 
GeneralIt's a nobel work. Pinmembergggmarketing10-Sep-11 4:08 
GeneralPlease fix formatting problems PinmemberSAKryukov30-May-11 11:14 
GeneralMy vote of 2 PinmemberLibin Jose chemperi12-Dec-10 22:48 
GeneralMake a Photo Gallary PinmemberMohit kr Batwada30-Apr-10 16:09 
GeneralCann't find wsdl.exe Pinmemberadhsys7-Jan-10 11:28 
GeneralExcellent! Pinmemberfantastic45-Jan-10 7:41 
GeneralNo Lisence needed Pinmemberkavehjozani18-Aug-09 3:04 
GeneralGood one Pinmemberbelame16-Jul-09 11:35 
GeneralEasy to understand PinmemberWaruna5-Apr-09 16:58 
QuestionASP.NET application's /bin directory? Pinmemberaref878-Nov-08 8:18 
AnswerRe: ASP.NET application's /bin directory? Pinmemberaref879-Nov-08 5:37 
AnswerRe: ASP.NET application's /bin directory? Pinmemberruisen8-Mar-09 2:30 
GeneralFor Web Service terms and Terminology in .net PinmemberDotNetGuts10-Sep-08 13:45 
QuestionDifferent types of web services? Pinmembersinanju23-May-08 2:45 
GeneralRe: Different types of web services? Pinmembersinanju2-Jun-08 19:16 
GeneralGreat Article PinmemberAnil Srivastava23-Mar-08 22:39 
GeneralHelp Needed Pinmemberraju57252-Nov-07 3:35 
I am new to UML,XSD and WSDL...But my requirement is to develope a webservice with the provided...I am unable to understand From where should I start...any hint will be thankful.
 
thanks
 
Raju
Generalsmall typo Pinmemberblackjack215030-Jul-07 1:25 
GeneralWeb Services - Excellent article PinmemberSrinivasan Seshadri30-Jul-07 0:27 
Questionvsdisco.file doesn't come up Pinmemberhariyani3-May-07 20:05 
GeneralGood Article PinmemberNeoshid19-Apr-07 21:27 
Generalweb services PinmemberMember #33329831-Mar-07 2:18 
Questionweb services PinmemberMember #33329831-Mar-07 2:16 
GeneralPraise Pinmemberbijulsoni9-Nov-06 3:18 
GeneralGood and Understandable PinmemberHimaBindu Vejella4-Jun-06 21:58 
JokeGood Article Pinmemberashushere19-Apr-06 13:41 
GeneralSession in web service Pinmemberkoo922-Apr-04 9:53 
GeneralRe: Session in web service PinmemberKumar Abhimanyu17-May-08 9:00 
GeneralExport into .csv Format PinsussAnonymous19-Aug-03 19:26 
GeneralASP .NET application Pinmemberlkbcpy18-Aug-03 7:21 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web03 | 2.8.141223.1 | Last Updated 26 Jun 2003
Article Copyright 2003 by Saumendra Poddar
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid