How to: Configure the WSE SOAP Router

Article
09/13/2006

There are two basic steps to configure the WSE router:

Configure the WSE router for a Web application to use WSE on the intermediate computer.
Configure a referral cache, which contains the URLs that a SOAP message should be rerouted to on the intermediate computer.

To configure the WSE router for a Web application

For the Web application that is hosting the SOAP router, include one or more <add> Element for <httpHandlers> elements in the <httpHandlers> section of the Web.config file.

Although the <add> Element for <httpHandlers>section that you add to your Web.config file will be nearly identical to the following code example, the path attribute is application configurable. The path attribute controls the set of requests received by ASP.NET that are processed by the WSE router. That is, if an application needs the WSE router to reroute two specific Web services, append two <add> elements to the Web.config file, each specifying exactly one file in the path attribute. This allows client applications to continue to send SOAP requests to one endpoint that may or may not be a SOAP router. That endpoint is configured based on application requirements to optionally reroute the requests to another Web server without updating the client application.

The following table provides example values for the path attribute of the <add> element and indicates which requests are rerouted by the WSE router for each value.

Example value of the path attribute	The WSE router reroutes
webservice22.asmx	Requests for URLs containing the file webservice22.asmx in this Web application.
*webservice.asmx**	Requests for URLs containing files with a webservice prefix and an .asmx extension in this Web application.
*.asmx	All requests for URLs containing files with an .asmx extension in this Web application.

The following code example configures the WSE router to run for all SOAP requests that are received for files with an .asmx extension in this Web application.

<configuration>
    <system.web>
        <httpHandlers>
            <add verb="*" path="*.asmx"
                type="Microsoft.Web.Services3.Messaging.SoapHttpRouter,
                    Microsoft.Web.Services3, Version=3.0.0.0,
                    Culture=neutral,
                    PublicKeyToken=31bf3856ad364e35" />
        </httpHandlers>
    </system.web>
</configuration>

Note

The type attribute of the <add> Element for <httpHandlers> section must be on one line, even though this code example contains line breaks for readability.

Note

All SOAP requests that come in for files with an .asmx extension for this Web application must have an entry in the referral cache; otherwise, a SOAP fault is returned to the client application.

To configure a referral cache

Add a <section> Element element to the <configuration> section for the Web.config file that affects the Web service. This adds the microsoft.web.services3 configuration section handler for this configuration file.

The following code example shows how to add the microsoft.web.services3 configuration section handler.
```
<configuration>
   <configSections>
      <section name="microsoft.web.services3"
               type="Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
   </configSections>
</configuration>
```
Add a <cache> Element for <referral> element to the Web.config file hosting the Web service that specifies the file name for the referral cache.

The WSE router requires that the file containing the referral cache not have the Read-only attribute set and that WSE have read/write access to the file. WSE runs under the account specified in the userName attribute of the <processModel> element in the Machine.config file, unless the router is running in IIS 6. The default installation of the .NET Framework sets the userName attribute to "machine". When the userName attribute is set to "machine", WSE runs under an account named ASPNET. IIS 6 uses application pools to determine the process identity, and the default account a Web service runs under is Network Service. Therefore, the ASPNET or Network Service account must be given read/write permissions to the referral cache file, depending on the operating system the router is running on.

Note

It is strongly recommended that the referral cache be stored in a file with a .config extension. Failure to do so might allow users to retrieve the contents of the referral cache by navigating to the file with a Web browser.

Note

Setting the Access Control List (ACL) on the referral cache file is the responsibility of the system administrator, not WSE. Once the WSE router activates, its referralCache file is locked. Before that, anyone can update the file, unless the ACL set on the file is more restrictive.

The following code example specifies that the referral cache for the Web application affected by the Web.config file is a file named referralCache.config in the root folder of the Web application.
```
<configuration>
    <microsoft.web.services3>
        <referral>
            <cache name="referralCache.config" />
        </referral>
    </microsoft.web.services3>
</configuration>
```
If the referral cache does not exist, an exception is thrown.

