डब्ल्यूसीएफ इंटरफेस दस्तावेज करने का सबसे अच्छा तरीका?

Question

तो मैं डब्ल्यूसीएफ का उपयोग कर रहा हूं, और एक आंतरिक ऐप के लिए किसी अन्य कंपनी को देने के लिए अपने इंटरफेस और सेवाओं को दस्तावेज करना चाहता हूं। उन इंटरफेस को दस्तावेज करने का सबसे अच्छा तरीका क्या है? मैं कोड के साथ दस्तावेज इनलाइन करना पसंद करूंगा, और फिर HTML आउटपुट करने के लिए कुछ सुंदरता प्राप्त करूँगा, लेकिन मुझे यकीन नहीं है कि ऐसा करने के लिए कोई अनुशंसित तरीका है या नहीं।

Answer 1

इसके लिए एक्सएमएल दस्तावेज़ का उपयोग करें। बहुत सारे स्मार्ट मेटा टैग हैं जो आपको कोड नमूने, ऑपरेशन, फेंकने वाले अपवाद आदि के संदर्भों को संदर्भित करने की अनुमति देंगे।

फिर आप Sandcastle (+ कुछ GUI जिसे आप कोडेप्लेक्स पर पा सकते हैं) का उपयोग कर सकते हैं ताकि उत्पन्न हो सके सीएम, या एचटीएमएल दस्तावेज।

Answer 2

कंपाइलर से एक्सएमएल आउटपुट का उपयोग करना अच्छा है ... लेकिन यह मेरा अनुभव रहा है कि सेवा की पूरी जटिलता को व्यक्त करना मुश्किल है और यह अकेले टिप्पणियों में आविष्कार, निर्भरता आदि की उम्मीद है। आप इसे कवर करने के लिए एक अलग वास्तविक दस्तावेज़ (शब्द, एचटीएमएल, विकी) को बनाए रखने से बेहतर हैं।

Answer 3

मैं दो एक्सएसएल फाइलों का उपयोग करता हूं - एक ऑपरेशन के लिए डब्ल्यूएसडीएल दस्तावेज करने के लिए, एक डेटा को पास करने के लिए एक्सएसडी दस्तावेज करने के लिए।

दुर्भाग्यवश, मुझे एक एकल संयोग समाधान नहीं मिला है, इसलिए मैं दो एक्सएसएलटी फाइलों के साथ काम करता हूं जो क्रमशः डब्लूएसडीएल और एक्सएसडी को एचटीएमएल दस्तावेज में परिवर्तित करते हैं।

WSDL Viewer डब्लूएसडीएल के लिए नौकरी करता है और पहला HTML दस्तावेज़ बनाता है, और xs3p एक्सएसडी फ़ाइल में मौजूद डेटा के लिए समान होता है।

Answer 4

मैं अपना इंटरफ़ेस अनुबंध एक सामान्य डीएल में रखूंगा और इसे बाहर कर दूंगा। यह उन्हें सेवा के ब्योरे दिए बिना अनुबंध पर एक्सएमएल टिप्पणियां देता है और साथ ही उन्हें ऑफ़लाइन मोड में सेवा को लागू करने की इजाजत देता है जब तक कि वे इसका उपयोग करने के लिए तैयार न हों। इसके शीर्ष पर, वे wsdl को बाईपास कर सकते हैं और चैनल बनाने के लिए चैनलफैक्टरी का उपयोग कर सकते हैं।

Answer 5

हम इसके लिए WCFExtras (http://www.codeplex.com/WCFExtras) का उपयोग करते हैं।

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

:

/// <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); 

कि इंटरफ़ेस का डबल्यूएसडीएल में परिलक्षित हो:

अन्य सुविधाओं में यह उदाहरण के लिए जाँच कैसे इन एक्सएमएल टिप्पणियां उत्पन्न डबल्यूएसडीएल में अपने कोड एक्सएमएल टिप्पणियों के लाइव निर्यात की अनुमति देता है,

उनके दस्तावेज़ों से एक अंश:

स्रोत कोड से डब्लूएसडीएल दस्तावेज़ीकरण जोड़ना XML टिप्पणियां यह एक्सटेंशन अनुमति देता है क्या आप अपनी स्रोत फ़ाइल में एक्सएमएल टिप्पणियों से सीधे डब्लूएसडीएल दस्तावेज (एनोटैटन) जोड़ना चाहते हैं। ये टिप्पणियां डब्लूएसडीएल के हिस्से के रूप में प्रकाशित की जाएंगी और डब्लूएसडीएल उपकरणों के लिए उपलब्ध हैं जो जानते हैं कि उनका लाभ कैसे लें (उदा। अपाचे एक्सिस wsdl2java और अन्य)। रिलीज 2.0 में क्लाइंट साइड डब्लूएसडीएल आयातक भी शामिल है जो उत्पन्न डब्लूएसडीएल टिप्पणियों को जेनरेट प्रॉक्सी कोड में एक्सएमएल टिप्पणियों में बदल देगा।