Visual Studio® 2008:

Windows®
Communication
Foundation
Module 6: Handling Errors
• Relating .NET Framework Exceptions to
Service-Level Faults
• Using Faults in a Service

• Handling Faults and Exceptions on Clients

Lesson: Relating .NET Framework Exceptions to
Service-Level Faults
• Relating Exceptions to Services

• Converting Exceptions to Faults

• Structure of a SOAP Fault

• Faults in Metadata
Relating Exceptions to Services
Exceptions are a common way to indicate errors

Local error Propagate up

information call chain

Terminates host Platform-specific

if uncaught information

These are not good characteristics for a service

 Converting Exceptions to Faults
Design Time Run Time
Domain Technical Domain Technical
errors errors errors errors

Service
Contract exception
errors handling

Service SOAP
Contract Fault SOAP
message
Structure of a SOAP Fault
<s:Envelope xmlns:s ="…/soap-envelope" xmlns:a ="…/addressing">
<s:Header>
<a:Action s:mustUnderstand ="1">
http://www.w3.org/2005/08/addressing/soap/fault
</a:Action>
<a:RelatesTo>
urn:uuid:dd129ffe-a8ff-4a70-ad6f-ad48085e94e8
</a:RelatesTo>
...
</s:Header>
<s:Body>
<s:Fault>
<s:Code>
<s:Value> s:Sender </s:Value>
</s:Code>
<s:Reason>
<s:Text xml:lang ="en-US"> ERROR INFO </s:Text>
</s:Reason>
<s:Detail>APPLICATION-SPECIFIC INFORMATION</s:Detail>
</s:Fault>
</s:Body>
</s:Envelope>
Faults in Metadata

[OperationContract]
[FaultContract(typeof(BankService.NoFunds))]
void Withdraw(string account, decimal amount);

Metadata
Generation
<wsdl:operation name="Withdraw">
<wsdl:input
wsaw:Action="http://tempuri.org/MyContract/Withdraw“
message="tns:MyContract_Withdraw_InputMessage"/>
<wsdl:output
wsaw:Action="http://tempuri.org/MyContract/WithdrawResponse“
message="tns:MyContract_Withdraw_OutputMessage"/>
<wsdl:fault
wsaw:Action="http://tempuri.org/MyContract/WithdrawNoFundsFault“
name=“NoFundsFault“
message="tns:MyContract_Withdraw_NoFundsFault_FaultMessage"/>
</wsdl:operation>
Lesson: Using Faults in a Service
• Designing Service Error Handling

• Deciding What Information To Include in Faults

• Typed and Untyped Faults

• Using a Typed Fault

• Service Behavior and Exceptions

• Applying Consistent Error Handling

• Diagnosing Unexpected Exceptions

• Demonstration: Handling and Generating Exceptions in a

WCF Service
Designing Service Error Handling
Domain Technical
errors errors

Always Expected Unexpected

expected

Inform Inform
Handle
caller caller
Deciding What Information to Include in Faults

End Users Service-Side

Support Team

Different information
for different
constituencies

Client-Side
Support Team
Typed and Untyped Faults

WCF provides programmatic representation of

SOAP fault
FaultException Populate fields on untyped fault

FaultException<T> Provide typed fault information

[DataContract(Namespace="http://myuri.org/Simple")]
public class AccountOverdrawnFault
{ DataContract
private string accountNo; for use as a
typed fault
[DataMember]
public string AccountNo
{
get { return accountNo; }
set { accountNo = value; }
}
...
}
Using a Typed Fault

void Withdraw(string account, decimal amount)

{
try
{
bankBusinessObject.Withdraw(account, amount);
...
}
catch (AccountOverdrawnException ex);
{
AccountOverdrawnFault fault =
new AccountOverdrawnFault(ex.accountNo,
ex.balanceBefore,
ex.amount);
throw new FaultException<AccountOverdrawnFault>(fault));
}
}
Service Behavior and Exceptions

Typed
fault
Ongoing
Domain
communication
error

Untyped
fault

Expected Ongoing
technical error communication

No
action
Unhandled Faulted
Unexpected
exception channel
technical error
Applying Consistent Error Handling

First option for consistent error handling is a big outer try block

Try/catch in each service operation

Convert exception to fault based on policy

Second option for consistent error handling is an error handler

Create custom error handler containing conversion code

Implement IErrorHandler.HandleError method

Add error handler to collection on ChannelDispatchers

Removes repeated error handling code from domain code

Diagnosing Unexpected Exceptions

By default unhandled exception information is not passed to caller

Security issues with information passed back

However, this is a problem for fault diagnosis

Set the includeExceptionDetailInFaults property of serviceDebug

<behavior name="bankServiceBehavior">
<serviceDebug includeExceptionDetailInFaults="true"/>
...
</behavior>

Switch it off in production environment

Demonstration: Handling and Generating Exceptions
in a WCF Service
In this demonstration, you will see how to:
• Create a typed WCF fault and use this as part of a service
contract
• Handle exceptions in a generic way in the service
Notes Page Over-flow Slide. Do Not Print Slide.
See Notes pane.
Lesson: Handling Faults and Exceptions on Clients
• Handling Service Exceptions

• Communication Exceptions

• Handling Typed Faults

• Handling Untyped Faults

• Faults and Different Communication Patterns

• Demonstration: Handling Service Exceptions in a Client

Handling Service Exceptions

Client must handle:

Expected domain and technical errors on service contract

Unexpected technical errors may fault the channel

Communication-related errors (will fault the channel)

• All remote code should be surrounded by a try/catch block

• Must recreate proxy if channel has faulted

Communication Exceptions

CommunicationException

TimeoutException EndpointNotFound

ProtocolException

CommunicationObjectFaultedException

Handle individual exceptions or CommunicationException

Handling Typed Faults

try
{
bankServiceProxy.Withdraw("ABC123", 2000.00);
...
}
catch (FaultException<AccountOverdrawnFault> ex);
{
AccountOverdrawnFault fault = ex.Detail;

Console.WriteLine("{0}. Account {1}, balance before {2}",

fault.Message,
fault.Account,
fault.Balance);
}
Handling Untyped Faults

try
{
bankServiceProxy.Withdraw("ABC123", 2000.00);
...
}
catch (FaultException ex);
{
Console.WriteLine("Service fault: {0}.", ex.Reason);
}

Enable includeExceptionDetailInFaults for more information

Faults and Different Communication Patterns

Most error handling focused on request/response

One-way operations

Fault not generated when message is sent

Next call to channel will generate fault

Duplex

Fault defined on callback contract

Demonstration: Handling Service Exceptions in
a Client
In this demonstration, you will see how to handle service
exceptions in a client and determine the underlying cause of
the problem
Notes Page Over-flow Slide. Do Not Print Slide.
See Notes pane.
Lab: Error Handling
• Exercise 1: Handle Unexpected Errors in a WCF Service

• Exercise 2: Add Fault Handling to a WCF Service and the

Service Contract

Logon information
Virtual machine 6461A-LON-DEV-06

User name Student

Password Pa$$w0rd

Estimated time: 40 minutes

Lab Review
• Would you go on to convert outer try blocks in your
operations to use IErrorHandler?
• How would you handle unexpected technical errors that
occur in your service? Would you represent this on the
service contract?
Module Review and Takeaways
• Review Questions

• Common Issues and Troubleshooting Tips

• Best Practices