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 WCF by using WCF Extras to leverage the XML comments within your WCF source code.  WCF Extras is a free set of extensions for WCF that can be found at http://wcfextras.codeplex.com/.

Documenting WCF Services

WCF Extras includes the XmlComments attribute that you must add to your service contract. Here is an example in C#:

/// /// <summary>Service for getting a stock quote.</summary> /// [XmlComments] [ServiceContract] public interface IStockQuote {     ... }

 

By adding this attribute to your service contract, XML comments from your source code will be added to WSDL documentation tags that are processed by TechWriter.

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#:

/// /// <summary>Look up stock ticker and return the company name.</summary> /// <param name="ticker">The stock ticker to lookup</param> /// <returns>The name of the stock</returns> public string LookupTicker(string ticker) {     ... }

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 taking advantage of TechWriter's support for comment models, you can apply formatting to the text using XML comment tags.  In order to use comment tags you must select the XML comments 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.

Configuring your WCF Service

Before you can use TechWriter to generate your documentation, you must configure your WCF service so that it can generate a WSDL.  To enable WSDL support you have to add a serviceMetadata behavior to your config file:

<serviceBehaviors>
  <behavior name="myServiceBehaviour">
    <serviceMetadata httpGetEnabled="true" />
  </behavior>
</serviceBehaviors>

Using TechWriter

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

 

http://myserver/myservice.svc?wsdl

 

 

 

---

© 2005-2009 Adivo Ltd. All rights reserved.