.NET should move documentation from the WSDL to the generated code

[Sebastien Tardif]

When I have a WSDL that is documented like:
<?xml version="1.0" encoding="UTF-8"?>
<!-- edited by Sebastien Tardif (Anacomp) -->
<wsdl:definitions xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" ...
<complexType name="Credential">
<xsd:annotation>
<xsd:documentation xml:lang="en">Holds username and password for
authentication.</xsd:documentation>
</xsd:annotation>
<sequence>
<element name="username" nillable="false" type="xsd:string"/>
...

The class Credential generated should have for comment what is inside
document. Right now I just see warning message like:
// CODEGEN: The optional WSDL extension element 'annotation' from namespace
'http://www.w3.org/2001/XMLSchema' was not handled.

 

[Kevin Yu [MSFT]]

Hi

We have reviewed this issue and are currently researching on it. We will
update you ASAP. Thanks for your patience!

Kevin Yu
=======
"This posting is provided "AS IS" with no warranties, and confers no
rights."

 

[Steven Cheng[MSFT]]

Hi ,

Thanks for your posting. Regarding on the problem you mentioned, I 've also
done the test and do find the problem you mentioned. I think this is due to
the wsdl.exe generate tool is omitting these annotation elements when
parsing the wsdl document. Also, seems most of the webservice client proxy
generation tools haven't provide a strong enough mechanism for generating
webservice comments in client proxy's code. Anyway, I'll also pass this
message to the dev team to see whether there is any other approachs or new
action plan on such functionality. I'll let you know if I got any new
updates. Thanks for your understanding.

Regards,

Steven Cheng
Microsoft Online Support

Get Secure! www.microsoft.com/security
(This posting is provided "AS IS", with no warranties, and confers no
rights.)

 

[Steven Cheng[MSFT]]

Hi Sebastien,

After some further consulting, it seems that Out source code generation
tools (xsd.exe, wsdl.exe) do not process the annotations in schema or wsdl
documents.
We can use WebMethod and WebService attribute Description property to add
documentation elements to wsdl, but those tools still won't process them
when generating proxy code.
Thanks.

Steven Cheng
Microsoft Online Support

Get Secure! www.microsoft.com/security
(This posting is provided "AS IS", with no warranties, and confers no
rights.)

 

[AndyMalakov]

Hi Steven,

It would be useful to see WSDL/XSD documentation propagated to
generated proxies and data objects. In our case we have large number
of XSD types defined and documented in WSDL, and stripping
documentation from generated files will require all our .NET clients to
learn WSDL/XSD.

 

[Steven Cheng[MSFT]]

Thanks for your feedback Andy,

I'll also forward such requirement to our webservice guys. Hope the
tools'll become more and more powerful.

Regards,

Steven Cheng
Microsoft Online Support

Get Secure! www.microsoft.com/security
(This posting is provided "AS IS", with no warranties, and confers no
rights.)