How To: Error Handling

Article
09/15/2021

This topic outlines the basic steps required to create a routing configuration that uses error handling. In this example, messages are routed to a destination endpoint. If a message cannot be delivered due to a network or communications-related failure (CommunicationException), the message is resent to an alternate endpoint.

Note

To simulate a network failure, the destination endpoint used in this example contains an incorrect address. Messages routed to this endpoint fail as no service is listening on the specified address.

Note

While the example contained in this topic does not explicitly discuss time-out settings, you must take these into consideration when using error handling. When errors are encountered, there will be an additional delay encountered before the client receives a response. This is because the error is received at the Routing Service, which then attempts to send the message to a backup endpoint. If the time-out values associated with the primary and backup destination endpoints are large, the client could experience a long delay as the message fails over multiple endpoints in the backup list before being successfully sent.

Since the Routing Service could encounter a maximum delay equal to the sum of the time-out value for all endpoints associated with a filter, we recommend that you increase the expected time-out at the client accordingly.

Implement Error Handling

Create the basic Routing Service configuration by specifying the service endpoint exposed by the service. The following example defines a single service endpoint, which is used to receive messages. It also defines the client endpoints that are used to send messages; deadDestination and realDestination. The deadDestination endpoint contains an address that does not reference a running service and is used to simulate a network failure when sending messages to this endpoint.

<services>
  <service behaviorConfiguration="routingConfiguration"
           name="System.ServiceModel.Routing.RoutingService">
    <host>
      <baseAddresses>
        <add baseAddress="http://localhost/routingservice/" />
      </baseAddresses>
    </host>
    <!-- Create the Routing Service endpoint -->
    <endpoint address="router"
              binding="basicHttpBinding"
              name="RoutingServiceEndpoint"
              contract="System.ServiceModel.Routing.IRequestReplyRouter" />
  </service>
</services>

<!-- Create the destination endpoints that we want to send to -->
<client>
  <!-- Create a dummy endpoint that we know will be down -->
  <endpoint name="deadDestination"
            address="net.tcp://localhost:9090/servicemodelsamples/fakeDestination"
            binding="netTcpBinding"
            contract="*" />

  <!-- Now create the real service endpoint -->
  <endpoint name="realDestination"
            address="net.tcp://localhost:8080/servicemodelsamples/service"
            binding="netTcpBinding"
            contract="*" />
</client>

Define the filters used to route messages to the destination endpoints. For this example, a MatchAll filter is used to match all messages received by the Routing Service.
```
<filters>
  
  <filter name="MatchAllFilter1" filterType="MatchAll" />
</filters>
```
Define the backup endpoint list, which contains the endpoints that a message is sent to in the event of a network or communications failure when sending to the primary destination endpoint. The following example defines a backup list that contains one endpoint; however, multiple endpoints can be specified in a backup list.

If the backup list contains multiple endpoints, when a network or communications failure occurs the Routing Service attempts to send the message to the first endpoint in the list. If a network or communications failure occurs when sending to this endpoint, the Routing Service attempts to send the message to the next endpoint contained in the list. The service continues sending the message to each endpoint in the backup endpoint list until the message is successfully sent, all backup endpoints return a network or communications-related error, or the message is sent and the endpoint returns a non-network, non-communications-related error.
```
<backupLists>
  <backupList name="backupEndpointList">
      <add endpointName="realDestination" />
  </backupList>
</backupLists>
```

Define the filter table, which associates the filter with the deadDestination endpoint and the backup endpoint list. The Routing Service first attempts to send the message to the destination endpoint associated with the filter. Since the deadDestination contains an address that does not refer to a running service, this results in a network error. The Routing Service then attempts to send the message to the endpoint specified in the backupEndpointList.

<filterTables>
        <!-- Set up the Routing Service's Message Filter Table -->
        <filterTable name="filterTable1">
            <!-- Add an entity that maps the MatchAllMessageFilter to the dead destination -->
            <!-- If that endpoint is down, tell the Routing Service to try the endpoints -->
            <!-- Listed in the backupEndpointList -->
            <add filterName="MatchAllFilter1" endpointName="deadDestination" backupList="backupEndpointList"/>
        </filterTable>
      </filterTables>

To evaluate incoming messages against the filter contained in the filter table, you must associate the filter table with the service endpoints by using the routing behavior. The following example demonstrates associating "filterTable1" with the service endpoints.
```
<behaviors>
  <serviceBehaviors>
    
    <behavior name="routingConfiguration">
      <routing filterTableName="filterTable1" />
    </behavior>
  </serviceBehaviors>
</behaviors>
```

Example

The following is a complete listing of the configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<!-- Copyright (c) Microsoft Corporation.  All Rights Reserved. -->
<configuration>
  <system.serviceModel>
    <services>
      <service behaviorConfiguration="routingConfiguration"
               name="System.ServiceModel.Routing.RoutingService">
        <host>
          <baseAddresses>
            <add baseAddress="http://localhost/routingservice/" />
          </baseAddresses>
        </host>
        <!-- Create the Routing Service endpoint -->
        <endpoint address="router"
                  binding="basicHttpBinding"
                  name="RoutingServiceEndpoint"
                  contract="System.ServiceModel.Routing.IRequestReplyRouter" />
      </service>
    </services>
    <behaviors>
      <serviceBehaviors>
        <!-- Set up the Routing Behavior -->
        <behavior name="routingConfiguration">
          <routing filterTableName="filterTable1" />
        </behavior>
      </serviceBehaviors>
    </behaviors>
    <!-- Create the destination endpoints that we want to send to -->
    <client>
      <!-- Create a dummy endpoint that we know will be down -->
      <endpoint name="deadDestination"
                address="net.tcp://localhost:9090/servicemodelsamples/fakeDestination"
                binding="netTcpBinding"
                contract="*" />

      <!-- Now create the real service endpoint -->
      <endpoint name="realDestination"
                address="net.tcp://localhost:8080/servicemodelsamples/service"
                binding="netTcpBinding"
                contract="*" />
    </client>
    <routing>
      <filters>
        <!-- Create a MatchAll filter which will catch all messages -->
        <filter name="MatchAllFilter1" filterType="MatchAll" />
      </filters>
      <filterTables>
        <!-- Set up the Routing Service's Message Filter Table -->
        <filterTable name="filterTable1">
            <!-- Add an entry that maps the MatchAllMessageFilter to the dead destination -->
            <!-- If that endpoint is down, tell the Routing Service to try the endpoints -->
            <!-- Listed in the backupEndpointList -->
            <add filterName="MatchAllFilter1" endpointName="deadDestination" backupList="backupEndpointList"/>
        </filterTable>
      </filterTables>
      <!-- Create the backup endpoint list -->
      <backupLists>
        <backupList name="backupEndpointList">
            <add endpointName="realDestination" />
        </backupList>
      </backupLists>
      </routing>
  </system.serviceModel>
</configuration>

How To: Error Handling

Implement Error Handling

Example

Additional resources