Webservice Tools (Disco and wsdl -- .Net FrameWork Tools Series)

All of us have worked with web services but very of us have worked with the command line tools provided by .Net framwork. Today we will discuss .Net Webservice Tools disco.exe and wsdl.exe.

Disco.exe :-

Discovey is the most important step when it comes to webservices. This tool discovers the URL's of XML webservices on a given web server. Discovery of webservices is important for its consumers as from the discovery document they can know about the various services they can consume.

This tool locates the webservice. If it finds the webservice it creates .wsdl, .xsd, .disco, and .discomap files and if it does not then the error message displayed to the user.

Let us use this tool to discover our webservice and create the above files:

1) Go to the VS.NET command prompt

2) Run disco.exe /? for checking out all the options

3) This is a list of some important options :

/nosave - Do not save the discovered documents or results to disk (for example wsdl, xsd and disco files). The default is to save the documents.

/out: The output directory to save the discovered documents in. The default is the current directory. Short form is '/o:'.

/username:

/password:

/domain: The credentials to use when the connecting to a server that requires authentication. Short forms are '/u:', '/p:' and '/d:'.

/proxy:The url of the proxy server to use for http requests.The default is to use the system proxy setting.

4) To discover the disco files of the webservice give the URL of the web service as

disco.exe http://localhost/MyWebservice/service1.asmx /nosave .

If the URL is found the following message will be displayed to you :

Microsoft (R) Web Services Discovery Utility

[Microsoft (R) .NET Framework, Version 1.0.3705.0]

Copyright (C) Microsoft Corporation 1998-2001. All rights reserved.

Disco found documents at the following URLs:

http://localhost/MyWebservice/service1.asmx?disco

http://localhost/MyWebservice/service1.asmx?wsdl

5) We will now perform the same command without /nosave option to save the document in MyWebSerDocs folder. Please see to it

that the directory exists as this tool does not create the directory

disco.exe http://localhost/MyWebservice/service1.asmx /out:MyWebSerDocs

6)You should see a similar output

Microsoft (R) Web Services Discovery Utility

[Microsoft (R) .NET Framework, Version 1.0.3705.0]

Copyright (C) Microsoft Corporation 1998-2001. All rights reserved.

Disco found documents at the following URLs:

http://localhost/MyWebservice/service1.asmx?disco

http://localhost/MyWebservice/service1.asmx?wsdl

The following files hold the content found at the corresponding URLs:

MyWebSerDocs\service1.disco <- http://localhost/MyWebservice/service1.asmx?disco

MyWebSerDocs\service1.wsdl <- http://localhost/MyWebservice/service1.asmx?wsdl

The file MyWebSerDocs\results.discomap holds links to each of these files.

7) Check out the directory it should have all the above 3 files i.e. Service1.disco, Service1.wsdl and results.discomap

8) Similarly you can discover any web service with this tool and create the .disco, .wsdl and discomap files.

9) These files that we have generated with disco.exe can be used as an input to wsdl.exe to create our webservice proxy class.



WSDL.exe :-

This tool is used to generate webservice proxy class. This file contains all the details for its clients to use when they are interacting

with the webservice.

Let us create the webservice proxy class:

1) Go to VS.Net command prompt

2) Type wsdl.exe /? to view all the options

3) I have listed a few important options below :

- A url or path to a WSDL contract, an XSD schema or .discomap document.

/language: - The language to use for the generated proxy class. Choose from 'CS','VB', 'JS' or provide a fully-qualified name for a class implementing

System.CodeDom.Compiler.CodeDomProvider. The default is 'CS' (CSharp).

/server Generate an abstract class for an xml web service implementation using ASP.NET based on the contracts. The default is to generate client proxy classes.

/out:

The filename for the generated proxy code. The default name is derived from

the service name. Short form is '/o:'.

/protocol: Override the default protocol to implement. Choose from 'SOAP', 'HttpGet','HttpPost', or custom protocol as specifiied in the configuration file.

4) To generate the proxy class you can either use .wsdl or .discomap file that we have generated using the disco.exe or you can give the webservice url as input.

5) We will create our proxy class using the .wsdl and .discomap files that we had generated.

6) Type the following command :

wsdl.exe Service1.wsdl

or

wsdl.exe results.discomap.

Service1.cs class will be generated.

7) You can use this proxy class with any of the client application to interact with the webservice.

8) Create a client application say a Windows application and add the proxy class to it by choosing Add Existing Item and selecting out proxy class Service1.cs. Create the webservice object and call any method on it.

Service1 myWebSer = new Service1();

