I'm using the xml comments to help users use my web service easier, but when I test the service in a seperate project, none of the xml documentation pops up to help the user in intellisense.
Can this be done in web services? I'm using the typical built-in comments:
There are (2) things you need to do to have the XML comments appear in the intellisense:
Make sure XML Documentation is turned on in the project properties. Then use the /// (C#) or ''' (VB.NET) notation to auto generate the XML comment block right before the class, method, or property.
The XML file that is generated in the /bin of the project must be deployed with the project and be the
same name as the assembly but .xml instead of .dll. The file needs to be in the same directory as the assembly and if VS.NET locates it, the Intellisense will parse the file and show the XML comments.
A couple of things: My project is a WEb Site project with web service files in it. I don't see an 'xml documentation file' option, and it doesn't build the documentation to a dll since it is code-and-continue.
Secondly, just to be clear, I'm talking about seeing intellisense XML doucumentation when CONSUMING the web service, in someone else's application, not from within the application I'm using.
1) Place the class files you want to get XML documents generated for in a
"Class Library" project and then reference that project from you website.
2) The second option, which might be a better option if you want to
generate XML documentation for code-behind files for pages, in addition to
classes, is to use the Web Application Project instead of a Website
project. Web Application projects.
Walkthrough: Converting a Web Site Project to a Web Application Project in Visual Studio:
I'm talking about seeing intellisense XML doucumentation when CONSUMING the web service, in someone else's application
I understood this, and the links provided do speak of how this should be possible. However a couple of things about this:
When a web service is consumed the proxy classes are generated using the wsdl.exe tool behind the scenes (from selecting 'Add Web Reference...). I am not sure of a
speceifc way to tell the the wsdl.exe tool to being that .xml file down to the client's consuming application. There may be a switch for the tool, but I am not sure if this is possible.
http://msdn.microsoft.com/en-us/library/7h3ystb6.aspx
Not to divert to much, but really the intenntion of what you are trying to do or want to do has been satisfied through the .asmx web service's 'wsdl' file. If you have not looked at it before, paste the .asmx url in any browser and you will get a nice
screen displaying all of the web methods and their descriptions. It would be nice to have in the Intellisense, but if you can't get this option working, you may want to revert to the wsdl.
You can have a look at using this codeplex plugin. One of its features is that you can add the XML comments into the WSDL. If you're feeling adventurous, you can also implement the
IWsdlExportExtension interface.
I've updated my project to be a web application and included an xml documentation file in the bin, but still no comments when I test the service from another instance of visual studio :(... I'm starting wonder if this is even possible? Perhaps VS doesn't
include the documentation when it builds the WSDL?
It doesn't, the class library XML comments are only for when you directly reference the class and use it. It's more of a .NET feature rather than a web service feature. Web services get serialized as XML, so only the important bits of any class make it
across. Logic and XML comments don't need to go, so they don't. Did you look at the codeplex plugin I showed you?
Yeah thanks I was thinking it might be possible but your explanation makes sense. I also looked into CodePlex sample and yes its an addin. Visual Studio does not include comments itself, but if you are really enthusiastic, just add that
plugin and don't forget to read "How to you use" at the end.
bbaxter
Member
148 Points
442 Posts
XML comments in web services
Sep 22, 2009 10:23 PM|LINK
I'm using the xml comments to help users use my web service easier, but when I test the service in a seperate project, none of the xml documentation pops up to help the user in intellisense.
Can this be done in web services? I'm using the typical built-in comments:
///<summary>
///<param>
etc...
atconway
All-Star
16846 Points
2756 Posts
Re: XML comments in web services
Sep 23, 2009 02:46 AM|LINK
There are (2) things you need to do to have the XML comments appear in the intellisense:
http://bytes.com/topic/c-sharp/answers/245290-xml-comments-not-showing-up-intellisense
http://dotnet.mvps.org/dotnet/faqs/?id=tooltipsxmldocumentation
Hope this helps!
bbaxter
Member
148 Points
442 Posts
Re: XML comments in web services
Sep 23, 2009 05:00 PM|LINK
A couple of things: My project is a WEb Site project with web service files in it. I don't see an 'xml documentation file' option, and it doesn't build the documentation to a dll since it is code-and-continue.
Secondly, just to be clear, I'm talking about seeing intellisense XML doucumentation when CONSUMING the web service, in someone else's application, not from within the application I'm using.
atconway
All-Star
16846 Points
2756 Posts
Re: XML comments in web services
Sep 23, 2009 06:21 PM|LINK
Yes that can be a problem. Here is the main response from the following link: http://www.velocityreviews.com/forums/t122236-xml-documentation-in-aspnet-web-sites.html
There are two ways to approach the current issue:
1) Place the class files you want to get XML documents generated for in a
"Class Library" project and then reference that project from you website.
2) The second option, which might be a better option if you want to
generate XML documentation for code-behind files for pages, in addition to
classes, is to use the Web Application Project instead of a Website
project. Web Application projects.
Walkthrough: Converting a Web Site Project to a Web Application Project in Visual Studio:
http://msdn.microsoft.com/en-us/library/aa983476.aspx
I understood this, and the links provided do speak of how this should be possible. However a couple of things about this:
mendhak
All-Star
17868 Points
2787 Posts
Re: XML comments in web services
Sep 23, 2009 09:15 PM|LINK
You can have a look at using this codeplex plugin. One of its features is that you can add the XML comments into the WSDL. If you're feeling adventurous, you can also implement the IWsdlExportExtension interface.
bbaxter
Member
148 Points
442 Posts
Re: XML comments in web services
Sep 24, 2009 08:55 PM|LINK
I've updated my project to be a web application and included an xml documentation file in the bin, but still no comments when I test the service from another instance of visual studio :(... I'm starting wonder if this is even possible? Perhaps VS doesn't include the documentation when it builds the WSDL?
mendhak
All-Star
17868 Points
2787 Posts
Re: XML comments in web services
Sep 25, 2009 07:10 AM|LINK
It doesn't, the class library XML comments are only for when you directly reference the class and use it. It's more of a .NET feature rather than a web service feature. Web services get serialized as XML, so only the important bits of any class make it across. Logic and XML comments don't need to go, so they don't. Did you look at the codeplex plugin I showed you?
fwd79
Member
10 Points
7 Posts
Re: XML comments in web services
Jan 15, 2010 01:42 PM|LINK
Yeah thanks I was thinking it might be possible but your explanation makes sense. I also looked into CodePlex sample and yes its an addin. Visual Studio does not include comments itself, but if you are really enthusiastic, just add that plugin and don't forget to read "How to you use" at the end.
Well here is the link again:
http://wcfextras.codeplex.com/
Regards.
Carlos Hass
Member
2 Points
1 Post
Re: XML comments in web services
Feb 27, 2013 06:13 PM|LINK
Hello !
You can say if, with use of WCFExtras, the xml documentation pops up to help the user in intellisense ??
Are you using VS2012?
REgards,
CArlos Hass