Documenting ASP.NET Web Services

The power of TechWriter comes from its ability to leverage information from your web service. In this topic we will show you how to document web services created with ASP.NET by including descriptions directly within the ASP.NET source code as an alternative to creating annotations within TechWriter.

Documenting Web Services

ASP.NET includes the WebService attribute that can be used to add a description to the class that implements your web services. Here is an example in C#:

[WebService(Description = "Service for getting a stock quote.")]
public class StockQuote : System.Web.Services.WebService
{
...
}

Here is the same example in VB.NET:

<WebService(Description = "Service for getting a stock quote.")> _
Public Class StockQuote
Inherits System.Web.Services.WebService

...

End Class

Documenting Methods

ASP.NET includes the WebMethod attribute that can be used to add a description to the method that implements your web service method. Here is an example in C#:

[WebMethod(Description = "Look up stock ticker and return the company name.")]
public string LookupTicker(string ticker)
{
...
}

Here is the same example in VB.NET:

<WebMethod(Description = "Look up stock ticker and return the company name.")> _
Public Function LookupTicker(ByVal ticker As String) As String

...

End Function

Documenting Method Arguments using Comment Tags

While there isn't a specific attribute or property for adding comments for method arguments, TechWriter supports the use of comment tags within the method comment for documenting arguments. For example, the JavaDoc param tag can be used to include argument descriptions within the method comments as shown below.

[WebMethod(Description = "Look up stock ticker and return the company name.\n@param ticker The stock ticker to lookup.")]
public string LookupTicker(string ticker)
{
...
}

In order to use comment tags, you must select the proper comment model for your database from the Web Service Settings dialog that is displayed when you add or edit a web service for the project.

Formatting Options

In some instances, you may want to format your comments with multiple paragraphs, lists, links and other formatting options that are available when using TechWriter's Annotation editor. By using one of TechWriter's supported comment models, such as XHTML, you can apply formatting to the text using comment tags. In order to use comment tags you must select the proper comment model for your web service from the Web Service Settings dialog that is displayed when you add or edit a web service for the project.

Using TechWriter

With your comments in place, you are ready to use TechWriter to generate your documentation. After starting TechWriter, add your ASP.NET web service to your project by selecting the WSDL web service type and provide the WSDL URL to your ASP.NET web service. This URL has the following syntax:

http://myserver/myservice/method.aspx?wsdl