Specifying Client Run-Time Behavior

Windows Communication Foundation (WCF) clients, like Windows Communication Foundation (WCF) services, can be configured to modify the run-time behavior to suit the client application. Three attributes are available for specifying client run-time behavior. Duplex client callback objects can use the CallbackBehaviorAttribute and CallbackDebugBehavior attributes to modify their run-time behavior. The other attribute, ClientViaBehavior, can be used to separate the logical destination from the immediate network destination. In addition, duplex client callback types can use some of the service-side behaviors. For more information, see Specifying Service Run-Time Behavior.

Using the CallbackBehaviorAttribute

You can configure or extend the execution behavior of a callback contract implementation in a client application by using the CallbackBehaviorAttribute class. This attribute performs a similar function for the callback class as the ServiceBehaviorAttribute class, with the exception of instancing behavior and transaction settings.

The CallbackBehaviorAttribute class must be applied to the class that implements the callback contract. If applied to a nonduplex contract implementation, an InvalidOperationException exception is thrown at run time. The following code example shows a CallbackBehaviorAttribute class on a callback object that uses the SynchronizationContext object to determine the thread to marshal to, the ValidateMustUnderstand property to enforce message validation, and the IncludeExceptionDetailInFaults property to return exceptions as FaultException objects to the service for debugging purposes.

using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Threading;

namespace Microsoft.WCF.Documentation
{
  [CallbackBehaviorAttribute(
   IncludeExceptionDetailInFaults= true,
    UseSynchronizationContext=true,
    ValidateMustUnderstand=true
  )]
  public class Client : SampleDuplexHelloCallback
  {
    AutoResetEvent waitHandle;

    public Client()
    {
      waitHandle = new AutoResetEvent(false);
    }

    public void Run()
    {
      // Picks up configuration from the configuration file.
      SampleDuplexHelloClient wcfClient
        = new SampleDuplexHelloClient(new InstanceContext(this), "WSDualHttpBinding_SampleDuplexHello");
      try
      {
        Console.ForegroundColor = ConsoleColor.White;
        Console.WriteLine("Enter a greeting to send and press ENTER: ");
        Console.Write(">>> ");
        Console.ForegroundColor = ConsoleColor.Green;
        string greeting = Console.ReadLine();
        Console.ForegroundColor = ConsoleColor.White;
        Console.WriteLine("Called service with: \r\n\t" + greeting);
        wcfClient.Hello(greeting);
        Console.WriteLine("Execution passes service call and moves to the WaitHandle.");
        this.waitHandle.WaitOne();
        Console.ForegroundColor = ConsoleColor.Blue;
        Console.WriteLine("Set was called.");
        Console.Write("Press ");
        Console.ForegroundColor = ConsoleColor.Red;
        Console.Write("ENTER");
        Console.ForegroundColor = ConsoleColor.Blue;
        Console.Write(" to exit...");
        Console.ReadLine();
      }
      catch (TimeoutException timeProblem)
      {
        Console.WriteLine("The service operation timed out. " + timeProblem.Message);
        Console.ReadLine();
      }
      catch (CommunicationException commProblem)
      {
        Console.WriteLine("There was a communication problem. " + commProblem.Message);
        Console.ReadLine();
      }
    }
    public static void Main()
    {
      Client client = new Client();
      client.Run();
    }

    public void Reply(string response)
    {
      Console.WriteLine("Received output.");
      Console.WriteLine("\r\n\t" + response);
      this.waitHandle.Set();
    }
  }
}

Using CallbackDebugBehavior to Enable the Flow of Managed Exception Information

You can enable the flow of managed exception information in a client callback object back to the service for debugging purposes by setting the IncludeExceptionDetailInFaults property to true either programmatically or from an application configuration file.

Returning managed exception information to services can be a security risk because exception details expose information about the internal client implementation that unauthorized services could use. In addition, although the CallbackDebugBehavior properties can also be set programmatically, it can be easy to forget to disable IncludeExceptionDetailInFaults when deploying.

Because of the security issues involved, it is strongly recommended that:

• You use an application configuration file to set the value of the IncludeExceptionDetailInFaults property to true.

• You do so only in controlled debugging scenarios.

The following code example shows a client configuration file that instructs WCF to return managed exception information from a client callback object in SOAP messages.

  <client>
      <endpoint 
        address="http://localhost:8080/DuplexHello" 
        binding="wsDualHttpBinding"
        bindingConfiguration="WSDualHttpBinding_SampleDuplexHello"
        contract="SampleDuplexHello" 
        name="WSDualHttpBinding_SampleDuplexHello"
        behaviorConfiguration="enableCallbackDebug">
      </endpoint>
  </client>
<behaviors>
  <endpointBehaviors>
    <behavior name="enableCallbackDebug">
      <callbackDebug includeExceptionDetailInFaults="true"/>
    </behavior>
  </endpointBehaviors>
</behaviors>

Using the ClientViaBehavior Behavior

You can use the ClientViaBehavior behavior to specify the Uniform Resource Identifier for which the transport channel should be created. Use this behavior when the immediate network destination is not the intended processor of the message. This enables multiple-hop conversations when the calling application does not necessarily know the ultimate destination or when the destination Via header is not an address.

See also

• Specifying Service Run-Time Behavior