Peterson's Ponderings

Technical findings, ideas, thoughts and news directly from me.
in

July 2007 - Posts

Customize the Default Web Service Help Page

Most .NET developers that write web services are familiar with the default test page that appears when you navigate to the asmx page in a web browser.  This page is installed with Visual Studio and allows a developer to test posting data to web service methods as long as the web service is only using simple type parameters.  If the web service is more complicated with complex types (serialized classes from your code) the default test page is of no help.  But alas, it can be utilized for testing if you customize it!

I've made a customized landing page that shows examples of the raw SOAP XML message request and response.  It also allows the user to fill in values for the XML elements as SOAP parameters for simple or complex types and post them directly to the service which then displays the raw SOAP XML response.  This is the best way for testing that the XML output of a web service method is being produced the way you expect it to be and involves no complex port sniffing or extra tool installation.  It's also a quick way (no coding involved) to test posting different types of input values and how the service responds to them.  You can find my customized landing page here.  The code essentially reads the wsdl information of the web service to generate the compliant XML of a SOAP message for every method defined in the service.  This customized page also supports web services that import from a static wsdl file (which a web site can be configured to do in the case where you want to override the wsdl .NET creates when hitting the .asmx?wsdl url of the web service page).

There are two ways you can set up a customized asmx default page.  The first is to replace the main copy that is in effect for all web services on the server and can be found at c:\windows\microsoft.net\framework\v2.0.50727\config\DefaultWsdlHelpGenerator.aspx

Essentially the asmx handler is forwarding all non-SOAP http requests to the help generator aspx page to display a user friendly landing page.  If you want all your sites to utilize the same test page then replace the DefaultWsdlHelpGenerator.aspx page with your own version.  Be sure to retain the same file name though.  (This works as well for the .NET 1.1 framework, just replace the v2.0.50727 folder with v1.1.4322 in the above path.)

If you want just a particular site to use a customized page then add a web.config entry to the web site to point to the location of the desired page.  This overrides the usage of the page found in the windows directory listed above.  An example web.config settings to make the default page point to a page in my current web site would be:

<system.web>

<webServices><wsdlHelpGenerator href="MyWsdlHelpPage.aspx" /></webServices>

</system.web>

Since the help generator page is just an aspx page you can feel free to make any web changes you'd like including branding to match an associated site.  The page does not have to include the ability to submit data to the web service allowing you to conceal that ability from any user that happens to land on the page.