Add entries to the referral cache that specify where SOAP requests are rerouted.

The referral cache is an XML document with the following syntax:

<?xml version="1.0" ?>
<r:referrals
    xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
    <r:ref>
        <r:for>
            <r:exact />|<r:prefix />
        </r:for>
        <r:if > 
            <r:ttl />
            <r:invalidates>
                <r:rid />
            </r:invalidates>
        </r:if>
        <r:go>
            <r:via/>
        </r:go>
        <r:refId />
    </r:ref>
</r:referrals>

The following table details the valid XML elements for a referral cache.

Element	Number of occurrences in XML document	Description
<r:referrals>	One.	The root XML element of a referral cache.
<r:ref>	Zero or more.	Specifies a single routing instruction. A routing instruction indicates the URL of an incoming SOAP request and where it should be rerouted.
<r:for>	One per <r:ref> element.	Specifies the incoming SOAP request portion of the routing instruction.
<r:exact>	One <r:exact> or <r:prefix> element per <r:for> element.	Specifies that a case-insensitive exact match on the URI must be made for this routing instruction to be executed.
<r:prefix>	One <r:exact> or <r:prefix> element per <r:for> element.	Specifies that any URI beginning with the contained URI be considered a match for this routing instruction to be executed.
<r:if>	One per <r:ref> element.	Specifies a set of conditions for the routing instruction.
<r:ttl>	One per <r:ref> element.	Specifies how long the routing instruction is valid.
<r:invalidates>	Zero or one per <r:ref> element.	Specifies a routing instruction that is no longer valid when this routing instruction is valid.
<r:rid>	Zero or one per <r:invalidates> element.	The unique identifier of the routing instruction that this routing instruction invalidates.
<r:go>	One per <r:ref> element.	Specifies the rerouting portion of a routing instruction.
<r:via>	One or more per <r:go> element.	Specifies a URI where the SOAP message is rerouted. When there are multiple <r:via> elements, the SOAP request is routed only to the first <r:via> element.
<r:refId>	One per <r:ref> element.	Specifies a unique identifier for the routing instruction. It is recommended that this be a GUID.

Note

When adding referral cache entries, ensure that multiple entries do not apply to SOAP messages targeted for the same destination. When this occurs, WSE re-routes the SOAP message based on only one of the referral cache entries and which one is non-deterministic.

The following code example represents a referral cache that reroutes SOAP requests sent to the https://www.contoso.com/MyWebApplication/SumService.asmx URI to the http://www.cohowinery.com/MyWebApplication/SumService.asmx URL.

<?xml version="1.0" ?>
<r:referrals
    xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
    <r:ref>
        <r:for>
            <r:exact>
                https://www.contoso.com/MyWebApplication/SumService.asmx
            </r:exact>
        </r:for>
        <r:if/>
        <r:go>
            <r:via>
            http://www.cohowinery.com/MyWebApplication/SumService.asmx
            </r:via>
        </r:go>
        <r:refId>uuid:fa469956-0057-4e77-962a-81c5e292f2ae</r:refId>
    </r:ref>
</r:referrals>

To modify an in-use referral cache

Prepare a second referral cache containing the new routing instructions.
Place the second referral cache on the Web server.

Typically, you will place the referral cache in the same folder as the existing referral cache, because you can be more certain that WSE has permission to access that folder. However, it is not required that the referral cache be placed in that folder.
Modify the <cache> Element for <referral> element of the Web.config file hosting the Web service by specifying the file name for the new referral cache.

The next time a SOAP message is received for this Web application, the WSE router will reroute it based on the contents of the new referral cache.

How to: Configure the WSE SOAP Router

To configure the WSE router for a Web application

To configure a referral cache

To modify an in-use referral cache

See Also

Reference

Concepts

Additional resources