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

Question

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

Answer 1

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

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

Answer 2

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

Answer 3

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

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

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

Answer 4

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

Answer 5

Мы используем 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 в сгенерированном прокси-коде.