WebService Documentation: Using a custom template
Web Services: they are an easy way to make information accessible or use information from some other site. For example, weather.gov's wsdl. The beauty of web services is that not all web services are .net and we don't have to care. Any web service that adheres to the w3's standards and that provides a wsdl we can easily use in asp.net. In order to help people understand how to consume the service; asp.net even gives us a nice page of generated documentation when someone opens the asmx in their browser.
I, for one, hate that page. If I have gone to all the trouble of building a WebService for someone to submit data or request information, why would I want to send them to a page that looks nothing like the rest of my site to learn how to use it? At the very least brand it in a way that identifies my company. But no, the sad state is such that the generate page is fixed and only by adding a theme to the page section in a web.config can you get it to use a custom style sheet or theme.
So what are we to do? Replace it! That's right, we can replace it. The first thing we need is, a web service of course.
I've cracked open the ObjectHelpDesk solution and added a new folder, "help". I have added a new WebService "help-desk" in the help folder. I moved the code-behind into a dll and edited the asmx accordingly.
I left HelloWorld in place and added EchoHelloWorld. Do not forget to but the WebMethod tag on EchoHelloWorld; otherwise the method will not be available in the web service.
Now we can browse out to the site and see how it looks. If you added comments to the code you might be thinking, "It would be a vast improvement if my comments listed under the methods."
I agree, and we can come close; by editing the WebMethod attribute tag, above the methods, we can add a basic description to the default documentation page. We are going to replace the default page; but we are also going to be using its "guts" as the base of our new page. Because turning off the custom WebService documentation page is as easy as editing one line in the web.config it is important to make sure everything is in order. There is also a description property on the WebService tag that can be set as well.
[WebMethod(Description="Echos back the passed in string")]
public string EchoHelloWorld(string echoMessage)
{
return "Hello World " + echoMessage;
}
(don't forget to set a description for the WebService)
[WebService(Namespace = http://www.JeffGaroutte.net/,
Description="This web service is currently used for testing.")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[ToolboxItem(false)]
public class help_desk : System.Web.Services.WebService
Browse out to C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG and look for DefaultWsdlHelpGenerator.aspx. Copy the file into your project and rename it. I renamed mine to WsdlTemplate.aspx and placed it in the "help" folder with the asmx. Tip: Do not delete, remove, edit or rename the original DefaultWsdlHelpGenerator.aspx file. Sites that do not have a custom template specified in the web.config will need the file. If for some reason you need to turn off the custom template will will still need the file.
Edit the web.config and add a webServices section.
Notice the href; it looks like a relative path. If the href starts with ~/ or / asp.net will throw a 404 error. You can also add a protocols section to the webServices to remove the "documentation" feature entirely. This is an excellent idea if the WebService is not meant to be open to general public use. For "security reasons" the HttpPost and HttpGet protocols methods are disabled for any request that is not from the localhost.
Now you can edit your WsdlTemplate.aspx page and change to your hearts content. However, the page must be dymancily complied. I tried moving the huge code block out into a code behind and found that asp.net did not like it. I believe this is due to the way the rendered page is generated from the template inside of the framework.
Happy Coding!
