Session routing rules define how messages that have been sent
to the session are forwarded to participants. Session routing rules are defined
in the routing table in the session. Each route in the routing
table specifies the conditions for routing a message to a
destination, the destination service to send a message to if these conditions
are satisfied, and optionally an intercept that can transform the
message before it is sent to the destination. When the session
receives a message, it evaluates the conditions that are specified for each
route in the routing table. If the conditions are met, the
session sends the message to the corresponding destination. The routing
rules enable the Session Web service to implement the following common routing
patterns:
- Unicast. If only a single service matches the routing
criteria, the message is routed to that single service.
- Multicast. If multiple services match the routing
criteria, the message is routed to all matching services.
- Broadcast. The Session Web service can route the
message to every service participating in the session.
- None. If no service matches the routing criteria,
the message is not routed, and an event is recorded in the Windows
Application Event Log.
When you create a session, a routing table is constructed in the Session
manifest containing the routing rules for the session. The routing table
generated for your session can contain both default routes and custom routes.
Default routes are generated automatically based on the WSDL of the
participating services. You create custom routes yourself and custom routes are
typically used to implement business logic for example using an intercept
participant required you to use custom routing. You can define a custom route
when you create a new session or can add the route dynamically during the
lifecycle of the session. If a custom route is specified, default routing will
not apply for that destination. This means that any messages, which
would under default routing be sent to that destination, will not be
routed to that destination if the criteria of the custom route does not
evaluate to true.
Default Routes
By default, the Session Web service generates a default set of rules that is
based on the operations that are exposed by each participant. When a client
application sends a message that matches an action that corresponds to an
operation of a service, the session routes the message to the
operation of that service. If the message matches an action that corresponds to
an operation in more than one service, then the session routes the message to
the operation of all the services.
The following figure shows a message that is sent from the client to
the session with an action property Action="http://getPrice". The Session Web
service queries the routing table by using the key Action="http://getPrice".
The action is checked against all entries in the routing table and the
destination is returned for all entries when the criteria evaluate to
true. In the figure, Destination = Warehouse[PriceChecker] is returned.
The session then routes the message to the PriceChecker Web method of the
Warehouse service. The PriceChecker method of the Warehouse service returns the
price to the session and the session routes the reply to the
client.
The default routing table is generated using the list of participants
specified in the participant manifest. When a session is created the
Session Web service queries the WSDL for each of the participants. The WSDL for
each of the participants exposes an action tag for each method. The action tag
for each method is used to generate the default routing table, specifying
action parameters for the criteria property for each destination.
.gif)
Custom Routes
You can add your own custom routes to a session and provide additional
criteria that the session can use to route messages. These criteria can
combine a number of operands and operators. When the session routes a message,
it evaluates the criteria for each route, and then sends the message to all
destinations that match the criteria.
The operands that you can specify as conditions for a route
include:
-
SOURCE. Matches the ParticipantName of
the endpoint from which the message is sent.
SOURCE EQ 'AParticipant'
-
FROM. Matches the endpoint from which the
message is sent.
FROM EQ
'http://servername/FromParticipantUri'
-
REPLYTO. Matches the endpoint specified as the
Reply To in the message header.
REPLYTO EQ
'http://servername/ReplyToParticipantUri'
-
FAULTTO. Matches the endpoint specified as the
Fault To in the message header.
FAULTTO EQ
'http://servername/FaultToParticipantUri'
-
RELATESTO. Matches the MessageID
property of a message to which the message being sent relates.
RELATESTO EQ
'uuid:772373c1-63d5-40dc-9951-332ccd2115ef'
-
MESSAGEID. Matches the MessageID
property of the message that is being sent.
MESSAGEID EQ
'uuid:ff98cb2e-e20a-4323-8565-93968772f853
-
ACTION. Matches the action of the message that
is being sent.
ACTION EQ 'MessageAction'
-
MESSAGE. Matches the name of the first XML tag
in the body of the message that is being sent.
MESSAGE EQ 'FirstXmlTag'
-
MESSAGENS. Matches the namespace of the first
XML tag in the body of the message that is being sent.
MESSAGENS EQ
'http://FirstXmlTagNamespace/'
-
SESSION. Identifies messages sent by the Session
Web service.
SOURCE EQ 'SESSION'
-
CSFCONTEXT. Matches messages with a given
value in the CsfContext property in the message
header. For more information, see >
How to Add the CsfContext Property to a Message Header.
CSFCONTEXT EQ 'MessageCsfContext'
-
TRUE. Evaluates to true for all
messages and can be used to route all messages to the
specified participant.
TRUE
-
FALSE. Evaluates to false for all
messages and is used to turn off the route.
FALSE
You can use any combination of the following operators to combine or
qualify the operands. The operands are listed in order of precedence, with NOT
having the highest precedence. The order of precedence can be changed by using
parentheses:
The destination for a route is a valid endpoint that specifies
an action for a participant. The destination must be a method exposed by a
participant Web service. If the actions property is used, the method
must be included in the actions property for the participant in the participant
manifest. There can only be one route for each destination, so,
if there is more than one criterion that should be routed to the same
destination, the OR operator must be used to combine criteria.
Using an Intercept
A message can be transformed by an intercept participant before it
is sent to the destination. You should note that only participants
with Role=Intercept specified in the participant manifest can act as an
intercept. The same intercept can appear in as many routes as is
required. For more information, see Intercepts
and >How to
Create an Intercept Participant.
The following figure shows a message that is sent from the client
to the session with an action property Action="http://getPriceImperial". The
Session Web service queries the routing table by using the key
Action="http://getPriceImperial". This action is checked against all entries in
the routing table and the destination is returned for all entries when the
criteria evaluate to true. In this example, Destination =
Warehouse[PriceChecker], with the associated intercept, Intercept =
Converter[ItoM], is returned. The session routes the message to the ItoM method
of the Converter Web service that converts the imperial measurement 12" to the
metric equivalent 0.3m before the session returns the message to the session.
The session then routes the message to the PriceChecker Web method of the
Warehouse service. The PriceChecker method of the Warehouse service calculates
and returns the price to the session, which in turn routes the reply to the
client.
.gif)
Examples
The examples below assume that the session manifest contains the following
participants and routes:
<Participants>
<Participant
timeout="0"
role="Service"
inChannelResponse="false"
type="WebService">
<ParticipantName>
Participant1
</ParticipantName>
<ParticipantID>
28ea7840-d9cd-41c9-a26c-01d6b70a0ad5
</ParticipantID>
<ParticipantUrl>
http://localhost/Participant1/Participant1.ashx
</ParticipantUrl>
<Actions>
<Action>
Action1
</Action>
<Action>
Action2
</Action>
</Actions>
<PolicyDocument>
<Include>
<SecondaryCredentialMap>
<PrimaryCredentiaForMessage>
None
</PrimaryCredentialForMessage>
<PrimaryCredentialForTransport
transportAuthenticationType="Ntlm">
None
</PrimaryCredentialForTransport>
</SecondaryCredentialMap>
</Include>
</PolicyDocument>
</Participant>
<Participant
timeout="0"
role="Service"
inChannelResponse="false"
type="WebService">
<ParticipantName>
Participant2
</ParticipantName>
<ParticipantID>
86fe1241-cc26-4a68-ae47-c7095afb312b
</ParticipantID>
<ParticipantUrl>
http://localhost/Participant2/Participant2.ashx
</ParticipantUrl>
<Actions>
<Action>
Action1
</Action>
<Action>
Action2
</Action>
<Action>
Action3
</Action>
</Actions>
<PolicyDocument>
<Include>
<SecondaryCredentialMap>
<PrimaryCredentiaForMessage>
None
</PrimaryCredentialForMessage>
<PrimaryCredentialForTransport
transportAuthenticationType="Ntlm">
None
</PrimaryCredentialForTransport>
</SecondaryCredentialMap>
</Include>
</PolicyDocument>
</Participant>
<Participants>
The following code examples show some possible combinations that could be
used to specify the criteria for a route:
To validate to true for all SOAP 1.2 faults that are sent by the
Session Web service:
MESSAGE EQ 'Fault' AND MESSAGENS EQ
'http://www.w3.org/2003/05/soap-envelope' AND SOURCE EQ 'SESSION'
To validate to true for all messages sent by Participant1 or
Participant2 which are not faults:
(SOURCE EQ 'Participant1' OR Participant2') AND MESSAGE
NEQ 'Fault'
To validate to true for all faults:
MESSAGE EQ 'Fault' AND MESSAGENS EQ
'http://www.w3.org/2003/05/soap-envelope' OR MESSAGE EQ 'Fault' AND MESSAGENS
EQ 'http://schemas.xmlsoap.org/soap/envelope'
To validate to true for messages with an action Action1 and sent by
Participant1 or with an action Action2:
ACTION EQ 'Action1' AND SOURCE EQ 'Participant1' OR ACTION
EQ 'Action2'
To validate to true for messages which do not have an action
Action1, sent by Participant1:
NOT (ACTION EQ 'Action1' AND SOURCE EQ 'Participant1')
To validate to true for all messages not sent by Session:
TRUE AND SOURCE NEQ 'SESSION'
See Also