How to document web service in ASP.NET in VB.NET

ASP.NET automatically provides all the information the client needs about what web service’s methods are available and what parameters they require. This is provided by the XML-based standard named WSDL. Because WSDL, does not describe web service’s purpose or the meaning of the information supplied to and returned from each method you should prepare a separate document. ASP.NET provides possibility to include a bare minimum of information with your web service by using the WebMethod and WebService attributes.

You can use the Description property of the WebMethod attribute to add description to each method and you can use Description property of the WebService attribute to add description to the entire web service as a whole. The next code lines show this:

 

Imports System.Web.Services

<WebService(Name:=”Books Service”, Description:=”Retrieve the books store information”)> _

Public Class BooksService

Inherits System.Web.Services.WebService

 

<WebMethod(Description:=”Return the total number of books”)> _

Public Function GetBooksCount() As Integer

‘…..

End Function

<WebMethod(Description:=”Return the full list of books”)> _

Public Function GetBooks() As DataSet

‘…..

End Function

End Class

 

You should supply one other detail for your web service – a unique XML namespace, which allows our web service to be uniquely identified. By default, ASP.NET web services use the default XML namespace http://tempuri.org/, which is suitable only for testing. Note: If you   don’t set a custom namespace, you’ll see a warning message in the test page advising you to use something more distinctive.

Preferably, the namespace you use is referring to a URL address that you control and in most cases, this incorporates your company’s Internet domain name as part of the namespace. For example, if your company uses the website http://www.mycompany.com, you can give the Books web service a namespace such as http://www.mycompany.com/BooksService.

 

The namespace is specified through the WebService attribute, as shown here:

 

<WebService(Name:=”Books Service”, _

Description:=”Retrieve the books store information” _

Namespace:=”http://www.mycompany.com/BooksService)> _

Public Class BooksService

Inherits System.Web.Services.WebService

‘…

End Class