Documentazione di servizio WCF

Question

Qual è il modo migliore per documentare/pubblicare informazioni su un servizio WCF in un documento tecnico del prodotto che sia i programmatori che i non programmatori guarderanno? Inoltre, qual è il miglior strumento per la pubblicazione.

Answer 1

Questo è un problema spinoso al meglio! :-)

Si potrebbe esportare il WCF descrizione del servizio in un file WSDL e arricchirla con <xs:documentation> e <xs:annotation> elementi, e poi convertire che a un documento HTML leggibile utilizzando una trasformazione XSLT - ma questo è meno grande e utile, davvero ....

Ecco un link che mostra come fare: http://andrewtokeley.net/archive/2008/10/30/adding-wsdl-documentation-to-your-wcf-services.aspx

Molti degli strumenti XML là fuori offrono anche modi per documentare file WSDL - spesso anche da quelle di documentazione e annotazione tag - un esempio è qui: http://www.oxygenxml.com/doc/ug-oxygen/generate-wsdl-documentation.html

Ecco una versione online (e una trasformazione XSLT scaricabile) per convertire la documentazione e gli elementi di annotazione dal vostro WSDL: http://tomi.vanek.sk/index.php?page=wsdl-viewer

io in realtà non hanno la risposta definitiva qui - ma un avido interesse per l'argomento, pure!

Marc

Answer 2

Date un'occhiata a questa domanda: Best way to document a WCF interface.

Answer 3

C'è un help page che viene generato quando si crea un servizio REST WCF utilizzando WCF REST Starter Kit. Sembra che tu non stia usando REST, ma ho pensato di parlarne perché questo formato potrebbe funzionare bene per te.

Questo utilizza la Descrizione operazione per esporre un Feed Atom delle operazioni.

Un po 'di riflessione alzato questo campione:

public Atom10FeedFormatter GetFeed(ContractDescription contractDescription) 
{ 
    List<SyndicationItem> items = new List<SyndicationItem>(); 
    foreach (OperationDescription od in contractDescription.Description.Operations) 
    { 
     WebGetAttribute get = od.Behaviors.Find<WebGetAttribute>(); 
     WebInvokeAttribute invoke = od.Behaviors.Find<WebInvokeAttribute>(); 
     string method = this.GetMethod(get, invoke); 
     string requestFormat = null; 
     if (invoke != null) 
     { 
      requestFormat = this.GetRequestFormat(invoke, od); 
     } 
     string responseFormat = this.GetResponseFormat(get, invoke, od); 
     string uriTemplate = this.GetUriTemplate(get, invoke, od); 
     WebMessageBodyStyle bodyStyle = this.GetBodyStyle(get, invoke); 
     string requestSchemaLink = null; 
     string responseSchemaLink = null; 
     string requestExampleLink = null; 
     string responseExampleLink = null; 
     if (bodyStyle == WebMessageBodyStyle.Bare) 
     { 
      UriTemplate responseSchemaTemplate = new UriTemplate("help/{operation}/response/schema"); 
      responseSchemaLink = responseSchemaTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
      UriTemplate responseExampleTemplate = new UriTemplate("help/{operation}/response/example"); 
      responseExampleLink = responseExampleTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
      if (invoke != null) 
      { 
       UriTemplate requestSchemaTemplate = new UriTemplate("help/{operation}/request/schema"); 
       requestSchemaLink = requestSchemaTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
       UriTemplate requestExampleTemplate = new UriTemplate("help/{operation}/request/example"); 
       requestExampleLink = requestExampleTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
      } 
     } 
     uriTemplate = HttpUtility.HtmlEncode(string.Format("{0}/{1}", this.BaseUri.AbsoluteUri, uriTemplate)); 
     string xhtmlDescription = string.Format("<div xmlns=\"http://www.w3.org/1999/xhtml\"><table border=\"5\"><tr><td>UriTemplate</td><td>{0}</td></tr><tr><td>Method</td><td>{1}</td></tr>", uriTemplate, method); 
     if (!string.IsNullOrEmpty(requestFormat)) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Request Format</td><td>{0}</td></tr>", requestFormat); 
     } 
     if (requestSchemaLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Request Schema</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(requestSchemaLink)); 
     } 
     if (requestExampleLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Request Example</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(requestExampleLink)); 
     } 
     xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Response Format</td><td>{0}</td></tr>", responseFormat); 
     if (responseSchemaLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Response Schema</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(responseSchemaLink)); 
     } 
     if (responseExampleLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Response Example</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(responseExampleLink)); 
     } 
     WebHelpAttribute help = od.Behaviors.Find<WebHelpAttribute>(); 
     if ((help != null) && !string.IsNullOrEmpty(help.Comment)) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Description</td><td>{0}</td></tr>", help.Comment); 
     } 
     xhtmlDescription = xhtmlDescription + "</table></div>"; 
     var item = new SyndicationItem() { 
      Id = "http://tmpuri.org/" + od.Name, 
      Content = new TextSyndicationContent(xhtmlDescription, TextSyndicationContentKind.XHtml), 
      LastUpdatedTime = DateTime.UtcNow, 
      Title = new TextSyndicationContent(string.Format("{0}: {1}", this.Description.Name, od.Name)) 
     }; 
     items.Add(item); 
    } 
    SyndicationFeed feed = new SyndicationFeed() 
    { 
     Title = new TextSyndicationContent("Service help page"), 
     LastUpdatedTime = DateTime.UtcNow, 
     Items = items 
    }; 
    WebOperationContext.Current.OutgoingResponse.ContentType = "application/atom+xml"; 
    return feed.GetAtom10Formatter(); 
}