Configuring Web Methods

A quick recap, then: We’ve built our Web service and given it two Web methods. We’ve looked at the WSDL document created automatically as part of the Web service. The content of the WSDL document depends partly on what happens within the Web method itself. However, the Web method isn’t the only object that can affect the contents of the WSDL document. It’s also possible to alter how the Web service and Web method work via the configuration files.

One major new feature in the .NET Framework was the XML configuration files, which store configuration information pertinent to both the .NET Framework and ASP.NET. You can use these configuration files to manage certain aspects of Web methods. Two main configuration files are used in .NET:

• Machine.config, which is used to configure information for the server and is used throughout all of your applications. It is the file from which all other configuration files can inherit their settings. It can be found at \Windows\Microsoft.Net\Framework\version\Config.

• Web.config, which is used to control application-specific information and should be found in the virtual root directory of the Web application. There might be more than one web.config file per application, with one file overriding another web.config file’s settings, along with any conflicting settings within the machine.config file. Web.config files apply configuration settings to all child directories unless other web.config files are beneath them.

The configuration files are simple XML files that allow alteration of the IIS metabase via various tags.

The Machine.config File

Machine.config is where a lot of the ASP.NET service’s functionality is enabled or disabled. This file allows you to take care of a number of tasks, from the setting of permissions in IIS to the enabling of protocols for use by Web services. There is a single version of machine.config for each version of ASP.NET that has been installed, to ensure some backward compatibility with future versions. All ASP.NET applications use this file for default properties and behaviors.

We’re interested in the behaviors of this file that affect Web services, so it makes sense to focus on the <webServices> element and the sections it supports.

Protocols

If you look under the <webServices> element in your machine.config file, you’ll see a list of the protocols that .asmx files support:

<webServices>   <protocols>       <add name="HttpSoap1.2"/>     <add name="HttpSoap"/>     <!-- <add name="HttpPost"/> -->     <!-- <add name="HttpGet"/> -->     <add name="Documentation"/>    </protocols>   ⋮ </webServices>

In .NET 1.1, only one protocol is supported by default. You can add others by changing the add element as follows:

<webServices>   <protocols>       <remove name="HttpSoap1.2"/>     <add name="HttpSoap"/>     <add name="HttpPost"/>     <add name="HttpGet"/>     <add name="Documentation"/>   </protocols>   ⋮ </webServices>

This action adds support for the HTTP-POST and HTTP-GET protocols for the whole server. You can remove support for any protocol by using the <remove> element and using the name attribute to specify the name of the protocol you want to remove.

Documentation

In addition to the three protocols, there is also a documentation protocol. It allows you to customize the documentation page that appears when you navigate to an .asmx endpoint. You can change it by means of the <wsdlHelpGenerator> element under the <webServices> element:

<webServices>   ⋮   <wsdlHelpGenerator href="defaultWsdlHelpGenerator.aspx" /> 

This element displays the HTML documentation. When you run a Web service, you see the test page by default, and the href attribute will default to indicate a local file called defaultWsdlHelpGenerator.aspx. If we run this page without altering it for our RecordStore test service, we’ll see the page shown earlier, in Figure 7-1, in the section “The Example Web Methods.”

By changing the setting in machine.config, you can substitute this page for your own page or an upgraded version of the defaultWsdlHelpGenerator.aspx page.

In addition to the protocols element, in the machine.config file you will also find the soapExtensionTypes, soapExtensionReflectorTypes, soapExtensionImporterTypes, and serviceDescriptionFormatExtensionTypes elements. These elements are used to register SOAP extensions, reflectors, and importers for use in the WSDL generation and proxy-client generation processes. These elements are poorly documented, but you can use them to add custom attributes to Web methods and provide access to these custom attributes on the client. For example, you can use them to add security attributes to import other XML schemas, such as the XML-Encryption and XML-Signature documents to help with proper authentication. The MSDN documentation specifies that these properties are not to be used by developers directly from code and should be left empty, but this isn’t entirely accurate because they do provide useful functionality.

The Web.config File

You can use the web.config file to modify settings from machine.config or to extend and define its own settings. The web.config file is commonly used to override settings from machine.config or other web.config files; it has an element you can use within the <protocols> element to wipe the protocol information specified in parent configuration files.

The <clear /> tag clears all settings inherited from a machine.config or web.config file. You can place this element at the head of the file and then add any protocol definitions after it, as in this example:

<webServices>   <protocols>       <clear />      <add name="SOAP"/> 

It is a good idea to use the <clear /> element because by default your Web service might be using the HTTP-POST and HTTP-GET protocols to transmit your Web service as well as SOAP, and this might not only affect the performance of your Web service but also make it more insecure. Also, for reasons of interoperability, it might be preferable to just use SOAP because SOAP is the standard protocol for Web service transfer and HTTP- POST and HTTP-GET are not.

You can also use the web.config file to enable debugging, by setting the compilation tag’s debug attribute to true. You do this within the <system.web> tag as follows:

<configuration>   <system.web>     <compilation debug="true"/>   </system.web> </configuration>

Another setting of interest in the web.config file is the appSettings tag. This tag allows the addition of custom application data, such as DSN details or information to enable Active Directory settings. You can add custom application data by using an add tag within the AppSettings tag, which takes key and value attributes:

<configuration>   <appSettings>     <add key="key" value="value" />   </appSettings> </configuration>

You can use the appSettings tag to dynamically specify the URL of a Web service at run time. This might be useful if you’ve tested a Web service on your own machine and need to change the name to deploy it on a client’s server or if you have several versions of a Web service and you want the user to be able to choose among them.

Important

You can also access the files you add to the appSettings element programmatically via a shortcut, by including the System.Configuration namespace and then specifying the following:

string example; example = ConfigurationSettings.AppSettings["URL"];

To dynamically specify the URL of a Web service, you have to jump through a few hoops. First you have to change the URL Behavior setting for the Web service from Static to Dynamic. To do so, you select the Web reference in Solution Explorer and then change the setting for URL Behavior in the Properties pane. This adds an appSetting entry to the app.config file in this fashion:

<appSettings>   <add key="WebApp.localhost.Service1"      value="http://localhost/wscr/07/RecordStore/Service1.asmx/"> </appSettings>

Next you must create an installer class that will override the install method of the class and modify the web.config file itself. This installer class must log the installation and locate the correct web.config file, which will then be added to the project as a custom action. (Custom actions are the actions requested by code that couldn’t be performed during installation.) You must create a project that includes the installer class and a dialog box that allows users to dynamically select the location of the Web service they want to run.

Generally, altering the .config files that affect Web methods isn’t a big issue, but it does alter the contents of the WSDL document, too.

Now let’s look at the other way to alter Web services—via attributes.