MessageBox.Show(myWebSer.HelloWorld());

WebServices Series Part - 5 ( Sync & Async Communication )

we saw how we can communicate with web services using callbacks. Today we will discuss the other two techniques Polling and Waithandles.

Polling :

When we made a call to our web service using callback we passed it reference to our fucntion and in return we get an IAsyncResult object back which acted as a token.

In case of polling we will again call BeginCoSine method but not pass any parameter for callback. This method will return us an IAsyncResult object. Polling works on one of the properties of this object called IsCompleted. After calling the method we will have to continuous POLL for the value of this property. When the webservice is completed with its processing the value IAsyncResult object will be set to true.After that we call the EndCoSine function passing it our IAsyncResult object (which acts as a token) to retrieve our result.

Add another button to your windows form and put in the below code :

private void button3_Click(object sender, System.EventArgs e)
{
int noOfSec = 0;
oIAsyncResult = trigoService.BeginCoSine(90,null,null);
while(oIAsyncResult.IsCompleted == false)
{
noOfSec++;
Thread.Sleep(1000);
}
MessageBox.Show("Completed in " + noOfSec);
label1.Text = Convert.ToString(trigoService.EndCoSine(oIAsyncResult));
}


Here we are checking out the value of IsCompleted property in a while loop. After the value is set to true we message the number of seconds that were taken to POLL. Finally we call EndCosine function passing our IAsyncResult object.

WaitHandles :

This method also uses one of the properties of IAsyncResult object called AsyncWaitHandle.

This approach is generally used when u dont want to leave the thread in which you are communicating with the webservice. Thus in this case you will wait for the webservice to complete its work without releasing the thread in which you were communicating. You can achieve this by using the WaitHandle returned by AsyncWaitHandle property of IAsyncResult object.

After you have called the BeginCosine method and got your IAsyncResult Token object you can use its AsyncWaitHandle property to get WaitHandle object then use its WaitOne method to wait for the thread. WaitOne has multiple overloads some also take the amount of time you want to wait.

Add another button to your windows form and add the following code snippet

private void button4_Click(object sender, System.EventArgs e)
{
int noOfSec = 0;
oIAsyncResult = trigoService.BeginCoSine(90,null,null);
oIAsyncResult.AsyncWaitHandle.WaitOne();
while(noOfSec++ < 5)
{
noOfSec++;
Thread.Sleep(1000);
}
MessageBox.Show("Waited for " + noOfSec);
label1.Text = Convert.ToString(trigoService.EndCoSine(oIAsyncResult));
}

You can also checkout the other static methods of the WaitHandle object like WaitAll and WaitAny. These methods are particularly used when you have multiple web service calls and you want to wait for either ALL of them to complete their processing and then move ahead or with ANY ONE of them to complete their processing and then move ahead.

WAIT ALL :- Wait for all the web services to complete processing.
WAIT ANY:- Wait for any one of them to complete processing.

WebServices Series Part - 4 ( Sync & Async Communication )

we will checkout how to consume our web service using SOAP in Synchronous and Asynchronous modes.

To consume to our web service we need to create our web service client.

Let us go ahead and create our web service client.

Open a new windows application and Select References Right click and select Add Web Reference. Select our Trigonometry web service.

WebReference to this web service will be added and along with it you will notice the reference.map , .disco and .wsdl files will be added for the web service. Our client interacts with our web service using a proxy class.

To view the proxy class ... Select the solution in the Solution Explorer and click on Show All Files ... You will notice a file under the Reference map node called as Reference.cs.

Open the Reference.cs file and Checkout the BASE CLASS for our webservice proxy class, it should be SoapHttpClientProtocol.

You should also notice that for each method in our webservice there are three methods in the webservice proxy class.

For Example these are the the three methods for Sine.

public System.Double Sine(System.Double angel)
public System.IAsyncResult BeginSine(System.Double angel, System.AsyncCallback callback, object asyncState)
public System.Double EndSine(System.IAsyncResult asyncResult)

Out of these three the first one is used for Synchronous communication and latter two for Asyncrhomous communication.

Let us checkout Synchrounous Communication.

Add a Form and add a button and a label to that Form

Declare a class level variable for our webservice

localhost.Service1 trigoService = new localhost.Service1();

Write the following code in the button Click event

private void button1_Click(object sender, System.EventArgs e)
{
label1.Text = Convert.ToString(trigoService.Sine(90));
}

Execute the apllication and checkout the results.

One of methods of Asynchronous communication with web service is using Callbacks.

To start with declare a class level variable for IAyncResult

private IAsyncResult oIAsyncResult;

