Подтвердить что ты не робот

Лучший способ документировать интерфейс WCF?

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

4b9b3361

ОТВЕТЫ

Ответ 1

Для этого используйте XML-документы. Существует множество интеллектуальных мета-тегов, которые позволят вам помещать в них образцы кода, ссылки между операциями, заброшенные исключения и т.д.

Затем вы можете использовать Sandcastle (+ некоторый графический интерфейс, который вы можете найти на Codeplex) для создания документации chm или html.

Ответ 2

Мы используем WCFExtras (http://www.codeplex.com/WCFExtras).

Среди других функций он позволяет осуществлять прямой экспорт ваших комментариев XML-кода в сгенерированный WSDL, например, проверить, как эти комментарии xml:

    /// <summary>
    /// Retrieve the tickets information for the specified order
    /// </summary>
    /// <param name="orderId">Order ID</param>
    /// <returns>Tickets data</returns>
    [OperationContract]
    TicketsDto GetTickets(int orderId);

получить отражение в WSDL этого интерфейса:

    <wsdl:operation name="GetTickets">
    <wsdl:documentation>
    <summary> Retrieve the tickets information for the specified order </summary> <param name="orderId">Order ID</param> <returns>Tickets data</returns>
    </wsdl:documentation>
    <wsdl:input wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_InputMessage"/>
    <wsdl:output wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_OutputMessage"/>
    </wsdl:operation>

Отрывок из своих документов:

Добавление документации WSDL из исходного кода XML Комментарии Это расширение позволяет вам добавлять документацию WSDL (annotaiton) непосредственно из комментариев XML в исходном файле. Эти комментарии будут опубликованы как часть WSDL и доступны для инструментов WSDL, которые знают, как их использовать (например, Apache Axis wsdl2java и другие). Версия 2.0 также включает импортер WSDL на стороне клиента, который превратит эти комментарии WSDL в комментарии XML в сгенерированном прокси-коде.

Ответ 3

Я использую два файла XSL - один для документирования WSDL для операций, один для документирования XSD для передаваемых данных.

К сожалению, до сих пор я не нашел ни одного единственного решения, поэтому я работаю с двумя файлами XSLT, которые преобразуют WSDL и XSD соответственно в документацию HTML.

WSDL Viewer выполняет задание для WSDL и создает первый документ HTML и xs3p делает то же самое для данных, содержащихся в файле XSD.

Ответ 4

Использование XML-вывода из компилятора хорош... но мне показалось, что трудно выразить полную сложность службы и ожидаемые инварианты, зависимости и т.д. только в комментариях. Вам лучше поддерживать отдельный реальный документ (Word, HTML, Wiki), чтобы покрыть все это.

Ответ 5

Я поставлю свой контракт на интерфейс в общую dll и передам его. Он дает им как xml-комментарии по контракту без предоставления подробной информации об услуге, так и позволяет им реализовать службу в автономном режиме для тестирования, пока они не будут готовы к ее использованию. Кроме того, они могут обойти wsdl и использовать ChannelFactory для создания канала.