How to document web service in ASP.NET in C#

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:

 

[WebService(Name=”Books Service”,

Description=”Retrieve the books store information”)]

public class BooksService : System.Web.Services.WebService

{

[WebMethod(Description=”Returns the total number of books.”)]

public int GetBooksCount()

{ … }

[WebMethod(Description=”Returns the full list of books.”)]

public DataSet GetBooks()

{ … }

}

 

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/BookService/”)]

public class BooksService : System.Web.Services.WebService

{ … }