Configuration Options for XML Web Services Created Using ASP.NET

Configuration of XML Web services follows the same paradigm used by all ASP.NET Web applications. The ASP.NET configuration is an XML-based text file configuration architecture, which is both powerful and extensible. A configuration file is simply a set of XML elements representing the configuration options for a specific technical feature of the Microsoft .NET Framework. In the case of XML Web services, the configuration options are encapsulated within the webServices XML element of a configuration file. For details on the ASP.NET configuration architecture, see ASP.NET Configuration. For a complete list of the configuration options available to XML Web services, see the <webServices> Element.

Configuring Messaging Protocols and Service Help Page

The messaging protocols and service help page for XML Web services are configurable in the <protocols> XML element beneath the <webServices> Element of configuration files. Configuration is done by adding <add> and <remove> elements for each setting, specifying whether the setting is available for the scope of the configuration file. The <add> element explicitly adds support for that setting for the scope of the configuration file, whereas the <remove> element removes support added higher up in the configuration hierarchy. For instance, a protocol setting can be added at the machine level with an <add> element in the Machine.config file and then removed for a Web application with an <remove> element in a Web.config file. The following is the syntax for the <add> and <remove> elements:

<{addremove} name="protocol name" />

The name attribute of the <add> and <remove> elements has the following options:

Setting	Description
HttpSoap	Controls support of the SOAP over HTTP protocol for XML Web services. Installation adds support by default.
HttpGet	Controls support of the HTTP-GET protocol for XML Web services. Installation does not add support by default.
HttpPost	Controls support of the HTTP-POST protocol for XML Web services regardless of the request origination. Installation does not add support by default.
HttpPostLocalhost	Controls support of the HTTP-POST protocol for XML Web services when the request originates from the local machine. If HttpPost is added to the current configuration, then this setting has no effect. Installation adds support by default.
Documentation	Specifies whether a service help page is displayed when a user navigates to the URL for an XML Web service without any parameters in a browser. Installation adds support by default.

Note The .NET Framework version 1.0 supports the HttpSoap, HttpGet, HttpPost and Documentation settings and all are enabled at the machine level by default.

Security Recommendation

Before enabling the HTTP-GET or HTTP-POST protocols for an XML Web service, you should be aware that doing so could expose it to unintentional invocation. For example, an unsuspecting user could receive an email with a link in it that, when clicked, invokes the XML Web service on behalf of the user using parameters supplied in the email. You should consider whether such unintentional invocations could be harmful before enabling the HTTP-GET or HTTP-POST protocols.

To disable HTTP-GET and HTTP-POST protocols for the whole machine

1. Open the Machine.config file in your favorite text editor. (The default installation places Machine.config in the \Config subdirectory of the installation root.)



2. Comment out the lines within the webServices section that add support for HTTP-GET and HTTP-POST, if they exist. After doing so, the webServices section should look like the following:
   

   <webServices>
       <protocols>
         <add name="HttpSoap"/>
            <!-- <add name="HttpPost"/> --> 
            <!-- <add name="HttpGet"/>  -->
         <add name="Documentation"/>
         <add name="HttpPostLocalhost"/>
       </protocols>
   </webServices>

   
   



3. Save Machine.config.
   

   This configuration change will take effect on the next request to an XML Web service hosted on that machine.
   

To disable support for a protocol for an individual Web application

1. Open the Web.config file in the root directory of the Web application with your favorite editor. (If a Web.config file does not exist, create one.)



2. Modify the webServices section of Web.config to explicitly remove the protocol setting. The following example explicitly removes the HTTP-POST and HTTP-GET protocols:
   

   <webServices>
        <protocols>
          <remove name="HttpPost" />
          <remove name="HttpGet" />
        </protocols>
   </webServices>

   
   



3. Save Web.config.
   

   This configuration change will take effect on the next request to an XML Web service hosted by the Web application.
   

Service Help Page

Navigating to the URL for the XML Web service without any parameters in a Web browser allows a client to view the service help page for the XML Web service, if the service is configured to do so. The service help page contains, by default, human readable information about how to communicate with the XML Web service and the XML Web service methods it exposes. Because the service help page is simply an ASP.NET Web Form, it can be replaced or modified to include items such as a company logo. The file name for the service help page is specified in the <wsdlHelpGenerator> XML element of a configuration file with a default setting of DefaultWsdlHelpGenerator.aspx specified in the Machine.config file. The service help page is only displayed for XML Web services within the scope of a configuration file that have the Documentation protocol specified within the <protocols> XML element. By default, the Documentation protocol is specified in the Machine.config file.

To disable the service help page for an individual Web application

1. Open the Web.config file in the root directory of the Web application with your favorite editor. (If a Web.config file does not exist, create one.)



2. Modify the webServices section of Web.config to explicitly remove the Documentation protocol.
   

   <webServices>
        <protocols>
          <remove name="Documentation" />
        </protocols>
   </webServices>

   
   



3. Save Web.config.
   

   This configuration change will take effect on the next request to an XML Web service hosted by the Web application.
   
   

   
   Note Removing the Documentation protocol also disables WSDL file generation for any XML Web services within the Web application. This prevents clients from generating a proxy class unless a custom WSDL file is created and provided for them. To leave WSDL file generation on for XML Web services within a Web application, but not provide any human readable information regarding the XML Web services, you can add an <wsdlHelpGenerator> element to the Web.config file for the Web application and set the href attribute to a blank HTML page you have created. The following code example is an excerpt of a Web.config file that sets the service help page to a MyBlank.htm file in the docs folder beneath the folder containing the Web.config file.

   
   
   

   <webServices>
      <wsdlHelpGenerator HREF="docs/MyBlank.asp"/>
   </webServices>