To consume our web service in asynchronous mode let us add another button to our form and add the below code. When we communicate with our web service in a asynchronous mode we will have to call the BeginSine method and pass a CALLBACK function to it. After our web service is done with its processing it will callback our function to return the result.

private void button2_Click(object sender, System.EventArgs e)
{
oIAsyncResult = trigoService.BeginSine(90,new AsyncCallback(CallBackForEndSine),null);
}

public void CallBackForEndSine(IAsyncResult oIAsyncResult)
{
double sineVal = trigoService.EndSine(oIAsyncResult);
label1.Text = Convert.ToString(sineVal);
}

Here I am calling the BeginSine method and passing it the reference of our CallBack method CallBackForEndSine. You should notice that on Calling the BeginSine method I am returned an IAysncResult object. This object acts as a TOKEN between the client and the webservice. Hence when the Webservice is through with its processing and Callback method is called, to get the result from the webserivce we need to call EndSine method in the CallBack method passing IAsyncResult Token.

The Difference between Asynchronous & Synchronous consumption of webservices can be noticed when there is a lot of processing done by a webservice. Thus if our webservice is consumed in a synchronous mode then our clients will have to wait for the processing to complete.

To get a good taste of Asynchronous processing with our webservice we will make a little change in our methods. Before returning the result we will make the thread sleep for 20 secs.


public double Sine(double angel)
{
Thread.Sleep(20000); // make a similar change in all the methods
return System.Math.Sin(angel);
}

Compile the webservice. Update the webservice reference in your Client project and Execute your Client.

Now if our web service is consumed synchrounsouly our client will have to wait for the result. Click on Button1 and check it out. The control will come back after 20 secs and till then your application will not respond to any other events. Now let us consume the webservice in an ansychronous mode by clicking on Button2. Since the communication is asynchronous the control will return back immediately rather than waiting for 20 seconds. Later the call back function will be called to deliver the results.

WebServices Series Part - 3 (Accessing with HTTP POSTLOCALHOST, POST and GET)

we will look how we can access web services with HTTP-GET and HTTP-POST protocols.


.Net Framework 1.0 had all the three protocols i.e. HTTP-POST,HTTP-GET AND HTTP-SOAP enabled by default. But in version 1.1 only HTTP-SOAP is enabled by default. Hence if you want to access the web service my HTTP-POST or GET then you will have to enable it explicitly.



Since HTTP-POST is not enabled by default in .Net framework 1.1 to test web service on the local machine there is a new protocol that has been added i.e. HTTPPOSTLOCALHOST. It is because of this protocol that while testing a web service you are able to view a test form on your local machine and not on a remote computer.


Let us check out each of these protocols individually: -



HTTPPOSTLOCALHOST: - This is enabled by default in .Net Framework version 1.1. Hence if you access your website as http://localhost you will get the test form but if you test the same web service with http:// from some other computer than the test form will not be displayed.



e.g. Try and access our trigonometry web service from your machine and then access it from any other machine. You will notice that the test form will not be displayed.



Before we look at HTTP-POST and HTTP-GET we need to checkout DefaultWsdlHelpGenerator.aspx.



DefaultWsdlHelpGenerator.aspx is the default wsdl help file located at



:\WINNT\Microsoft.NET\Framework\v1.1.4322\CONFIG.



Open DefaultWsdlHelpGenerator.aspx and checkout showPost flag.


bool showPost = true; // search for this



Depending the value of showPost flag HTTP-GET or HTTP-POST protocol is used.Set its value to true if you want to see a POST test form and false to view a GET test form.



Along with this you will have to include the appropriate protocols in the web services tag in Web.config.



HTTP-POST: - To enable our web service with HTTP-POST we will have to make the following changes.



1. Open the web.config and add the tag under as follows to enable the HTTP-POST protocol.











2. Open DefaultWsdlHelpGenerator.aspx and set the value of showPost to true. By default it is set to true.
3. Run the web service and checkout the HTTP-POST form.
4. On execution you will see the xml output of your webservice. Checkout the URL of output in the browser it will not show any querystring parameters.



http://namrathas/Trigonometery/MyService.asmx/CoSine



5. Execute your web service from some other computer and you will be able to view HTTP-POST test form.



HTTP-GET: - To enable our web service with HTTP-GET we will have to make the following changes.



1. Open the web.config and add to protocols tage s follows to enable our webservice with HTTP-GET protocol also.












2. Open DefaultWsdlHelpGenerator.aspx and set the value of showPost to false. So now HTTP-POST form will be displayed. All the parameters will be passed as querystring.



