Version 2 of the open source ChannelAdam WCF Library has been released.
The major changes include how retry policies for transient faults are applied, with support for plugging in any type of retry mechanism.
Please see the ChannelAdam WCF Library documentation for more information.
Please note: this article has been superceded by the documentation for the ChannelAdam WCF Library.
In my previous article, How To Call WCF Services Properly, I researched and highlighted the typical problems with using WCF clients (such as memory and connection leaks), and concluded that the most correct solution for consuming WCF services would:
Close and Abort methods throw exceptions; andThreadAbortException.And below was my sample code for correctly using a WCF client, performing exception handling and correctly performing the Close/Abort pattern.
1SampleServiceClient client = null;
2
3try
4{
5 client = new SampleServiceClient();
6
7 var response = client.SampleOperation(1234);
8
9 // Do some business logic
10}
11catch (FaultException<MyCustomException>)
12{
13 // Do some business logic for this SOAP Fault Exception
14}
15catch (FaultException)
16{
17 // Do some business logic for this SOAP Fault Exception
18}
19catch (CommunicationException)
20{
21 // Catch this expected exception so it is not propagated further.
22 // Perhaps write this exception out to log file for gathering statistics...
23}
24catch (TimeoutException)
25{
26 // Catch this expected exception so it is not propagated further.
27 // Perhaps write this exception out to log file for gathering statistics...
28}
29catch (Exception)
30{
31 // An unexpected exception that we don't know how to handle.
32 // Perhaps write this exception out to log file for support purposes...
33 throw;
34}
35finally
36{
37 // This will:
38 // - be executed if any exception was thrown above in the 'try' (including ThreadAbortException); and
39 // - ensure that CloseOrAbortServiceChannel() itself will not be interrupted by a ThreadAbortException
40 // (since it is executing from within a 'finally' block)
41 CloseOrAbortServiceChannel(client);
42
43 // Unreference the client
44 client = null;
45}
46
47
48private void CloseOrAbortServiceChannel(ICommunicationObject communicationObject)
49{
50 bool isClosed = false;
51
52 if (communicationObject == null || communicationObject.State == CommunicationState.Closed)
53 {
54 return;
55 }
56
57 try
58 {
59 if (communicationObject.State != CommunicationState.Faulted)
60 {
61 communicationObject.Close();
62 isClosed = true;
63 }
64 }
65 catch (CommunicationException)
66 {
67 // Catch this expected exception so it is not propagated further.
68 // Perhaps write this exception out to log file for gathering statistics...
69 }
70 catch (TimeoutException)
71 {
72 // Catch this expected exception so it is not propagated further.
73 // Perhaps write this exception out to log file for gathering statistics...
74 }
75 catch (Exception)
76 {
77 // An unexpected exception that we don't know how to handle.
78 // Perhaps write this exception out to log file for support purposes...
79 throw;
80 }
81 finally
82 {
83 // If State was Faulted or any exception occurred while doing the Close(), then do an Abort()
84 if (!isClosed)
85 {
86 AbortServiceChannel(communicationObject);
87 }
88 }
89}
90
91
92private static void AbortServiceChannel(ICommunicationObject communicationObject)
93{
94 try
95 {
96 communicationObject.Abort();
97 }
98 catch (Exception)
99 {
100 // An unexpected exception that we don't know how to handle.
101 // If we are in this situation:
102 // - we should NOT retry the Abort() because it has already failed and there is nothing to suggest it could be successful next time
103 // - the abort may have partially succeeded
104 // - the actual service call may have been successful
105 //
106 // The only thing we can do is hope that the channel's resources have been released.
107 // Do not rethrow this exception because the actual service operation call might have succeeded
108 // and an exception closing the channel should not stop the client doing whatever it does next.
109 //
110 // Perhaps write this exception out to log file for gathering statistics and support purposes...
111 }
112}
Unfortunately, due to the way Microsoft designed WCF, if you want to use a WCF service client cleanly without connection or memory leaks, then above is the type of extensive code that must be written for every service operation call.
I then promised to share an even better way to achieve this - by using some programming tricks to provide a nice, clean API for working with WCF clients, that significantly reduces the amount of that code that developers have to write.
Well, here it is! Drum roll please…
After more than a month of developing late into the evening and early morning, allow me to introduce the ChannelAdam WCF Library - an open source (Apache License 2.0) library that allows you to forget about the complex subtleties of WCF clients, channels and communication states, and lets you just use your service client (very similar to how you probably are doing it now - but without the leaks!).
When you use the ChannelAdam WCF Library’s ServiceConsumer, you know that you can keep calling service operations through the ServiceConsumer and it will ‘just work’ and not leak connections or memory - no matter what happens!
The ChannelAdam WCF Library’s ServiceConsumer hides the inner complexity of service channels. For example, if a service channel / communication object / service client moves into a Fault state, the ServiceConsumer will correctly perform the Close/Abort pattern and dispose of the channel. The next time a request is made through the ServiceConsumer, a new channel is created under the covers to seamlessly process the request.
You can install the ChannelAdam.Wcf NuGet package from within Visual Studio, or find it on the NuGet.org gallery at
https://www.nuget.org/packages/ChannelAdam.Wcf.
If you are keen to see some of the programming tricks and how it works, or possibly contribute features to it, the source code for the ChannelAdam WCF Library is on GitHub at https://github.com/channeladam/ChannelAdam.Wcf.
Let’s assume for the duration of this article that there is a web service named FakeService and in Visual Studio we have generated a service reference and interface to FakeService, and there is now an IFakeService interface and a FakeServiceClient class to use.
That is all normal and basic Visual Studio functionality.
Let’s also assume that the service has the following operation signature:
1int AddIntegers(int first, int second);
The first thing you need to understand is that you consume your service operations through the usage of the ChannelAdam.ServiceModel.ServiceConsumer class.
The second thing you need to understand is that the best way to create the ServiceConsumer is by using the Create method on the ChannelAdam.ServiceModel.ServiceConsumerFactory.
In order to use the ServiceConsumerFactory.Create method, simply pass in as a parameter a factory method for creating the service client.
For example:
1IServiceConsumer<IFakeService> service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient()));
The ServiceConsumerFactory.Create method returns a IServiceConsumer<TServiceInterface> type.
In all further examples, I will use the var keyword instead - such as:
1var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient()));
Alternatively, you can pass in as a string parameter the endpoint configuration name from the service client section of your application’s .config file. For example:
1var service = ServiceConsumerFactory.Create<IFakeService>("BasicHttpBinding_IFakeService"));
There are four ways in which the ServiceConsumer can be cleaned up:
The ServiceConsumer and underlying channel can be closed immediately by calling the Close method on the ServiceConsumer instance.
1service.Close();
If you want to, you still can immediately call another service operation via that same ServiceConsumer instance, as under the covers, a new service channel will be created seamlessly and automatically.
The ServiceConsumer and underlying channel can be disposed of immediately by calling the Dispose method on the ServiceConsumer instance.
1service.Dispose();
As per standard IDisposable concepts, you should not attempt to reuse the ServiceConsumer after disposing it.
Instead of calling the Close or Dispose methods directly, you can use the Using statement on the ServiceConsumer because it is a well behaved implementation of IDisposable (unlike Microsoft’s service clients!).
1using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient())))
2{
3 ...
4}
If you happen to accidently forget to wrap your ServiceConsumer instance in a Using statement or call the Close method, rest assured that the ServiceConsumer will still be cleaned up! When the ServiceConsumer instance goes out of scope, the .NET Garbage Collector will [eventually] kick in and call its destructor/finalise method, thus correctly cleaning up the service channel and preventing any leaks.
Since there is an indeterminate amount of time before the Garbage Collector kicks in, I would recommend the Using statement approach, as it minimises the number of open channels and other resources currently in use, over the lifetime of your application.
There are two ways in which to call a service operation via the ServiceConsumer:
Operations property; orConsume method.The Operations property exposes the interface of your service. It can be used just like the normal service client that you already would be familiar with.
Below is an example of how to call the AddIntegers operation via the Operations property.
1using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient())))
2{
3 try
4 {
5 int actualValue = service.Operations.AddIntegers(1, 1);
6 Assert.AreEqual(2, actualValue);
7 }
8 ...
9}
And below is an example of how to do some exception handling.
1using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient())))
2{
3 try
4 {
5 int actualValue = service.Operations.AddIntegers(1, 1);
6 Assert.AreEqual(2, actualValue);
7 }
8 catch (FaultException<MyCustomException> fe)
9 {
10 Console.WriteLine("Service operation threw a custom fault: " + fe.ToString());
11 }
12 catch (FaultException fe)
13 {
14 Console.WriteLine("Service operation threw a fault: " + fe.ToString());
15 }
16 catch (Exception ex)
17 {
18 Console.WriteLine("An unexpected error occurred while calling the service operation: " + ex.ToString());
19 }
20}
You may notice that there is now no need to catch a CommunicationException or TimeOutException and try to perform the Close/Abort pattern, as the underlying channel is dealt with automatically for you by the ServiceConsumer.
As an alternative to the Operations property, you can call a service operation via the Consume method on the ServiceConsumer instance.
The Consume method returns an instance of IOperationResult<TReturnTypeOfYourOperation> which wraps the result of the operation. This interface has the following helpful properties:
TReturnTypeOfYourOperation Value - which gives you access to the return value from the operation;bool HasException - whether there was an exception thrown by the service operation;bool HasNoException - whether there was not an exception thrown by the service operation;bool HasFaultException - whether an exception of type FaultException was thrown by the service operation;bool HasFaultException<OfThisType> - whether an exception of FaultException<OfThisType> was thrown by the service operation; andException Exception - the exception that was thrown by the service operation.Below is an example of how to call the AddIntegers operation via the Consume method.
1using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient())))
2{
3 IOperationResult<int> result = service.Consume(operation => operation.AddIntegers(1, 1));
4
5 if (result.HasNoException)
6 {
7 Assert.AreEqual(2, result.Value);
8 }
9 ...
10}
And below is an example of how to do some exception handling with IOperationResult.
1using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient())))
2{
3 var result = service.Consume(operation => operation.AddIntegers(1, 1));
4
5 if (result.HasNoException)
6 {
7 int actualValue = result.Value;
8 Assert.AreEqual(2, actualValue);
9 }
10 else
11 {
12 if (result.HasFaultExceptionOfType<MyCustomException>())
13 {
14 Console.WriteLine("Service operation threw a custom fault: " + result.Exception.ToString());
15 }
16 else if (result.HasFaultException)
17 {
18 Console.WriteLine("Service operation threw a fault: " + result.Exception.ToString());
19 }
20 else
21 {
22 Console.WriteLine("An unexpected error occurred while calling the service operation: " + result.Exception.ToString());
23 }
24 }
25}
It is easy to use the ServiceConsumerFactory from Inversion of Control (IoC) containers. Below are examples with three popular IoC containers.
Let’s assume that there is the following class and we want to perform constructor injection with it.
1public class ConstructorInjectedController
2{
3 public IServiceConsumer<IFakeService> FakeService { get; set; }
4
5 /// <summary>
6 /// Initializes a new instance of the <see cref="ConstructorInjectedController"/> class.
7 /// </summary>
8 /// <param name="fakeService">The fake service.</param>
9 public ConstructorInjectedController(IServiceConsumer<IFakeService> fakeService)
10 {
11 this.FakeService = fakeService;
12 }
13}
Here is how to use the ServiceConsumerFactory with AutoFac.
1var builder = new Autofac.ContainerBuilder();
2builder.Register(c => ServiceConsumerFactory.Create<IFakeService>("BasicHttpBinding_IFakeService")).InstancePerDependency();
3builder.RegisterType<ConstructorInjectedController>();
4
5var autofacContainer = builder.Build();
6
7var controller = autofacContainer.Resolve<ConstructorInjectedController>();
Here is how to use the ServiceConsumerFactory with SimpleInjector.
1var simpleInjectorContainer = new SimpleInjector.Container();
2simpleInjectorContainer.Register(() => ServiceConsumerFactory.Create<IFakeService>("BasicHttpBinding_IFakeService"), SimpleInjector.Lifestyle.Transient);
3simpleInjectorContainer.Verify();
4
5var controller = simpleInjectorContainer.GetInstance<ConstructorInjectedController>();
And, here is how to use the ServiceConsumerFactory with Unity.
1var unityContainer = new UnityContainer();
2
3unityContainer
4 .RegisterType<IServiceConsumer<IFakeService>>(
5 new TransientLifetimeManager(),
6 new InjectionFactory(c => ServiceConsumerFactory.Create<IFakeService>("BasicHttpBinding_IFakeService")))
7
8 //
9 // OR
10 //
11 //.RegisterType<IServiceConsumer<IFakeService>>(
12 // new InjectionFactory(c => ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient())))
13
14 //
15 // OR more 'correctly'
16 //
17 //.RegisterType<IFakeService, FakeServiceClient>(new TransientLifetimeManager())
18 //.RegisterType<IServiceConsumer<IFakeService>>(
19 // new InjectionFactory(c =>
20 // ServiceConsumerFactory.Create<IFakeService>(() => (ICommunicationObject)c.Resolve<IFakeService>())))
21 ;
22
23var controller = unityContainer.Resolve<ConstructorInjectedController>();
When an exception occurs while calling the service operation, the ServiceConsumer follows a specific strategy to determine whether the exception and/or current channel state is severe enough to necessitate and trigger the closing/aborting of the service channel.
These “Service Channel Close Trigger Strategies” are an implementation of the interface IServiceChannelCloseTriggerStrategy. There is one method in this interface:
1bool ShouldCloseChannel(ICommunicationObject channel, Exception exception);
If the method ShouldCloseChannel returns true, then the ServiceConsumer will perform the Close/Abort pattern.
Out of the box, the DefaultServiceChannelCloseTriggerStrategy is used. This strategy is very simple, effective and safe. It triggers a close to occur if the exception is anything but a FaultException, regardless of the state of the service channel. It is highly probable that the channel is no longer usable in the case where there was any other type of exception.
If you find that this strategy does not suit your need, you can create your own class that implements that interface and specify your class as one of the overloads of the Create method on the ServiceConsumerFactory. Alternatively, you can directly set the property ChannelCloseTriggerStrategy on the ServiceConsumer instance itself.
As you know, the ServiceConsumer automatically handles the clean up of service channels. If an exception occurs at any point throughout the usage of the channel, the ServiceConsumer will catch it and close the channel if necessary. In some cases, for example, if an exception occurs while attempting to close the channel, the ServiceConsumer does not want to propagate the exception back to the calling code, as it is not the caller’s concern. In order to be a good citizen and prevent the ServiceConsumer from swallowing exceptions, the concept of the “Exception Behaviour Strategy” was born.
Whenever an exception occurs throughout the lifetime of the ServiceConsumer, a corresponding method on the configured Exception Behaviour Strategy class is invoked, thus allowing the exception to be logged and statistics recorded for an organisation’s support purposes.
Each Exception Behaviour Strategy class implements the interface IServiceConsumerExceptionBehaviourStrategy. This interface contains the following methods:
PerformFaultExceptionBehaviour - the behaviour to perform when a fault exception occurs while the service operation is called;PerformCommunicationExceptionBehaviour - the behaviour to perform when a communication exception occurs while the service operation is called;PerformTimeoutExceptionBehaviour - the behaviour to perform when a timeout exception occurs while the service operation is called;PerformUnexpectedExceptionBehaviour - the behaviour to perform when an unexpected exception occurs while the service operation is called;PerformCloseCommunicationExceptionBehaviour - the behaviour to perform when a communication exception occurs during a close;PerformCloseTimeoutExceptionBehaviour - the behaviour to perform when a timeout exception occurs during a close;PerformCloseUnexpectedExceptionBehaviour - the behaviour to perform when an unexpected exception occurs during a close;PerformAbortExceptionBehaviour - the behaviour to perform when an exception occurs during an abort; andPerformDestructorExceptionBehaviour - the behaviour to perform when an exception occurs during a destructor/Finalize method.The ChannelAdam.Wcf Library comes with the following Exception Behaviour Strategies:
NullServiceConsumerExceptionBehaviourStrategy - which does not write out any exception details anywhere;StandardOutServiceConsumerExceptionBehaviourStrategy - which writes out all exceptions to the Standard Error stream; andStandardErrorServiceConsumerExceptionBehaviourStrategy - which writes out all exceptions to the Standard Out stream.By default, the ServiceConsumerFactory configures each ServiceConsumer with the StandardErrorServiceConsumerExceptionBehaviourStrategy.
There are three ways to change the Exception Behaviour Strategy that is assigned when you create a ServiceConsumer:
Create method on the ServiceConsumerFactory;ChannelCloseTriggerStrategy on the ServiceConsumer instance itself; orServiceConsumerFactory.DefaultExceptionBehaviourStrategy to your desired strategy. From then on, that strategy will be used by default.As I expect will be the case, many organisations will want to use a logging library and write out the exceptions to a log file somewhere. Easy - just implement the interface and set it as the default in some bootstrap code.
When you call your web services, do you currently handle transient errors that may occur (such as the network briefly dropping out), and have some automatic retry logic?
Well, the ChannelAdam WCF Library has some built-in support for the Microsoft Practices Transient Fault Handling Library - but only when you use the Consume method and not when you use the Operations property.
Below is an example naive implementation of retry logic (without the help of any library) while using the Operations property.
1int retryCount = 1;
2Exception lastException = null;
3
4using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient()))
5{
6 while (retryCount > 0)
7 {
8 Console.WriteLine("#### Retry count: " + retryCount);
9
10 try
11 {
12 int actual = service.Operations.AddIntegers(1, 1);
13
14 Console.WriteLine("Actual: " + actual);
15 Assert.AreEqual(2, actual);
16
17 return;
18 }
19 catch (FaultException fe)
20 {
21 lastException = fe;
22 Console.WriteLine("Service operation threw a fault: " + fe.ToString());
23 }
24 catch (Exception ex)
25 {
26 lastException = ex;
27 Console.WriteLine("Technical error occurred while calling the service operation: " + ex.ToString());
28 }
29
30 retryCount--;
31 }
32}
33
34Assert.Fail("Service operation was not successfully called");
Unfortunately that code is lengthy and error prone.
The code above can be improved upon by using the Microsoft Practices Transient Fault Handling Library, as below.
You will notice in this example, I am using the ChannelAdam.ServiceModel.SoapFaultWebServiceTransientErrorDetectionStrategy to determine if there was a transient error or not. If the given exception was a FaultException, this strategy says that was not a transient error and therefore do not retry. If on the other hand any other type of exception occurs, then this strategy will tell the Microsoft library to retry according to the retry policy.
1Exception lastException;
2
3using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient()))
4{
5 try
6 {
7 int actual = 0;
8
9 var retryStrategy = new Incremental(5, TimeSpan.FromSeconds(2), TimeSpan.FromSeconds(2));
10 var retryPolicy = new RetryPolicy<SoapFaultWebServiceTransientErrorDetectionStrategy>(retryStrategy);
11
12 retryPolicy.ExecuteAction(() =>
13 {
14 actual = service.Operations.AddIntegers(1, 1);
15 });
16
17 Console.WriteLine("Actual: " + actual);
18 Assert.AreEqual(2, actual);
19
20 return;
21 }
22 catch (FaultException fe)
23 {
24 lastException = fe;
25 Console.WriteLine("Service operation threw a fault: " + fe.ToString());
26 }
27 catch (Exception ex)
28 {
29 lastException = ex;
30 Console.WriteLine("Technical error occurred while calling the service operation: " + ex.ToString());
31 }
32
33 Assert.Fail("Service operation was not successfully called");
For me, both code examples above that use the Operations property is clunky - which is why I prefer using the Consume method!
When using the Consume method, there are three ways to set the retry policy:
DefaultRetryPolicy on the ServiceConsumerFactory - which will apply to all created instances;Create method on the ServiceConsumerFactory - which will apply just to that ServiceConsumer instance to be created; orConsume method itself.For example, the overload on the Consume method:
1using (var service = ServiceConsumerFactory.Create<IFakeService>(() => new FakeServiceClient()))
2{
3 var retryStrategy = new Incremental(5, TimeSpan.FromSeconds(2), TimeSpan.FromSeconds(2));
4 var retryPolicy = new RetryPolicy<SoapFaultWebServiceTransientErrorDetectionStrategy>(retryStrategy);
5
6 var result = service.Consume(operation => operation.AddIntegers(1, 1), retryPolicy);
7
8 if (result.HasNoException)
9 {
10 Console.WriteLine("Actual: " + result.Value);
11 Assert.AreEqual(2, result.Value);
12 }
13 else
14 {
15 if (result.HasFaultException)
16 {
17 Console.WriteLine("Service operation threw a fault: " + result.Exception.ToString());
18 }
19 else if (result.HasException)
20 {
21 Console.WriteLine("An unexpected error occurred while calling the service operation: " + result.Exception.ToString());
22 }
23
24 Assert.Fail("Service operation was not successfully called");
25 }
26}
Perhaps you too may agree that using the retry strategy with the Consume method is simpler and cleaner, in comparison with the Operations property.
If you want to know at a deeper level how the ServiceConsumer and its friends behave, perhaps you would like to read the Behaviour Specifications feature file.
The ChannelAdam WCF Library is designed to make your life as a developer easier when consuming WCF services, by abstracting away the complexities of service channel state transitions and the odd behaviour of the Microsoft WCF libraries that do not comply with even their own design guidelines.
In doing this, the ChannelAdam ServiceConsumer once and for all prevents memory and connection leaks, gives developers the ability to plug in their own strategies for handling different situations (such as logging exceptions), and provides a built-in mechanism to retry service operation calls when transient faults occur.
I hope you like it, and I welcome your feedback!
No matter how many client sites I visit, invariably I stumble across Windows Communication Foundation (WCF) client-side code that leaks memory and resources. This can result in an application crashing or connection limits being reached resulting in further service calls being rejected. Not only can the client-side code cause problems on the client machine, but if connections are not correctly closed on the client then that can cause the server to hit its maximum connection limit and reject service calls from other clients as well!
These types of issues are caused by developers performing incorrect error handling and incorrect disposal of the client and connection. Microsoft really is to blame for starting this mess, as they created an API that does not conform to typical practices - or even their own guidelines! For instance, Microsoft’s guideline is never to throw an exception from a Dispose method - but the WCF client code does exactly that. At the end of the day however, it is the responsibility of individual developers to be aware of the issues and design restrictions and create software that works properly.
In many cases, WCF client-side code resides in small or medium-sized user applications that do not get used hard or long enough to exhibit a noticeable degradation in system resources and upset users. But as previously stated, depending on the number of users, it still may be causing issues on servers.
When it goes wrong - for instance, on a server - there can be a spectacular flurry of activity! It can be amazing to see how quickly IT departments can move when a server hosting core business services starts failing due to custom server applications leaking resources and using many Gigabytes of memory. Unfortunately it takes such an event for many businesses to pay attention to the need for higher-quality software development practices and testing.
In the past I have seen proud companies who develop and sell custom n-tier products “work around” known problems in their proprietary code by recommending to their clients that they recycle the IIS Application Pools frequently and run an excessive numbers of servers. I never really appreciated that band-aid attitude towards software development practices or clients.
This series of articles will show you how to fix the root cause - by correctly calling WCF services, handling errors and disposing of WCF clients.
Update 2014-10-01: The focus of this article is not about the overall design of WCF. Other parts of WCF are designed very well - especially with regards to its extensible nature. This article is a narrow focus on the design decisions that cause the common issues I see too often on so many client sites.
One of the problems that Microsoft caused was by not following their own guideline of not throwing exceptions in the Dispose method. The using statement is an excellent and common pattern for automatically disposing IDisposable objects at the end of the code block. Avoiding Problems with the Using Statement describes how even though the WCF client is disposable, developers should NOT use the using statement with them.
The C# “using” statement results in a call to Dispose(). This is the same as Close(), which may throw exceptions when a network error occurs. Because the call to Dispose() happens implicitly at the closing brace of the “using” block, this source of exceptions is likely to go unnoticed both by people writing the code and reading the code. This represents a potential source of application errors.
Microsoft demonstrates in that article how to clean up “correctly” when an exception occurs.
1try
2{
3 ...
4 client.Close();
5}
6catch (CommunicationException e)
7{
8 ...
9 client.Abort();
10}
11catch (TimeoutException e)
12{
13 ...
14 client.Abort();
15}
16catch (Exception e)
17{
18 ...
19 client.Abort();
20 throw;
21}
It is important to understand that if the client is in a State of Faulted, then the only action that should be taken by client code is the Abort method. As documented in Expected Exceptions the TimeoutException, CommunicationException and any derived class of CommunicationException are ‘expected’ exceptions from the WCF client.
If an expected exception occurs, the client may or may not be usable afterwards. To determine if the client is still usable, check that the State property is CommunicationState.Opened. If it is still opened, then it is still usable. Otherwise you should abort the client and release all references to it.
Caution: You may observe that clients that have a session are often no longer usable after an exception, and clients that do not have a session are often still usable after an exception. However, neither of these is guaranteed, so if you want to try to continue using the client after an exception your application should check the State property to verify the client is still opened.
Code that calls a client communication method must catch the TimeoutException and CommunicationException.
However, all this talk of checking for the State property is cautioned by Accessing Services Using a WCF Client:
Checking the value of the ICommunicationObject.State property is a race condition and is not recommended to determine whether to reuse or close a channel.
If you were to check the State property in order to determine whether to Abort or Close, depending on your approach there could be a race condition. For instance the following code could result in a race condition:
1if (this.State == CommunicationState.Faulted)
2{
3 this.Abort();
4}
5else
6{
7 this.Close();
8}
The race condition could occur because when the State property is checked to see if it is Faulted it might be Opened at that point in time. However, by the short time that Close method is reached, the State might now be Faulted, and when Close is called an exception would be thrown. This code alone is not sufficient.
The Communication State Enumeration documentation explains the meaning of each possible State:
The Closed state is equivalent to being disposed and the configuration of the object can still be inspected.
The Faulted state is used to indicate that the object has transitioned to a state where it can no longer be used. There are two primary scenarios where this can happen:
- If the Open method fails for any reason, the object transitions to the faulted state.
- If a session-based channel detects an error that it cannot recover from, it transitions to the faulted state. This can happen for instance if there is a protocol error (that is, it receives a protocol message at an invalid time) or if the remote endpoint aborts the session.
An object in the Faulted state is not closed and may be holding resources. The Abort method should be used to close an object that has faulted. If Close is called on an object in the Faulted state, a CommunicationObjectFaultedException is thrown because the object cannot be gracefully closed.
The article Understanding State Changes describes how the State property can transition to different states. This article expands upon and somewhat contradicts the previous by indicating that if the object is in the Faulted state then the Close method will call Abort for you and return.
The Close() method can be called at any state. It tries to close the object normally. If an error is encountered, it terminates the object. The method does nothing if the current state is Closing or Closed. Otherwise it sets the state to Closing. If the original state was Created, Opening or Faulted, it calls Abort().
I’m confused - how about you?
To remedy my confusion, I went to the source of truth - the code. The reference source for CommunicationObject shows us that the Close method handles being called from any State value, and that it will perform an Abort if required. In addition, if the State was Faulted, the Close method actually will throw a CommunicationObjectFaultedException.
1...
2 switch (originalState)
3 {
4 case CommunicationState.Created:
5 case CommunicationState.Opening:
6 case CommunicationState.Faulted:
7 this.Abort();
8 if (originalState == CommunicationState.Faulted)
9 {
10 throw TraceUtility.ThrowHelperError(this.CreateFaultedException(), Guid.Empty, this);
11 }
12 break;
13...
The article Understanding State Changes also explicitly states that the Abort method can throw exceptions.
The Abort() method does nothing if the current state is Closed or if the object has been terminated before (for example, possibly by having Abort() executing on another thread). Otherwise it sets the state to Closing and calls OnClosing() (which raises the Closing event), OnAbort(), and OnClosed() in that order (does not call OnClose because the object is being terminated, not closed). OnClosed() sets the state to Closed and raises the Closed event. If any of these throw an exception, it is re-thrown to the caller of Abort.
No sample code from Microsoft or anywhere else that I have seen handles the situation where the Abort method throws an exception.
Stack Overflow has an interesting thread about how to work around the using block issue and perform the close/abort pattern. Their top-voted solution for the close/abort pattern, to fix the race condition is:
1bool success = false;
2try
3{
4 if (State != CommunicationState.Faulted)
5 {
6 Close();
7 success = true;
8 }
9}
10finally
11{
12 if (!success)
13 {
14 Abort();
15 }
16}
In this code, if the State is already Faulted or the execution of the Close method throws an exception (which is implicitly caught and ignored), then finally the Abort method will be called. That’s pretty good. But as we now know, the Abort method can throw exceptions, and that code does not handle it.
The article Sending and Receiving Faults shows us that we need to catch the exceptions in a specific order - especially in relation to the SOAP-based FaultException.
Because FaultException
derives from FaultException, and FaultException derives from CommunicationException, it is important to catch these exceptions in the proper order. If, for example, you have a try/catch block in which you first catch CommunicationException, all specified and unspecified SOAP faults are handled there; any subsequent catch blocks to handle a custom FaultException exception are never invoked. Remember that one operation can return any number of specified faults. Each fault is a unique type and must be handled separately.
Closing the channel can throw exceptions if the connection cannot be cleanly closed or is already closed, even if all the operations returned properly.
Typically, client object channels are closed in one of the following ways:
- When the WCF client object is recycled.
- When the client application calls ClientBase
.Close. - When the client application calls ICommunicationObject.Close.
- When the client application calls an operation that is a terminating operation for a session.
In all cases, closing the channel instructs the channel to begin closing any underlying channels that may be sending messages to support complex functionality at the application level. For example, when a contract requires sessions a binding attempts to establish a session by exchanging messages with the service channel until a session is established. When the channel is closed, the underlying session channel notifies the service that the session is terminated. In this case, if the channel has already aborted, closed, or is otherwise unusable (for example, when a network cable is unplugged), the client channel cannot inform the service channel that the session is terminated and an exception can result.
Abort the Channel If Necessary
Because closing the channel can also throw exceptions, then, it is recommended that in addition to catching fault exceptions in the correct order, it is important to abort the channel that was used in making the call in the catch block. If the fault conveys error information specific to an operation and it remains possible that others can use it, there is no need to abort the channel (although these cases are rare). In all other cases, it is recommended that you abort the channel. For a sample that demonstrates all of these points, see Expected Exceptions.
And here is the sample code from that article:
1using System;
2using System.ServiceModel;
3using System.ServiceModel.Channels;
4using Microsoft.WCF.Documentation;
5
6public class Client
7{
8 public static void Main()
9 {
10 SampleServiceClient wcfClient = new SampleServiceClient();
11
12 try
13 {
14 wcfClient.SampleMethod("hello");
15
16 wcfClient.Close();
17 }
18 catch (TimeoutException timeProblem)
19 {
20 wcfClient.Abort();
21 }
22 catch (FaultException<MyCustomFault> myCustomFault)
23 {
24 wcfClient.Abort();
25 }
26 catch (FaultException<MyOtherCustomFault> myOtherCustomFault)
27 {
28 wcfClient.Abort();
29 }
30 catch (FaultException unknownFault)
31 {
32 wcfClient.Abort();
33 }
34 catch (CommunicationException commProblem)
35 {
36 wcfClient.Abort();
37 }
38 }
39}
Note the following about this sample code:
Abort method.There is one more type of exception that never seems to be mentioned in sample code or in any literature I have seen related to WCF, and that is the ThreadAbortException.
When this exception is raised, the runtime executes all the finally blocks before ending the thread. Because the thread can do an unbounded computation in the finally blocks or call Thread.ResetAbort to cancel the abort, there is no guarantee that the thread will ever end.
The ThreadAbortException is a special exception that can occur asynchronously. If the WCF client is called from within a thread, and if the thread is aborted, then it might be prudent to clean up the client before the thread finishes.
The top-voted solution from Stack Overflow does partially and elegantly handle this situation, as well as the other asynchronous exceptions such as OutOfMemoryException and StackOverflowException.
So does all that sound complicated enough? No wonder so many don’t get it right…
In my opinion, the most correct solution would:
Close and Abort methods throw exceptionsThreadAbortExceptionBelow is my proposed solution for correctly using a WCF client.
1SampleServiceClient client = null;
2
3try
4{
5 client = new SampleServiceClient();
6
7 var response = client.SampleOperation(1234);
8
9 // Do some business logic
10}
11catch (FaultException<MyCustomException>)
12{
13 // Do some business logic for this SOAP Fault Exception
14}
15catch (FaultException)
16{
17 // Do some business logic for this SOAP Fault Exception
18}
19catch (CommunicationException)
20{
21 // Catch this expected exception so it is not propagated further.
22 // Perhaps write this exception out to log file for gathering statistics...
23}
24catch (TimeoutException)
25{
26 // Catch this expected exception so it is not propagated further.
27 // Perhaps write this exception out to log file for gathering statistics...
28}
29catch (Exception)
30{
31 // An unexpected exception that we don't know how to handle.
32 // Perhaps write this exception out to log file for support purposes...
33 throw;
34}
35finally
36{
37 // This will:
38 // - be executed if any exception was thrown above in the 'try' (including ThreadAbortException); and
39 // - ensure that CloseOrAbortServiceChannel() itself will not be interrupted by a ThreadAbortException
40 // (since it is executing from within a 'finally' block)
41 CloseOrAbortServiceChannel(client);
42
43 // Unreference the client
44 client = null;
45}
46
47
48
49private void CloseOrAbortServiceChannel(ICommunicationObject communicationObject)
50{
51 bool isClosed = false;
52
53 if (communicationObject == null || communicationObject.State == CommunicationState.Closed)
54 {
55 return;
56 }
57
58 try
59 {
60 if (communicationObject.State != CommunicationState.Faulted)
61 {
62 communicationObject.Close();
63 isClosed = true;
64 }
65 }
66 catch (CommunicationException)
67 {
68 // Catch this expected exception so it is not propagated further.
69 // Perhaps write this exception out to log file for gathering statistics...
70 }
71 catch (TimeoutException)
72 {
73 // Catch this expected exception so it is not propagated further.
74 // Perhaps write this exception out to log file for gathering statistics...
75 }
76 catch (Exception)
77 {
78 // An unexpected exception that we don't know how to handle.
79 // Perhaps write this exception out to log file for support purposes...
80 throw;
81 }
82 finally
83 {
84 // If State was Faulted or any exception occurred while doing the Close(), then do an Abort()
85 if (!isClosed)
86 {
87 AbortServiceChannel(communicationObject);
88 }
89 }
90}
91
92private static void AbortServiceChannel(ICommunicationObject communicationObject)
93{
94 try
95 {
96 communicationObject.Abort();
97 }
98 catch (Exception)
99 {
100 // An unexpected exception that we don't know how to handle.
101 // If we are in this situation:
102 // - we should NOT retry the Abort() because it has already failed and there is nothing to suggest it could be successful next time
103 // - the abort may have partially succeeded
104 // - the actual service call may have been successful
105 //
106 // The only thing we can do is hope that the channel's resources have been released.
107 // Do not rethrow this exception because the actual service operation call might have succeeded
108 // and an exception closing the channel should not stop the client doing whatever it does next.
109 //
110 // Perhaps write this exception out to log file for gathering statistics and support purposes...
111 }
112}
Well, that’s quite depressing, isn’t it! Imagine that you have an application that calls many services. If you were to tell me that I should duplicate all that code every time I want to make a service operation call, as a developer I won’t be happy.
Unfortunately that is exactly the situation that Microsoft has forced upon developers.
You could take some short-cuts and not do all the exception handling, but no doubt on the day that one of those perhaps rare exceptions happen (and it will!), you will be glad that you handled those edge cases.
In my next article, I will show you how to use some programming tricks to significantly reduce the amount of code that developers have to write and provide a nice, clean API for working with WCF clients.