Cách tốt nhất để lập tài liệu giao diện WCF là gì?

Question

Vì vậy, tôi đang sử dụng WCF và muốn ghi lại (các) giao diện và dịch vụ của mình để cung cấp cho một công ty khác cho một ứng dụng nội bộ. Cách tốt nhất để ghi lại các giao diện đó là gì? Tôi muốn có tài liệu nội tuyến với mã, và sau đó có một cái gì đó prettify để đầu ra HTML, nhưng tôi không chắc chắn nếu có một cách được đề nghị để làm điều đó.

Answer 1

Sử dụng tài liệu XML cho điều đó. Có rất nhiều thẻ meta thông minh sẽ cho phép bạn đặt mẫu mã vào chúng, tham chiếu giữa các hoạt động, ngoại lệ được ném, v.v.

Sau đó, bạn có thể sử dụng Sandcastle (+ một số GUI bạn có thể tìm thấy trên Codeplex) để tạo chm, hoặc tài liệu html.

Answer 2

Sử dụng đầu ra XML từ trình biên dịch đẹp ... nhưng đó là trải nghiệm của tôi khó thể hiện sự phức tạp hoàn chỉnh của dịch vụ và các biến thể, phụ thuộc, v.v. Bạn nên duy trì một tài liệu thật riêng biệt (Word, HTML, Wiki) để trang trải tất cả.

Answer 3

Tôi sử dụng hai tệp XSL - một tệp để ghi tài liệu WSDL cho các thao tác, một để ghi lại XSD cho dữ liệu được truyền xung quanh. Thật không may, cho đến nay, tôi đã không tìm thấy một giải pháp cố kết duy nhất, vì vậy tôi làm việc với hai tệp XSLT chuyển đổi WSDL và XSD tương ứng thành tài liệu HTML.

WSDL Viewer thực hiện công việc cho WSDL và tạo tài liệu HTML đầu tiên và xs3p thực hiện tương tự cho dữ liệu chứa trong tệp XSD.

Answer 4

Tôi sẽ đặt hợp đồng giao diện của mình vào một dll chung và đưa ra. Nó cung cấp cho cả hai nhận xét xml về hợp đồng mà không cung cấp chi tiết về dịch vụ cũng như cho phép họ triển khai dịch vụ ở chế độ ngoại tuyến để kiểm tra cho đến khi họ sẵn sàng sử dụng nó. Trên hết, họ có thể bỏ qua wsdl và sử dụng ChannelFactory để tạo kênh.

Answer 5

Chúng tôi sử dụng WCFExtras (http://www.codeplex.com/WCFExtras) cho điều đó.

Trong số các tính năng khác nó cho phép xuất khẩu trực tiếp các ý kiến ​​mã xml của bạn vào WSDL được tạo ra, ví dụ như kiểm tra như thế nào những ý kiến ​​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); 

nhận được phản ánh trong WSDL của giao diện mà:

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

Trích đoạn từ tài liệu của họ:

Thêm tài liệu WSDL từ mã nguồn XML Nhận xét Tiện ích mở rộng này cho phép Bạn có thể thêm tài liệu WSDL (chú thích) trực tiếp từ các chú thích XML trong tệp nguồn của bạn. Các nhận xét này sẽ được xuất bản như một phần của WSDL và có sẵn cho các công cụ WSDL biết cách tận dụng chúng (ví dụ: Apache Axis wsdl2java và các công cụ khác). Bản phát hành 2.0 cũng bao gồm một trình nhập khẩu WSDL phía máy khách sẽ biến các nhận xét WSDL đó thành các nhận xét XML trong mã proxy được tạo ra.