Сервисная документация WCF

Как лучше всего документировать /публиковать информацию о службе WCF в техническом документе продукта, на который будут смотреть как программисты, так и непрограммисты? Кроме того, что является лучшим инструментом для публикации.

wcf
7 голосов | спросил Susan James 14 Maypm09 2009, 23:35:27

3 ответа


0

В лучшем случае это сложная проблема! : -)

Вы можете экспортировать описание своей службы WCF в файл WSDL и дополнить его <xs:documentation> и <xs:annotation>, а затем преобразуйте его в читаемый HTML-документ с помощью преобразования XSLT - но это не так здорово и полезно, на самом деле ....

Вот ссылка, которая показывает, как это сделать: http: //andrewtokeley. сеть /архив /2008/10/30 /добавление-WSDL-документации к вашей-ФОС-services.aspx

Некоторые из инструментов XML также предлагают способы документирования файлов WSDL - часто также с помощью этих тегов документации и аннотаций - один пример здесь: http://www.oxygenxml.com/doc/ug-oxygen/generate-wsdl-documentation.html

Вот онлайн-версия (и загружаемое XSLT-преобразование) для преобразования элементов документации и аннотаций из вашего WSDL: http://tomi.vanek.sk/index.php?page=wsdl-viewer

У меня нет окончательного ответа здесь - но страстный интерес к теме тоже!

Марк

ответил marc_s 14 Maypm09 2009, 23:40:04
0
ответил Paul Alexander 14 Maypm09 2009, 23:46:10
0

Существует страница справки , которая создается при создании Служба REST WCF с использованием Стартовый комплект REST WCF . Похоже, вы не используете REST, но я подумал, что упомяну об этом, потому что этот формат может вам подойти.

При этом используется описание операции, чтобы представить Atom Feed операций.

Небольшое отражение подняло этот пример:

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();
}
ответил bendewey 14 Maypm09 2009, 23:54:31

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132