Melhor maneira de interface de documento WCF? [fechadas]

Question

Então, eu estou usando WCF, e deseja documentar minha interface (s) e serviços para dar a outra empresa para uma aplicação interna. Qual é a melhor maneira de documentar essas interfaces? Eu prefiro ter a linha de documentação com o código, e, em seguida, ter algo embelezar a saída HTML, mas não tenho certeza se há uma maneira recomendada para fazê-lo.

Answer 1

Do docs uso de XML para isso. Há uma grande quantidade de meta-tags inteligentes que lhe permitirá colocar amostras de código em si, referências entre as operações, exceções lançadas etc.

Então você pode usar Sandcastle (+ alguns GUI você pode encontrar no Codeplex) para gerar quer chm, ou html documentação.

Answer 2

Nós usamos WCFExtras ( http://www.codeplex.com/WCFExtras ) para isso.

Entre outras características permite ao vivo exportação de seus comentários xml código para o WSDL gerado, por exemplo, verificação de como esses comentários 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);

se reflete no WSDL dessa interface:

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

Um trecho de seus documentos:

Adicionando documentação WSDL a partir do código fonte XML comentários Esta extensão permite que você adicione documentação WSDL (annotaiton) diretamente de comentários XML em seu arquivo de origem. Estes comentários serão publicados como parte do WSDL e estão disponíveis para obter ferramentas WSDL que sabem como tirar proveito delas (por exemplo wsdl2java Apache Axis e outros). Versão 2.0 também inclui um WSDL importador lado do cliente que vai transformar esses comentários WSDL para comentários XML no código proxy gerado.

Answer 3

Eu uso dois arquivos XSL - uma para documentar o WSDL para as operações, uma para documentar o XSD para os dados que estão sendo passados ??ao redor

.

Infelizmente, até agora, eu não encontrei uma única solução coesa, então eu trabalho com arquivos de dois XSLT que transformam o WSDL e o XSD respectivamente na documentação HTML.

WSDL Visualizador faz o trabalho para o WSDL e produz um primeiro documento HTML e xs3p faz o mesmo para os dados contêm no arquivo XSD.

Answer 4

Usando a saída XML do compilador é bom ... mas tem sido minha experiência que é difícil expressar a complexidade completa de um serviço e é invariantes, dependências, etc. Só em comentários esperado. Você é melhor fora de manter um documento verdadeiro separado (Word, HTML, Wiki) para cobrir tudo.

Answer 5

Eu vou colocar o meu contrato de interface em uma dll comum e mão que fora. Dá-lhes ambos os comentários XML no contrato sem dar os detalhes do serviço, bem como o que lhes permite implementar o serviço em modo offline para testar até que esteja pronto para usá-lo. Em cima disso, eles podem ignorar o WSDL e uso ChannelFactory para criar um canal.