http://namratas/Trigo/MyService.asmx/CoSine?angel=5



3. Run the web service and checkout the HTTP-GET form. Its looks the same as HTTP-POST form. You will notice the difference on execution.
4. Execute the web service and you will see the xml output of your webservice. Checkout the URL of output in the browser it will show query string parameters passed to the web method.



HTTP-SOAP: - Whenever our webservice is accessed from any application HTTP-SOAP protocol is used. HTTP-SOAP is enabled by default. We will look in to more details of HTTP-SOAP when we look into consuming webservices.



Hence if want our webservice to be enabled for all the four protocols we need to add them in the tag.

WebServices Series Part - 2 (WebMethod and WebService Properties)

After creating our basic web service yesterday we will look into the web method properties and supported data types.

Well Whenever we create a web service all those methods of the web service which we want to be web-callable have to be marked with the web method attribute and should have a public access modifier. Web Method Attribute is basically used to make a method web callable.

WebMethod attribute has the following properties like :-


* Description
* TransactionOption
* CacheDuration
* BuffferResponse
* EnableSession
* MessageName



Description :- It is used for commenting the web method. The description that is added here is included in WSDL. Add the

webmethod description property above any method as shown below. When you call the webservice from a browser you view the web service.



e.g. [WebMethod(Description = "My WebMethod Description comes here")]



Enable Session :- WebServices are a type of ASP.NET applications hence you can access your ASP.NET application Session from your webservice. By default the session is disabled i.e. set to false. You can enable it by setting its value to true.



e.g. [WebMethod(EnableSession ="true")]



Message Name :- Message Name property is used give an alias to a method name. This is esp. useful when you are using overloaded methods.



e.g. Yesterday we created 3 method in our webservice for cos,sin and tan which took double as an input parameter. Today we will create their overloads that will take int as an input parameter


[WebMethod]
public double Tan(int angel)
{
return System.Math.Tan(angel);
}

[WebMethod]
public double Sine(int angel)
{
return System.Math.Sin(angel);
}

[WebMethod]
public double CoSine(int angel)
{
return System.Math.Cos(angel);
}



If you compile this code it will compile successfully. It is on execution that you we view the below error message



Error Message: Both Double Tan(Int32) and Double Tan(Double) use the message name 'Tan'. Use the MessageName property of the WebMethod custom attribute to specify unique message names for the methods.



Web service needs to identify each method uniquely hence we will give alias to the methods by setting the MessageName property.



e.g. [WebMethod(MessageName = "SinInt")]
[WebMethod(MessageName = "CosInt")]
[WebMethod(MessageName = "TanInt")]

TransactionOption : - If our web service is a part if any COM/MTS transaction application then we can enable the Transaction Option of the webservice thus making it a part of the 2 phase commit protocol of MTS.



e.g. [WebMethod(TransactionOption = "Supported")]



The dafault is same as COM/MTS transactions i.e. Required.



CacheDuration :- Like any other ASP.NET applications WebServices also support output caching. Output caching gives a performance boost coz the same request is not executed repeatedly instead the result is return from the cache itself. This feature is

esp. useful when you are retrieving chunks of data from the database for listing and other purposes. But caching should preferably used with only those methods where we know that the data will not change frequently.



e.g. [WebMethod(CacheDuration = "180")]

This means the output of this method will be cached for seconds.



BuffferResponse :- We all are familiar with the buffering property rite from our ASP days where used Response.Buffer = true so that

the response is only sent when the Response for the request is completely generated or when the buffer is full. WebServices also use the same logic. If we want our response to be sent across only after its complete processing is done we need to buffer our response by setting its property to true.



e.g. [WebMethod(BufferResponse = "true")]



By default it is set to true.



These properties were webmethod properties. We also have some web service properties like



* Description.
* Name
* NameSpace


Description :- This is same as web method property. It is used to comment web service and give it a description that is included in WSDL.



e.g. [WebService(Description = "My WebService Description comes here")]
public class MyService : System.Web.Services.WebService

{
Name :- By default the name of the class is used as the service name but incase we want to give a different service name which will to exposed to our clients and in WSDL we can set the Name property. This property will override the default value i.e. the class name.



e.g. [WebService(Name = "MyNewName")]
public class MyService : System.Web.Services.WebService
{



NameSpace :- The default name space is http://tempuri.org. You can change this to http://localhost/MyWebServices. You should set namespace to any unique value.



e.g. [WebService(Namespace = "http://localhost/MyWebServices")]
public class MyService : System.Web.Services.WebService
{

WebServices Series Part - 1

WebServices Series Part - 1