How to Send and Receive Faults in Workflow Services

Author: Cindy Song

Author(s) Cindy Song

Created 12/3/2009

Last Updated 1/22/2010

Reviewer(s) Emil Velinov, Chris Kurt, Tai Yee, Susan Joly

Approver(s) Dave Cliffe

Informed

This article describes how to set up and use custom faults in a .NET 4 workflow service.

IntroductionThe messaging activities in .NET 4 workflow services are responsible for establishing the contract between the service and the client. For more information, see Using Contracts in Workflow (http://msdn.microsoft.com/en-us/library/ee358741(VS.100).aspx). It is the same for setting up a fault contract. The SendReply activity can be configured to send a fault by specifying the message content or the parameter content to be of type FaultException or FaultException<T>.

Here is a common fault scenario: 1) the client sends a request to the service 2) the service determines the request is an invalid request 3) the service sends a fault back to the client. This article describes in detail how to configure a fault contract in the Visual Studio 2010 workflow designer for the preceding invalid request scenario.

In addition, setting up a declared fault using the Receive and SendReply activities is demonstrated. One can build multiple SendReply activities associated with a single Receive activity. Some of the SendReply activities will be for sending business replies back to the client, and these SendReply activities need to have consistent message/parameter content. The other SendReply acitivites can be used for sending different fault exceptions to the client, and these would have a single parameter in the content or a message content that is of type FaultException.

Note that in the case of an unhandled exception that occurs between a Receive and SendReply, the WorkflowServiceHost will automatically turn that exception into a fault. The fault will be raised as a FaultException on the client, although it will not contain any of the detailed exception information (unless includeExceptionDetailsInFaults is set to true on the ServiceDebugBehavior). The resulting workflow instance will be handled according to the host policy specified on the WorkflowUnhandledExceptionBehavior (default is AbandonAndSuspend).

Scenario

A workflow service receives a piece of data and validates the data. If the data is valid, then some logic is executed and a regular response is returned. If the data is invalid, then a fault is sent back to the client. In this scenario, the fault will be built with customized exception detail.

The xaml workflow service described below has a Receive activity, and two SendReply activities associated with the Receive. The if-then-else logic is set up for validating the input data. The last section of the paper describes how to test the example using a console app Client project. One should be able to see the customized message that is specified in the FaultException displayed on the console, when the fault is sent back to the Client.

Step-by-Step Instructions

Create a WCF Workflow Service Application Project1. In Visual Studio 2010, create a new project using the WCF Workflow Service Application

template. For the purpose of this exercise, name the project MyService and the solution FaultExceptionExample.

Create a new workflow service using the WCF Workflow Service Application template.

2. By default, the template creates a Sequential Service, which contains a pair of Receive and Send activities called “ReceiveRequest” and “SendResponse.” This is a .NET 4 workflow service, which contains a workflow with activities, some of which may be messaging activities with implicit WCF endpoints for communicating with other services or applications.

The default workflow service created by the template.

3. By default, several variables are created as well, which you should examine: click Sequential Service to focus the scope, and then click the Variables tab at the bottom of the main design canvas

The default variables created by the template.

4. Generate a second SendResponse activity associated with the existing ReceiveRequest activity: right-click ReceiveRequest, and then select Create SendReply. A new SendReply activity appears on the canvas.

Create SendReply from a Receive activity.

The second SendReply activity is generated.

5. Rename the messaging activities for clarity; a) click and highlight the activity title ReceiveRequest, and rename it to Receive Data Request b) rename SendReplytoReceiveRequest to Send Invalid Data Fault Exception and c) rename SendResponse to Send Data Response.

The workflow service with one Receive and two Send activities.

The activities are renamed for clarity.

6. Set up the if-then-else logic. For simplicity, let’s set up the following logic. If the received int is bigger than 0, then return the string format of the integer incremented by one. Otherwise, send a fault exception back.

To do this, drag and drop an If activity anywhere after the ReceiveRequest activity inside the Sequential Service; in the Condition box, type data > 0, drag and drop the Send Data Response activity into the box below Then, and drag and drop the Send Invalid Data Fault Exception activity into the box below Else.

If-Then-Else logic setup for the workflow service.

7. Save the file. 8. The details for each messaging activity will be set up in later steps.9. Change the project Web settings to “Local IIS Web Server” to enable WAS hosting for the new

service: right-click the project and select Properties, and then on the Web tab select Use Local IIS Web Server, and click Create Virtual Directory.

Toggle from Visual Studio Development Server to Local IIS Web server

Define a Custom Fault Exception Error Detail Type1. Create a new class file called RequestInvalidFault, which will contain the fault detail: right-click

the project MyService, add a new C# class, and name it RequestInvalidFault.

Create a new C# class

2. Define the fault class. Mark it with attribute DataContract. Define the property message as a data member. See the following code.

using System;using System.Collections.Generic;using System.Linq;using System.Web;

using System.Runtime.Serialization;

namespace MyService{ [DataContract] public class RequestInvalidFault { private string message;

public RequestInvalidFault(string message) { this.message = message; }

[DataMember] public string Message { get { return this.message; } set { this.message = value; } } }}

3. Save and build the project.

Set Up the Messaging Activities 1. In Service1.xamlx, see that the content of the “Receive Data Request” activity is pointing to the

“data” variable, by default. Note “Data” is a variable that the template generates by default. For this scenario, the only setup needed for this Receive activity is to specify the message type to be Int32.

Open the Content Definition dialog box by selecting the message activity, and then either clicking View Message or the “….” button next to Content in the property pane.

Configure the message content of the Receive Data Request activity.

2. By default, the content of the “Send Data Response” activity is “data.ToString()”. Set up this Send activity by selecting String as the message type.

3. Configure the other Send activity to use the custom fault type that was created earlier as the contract, by adhering to the following steps.

4. First, create a variable, myRequestInvalidFault, of type RequestInvalidFault, such that when the fault exception is initialized, it can point to this variable as the Detail type for <TDetail>. Make its default value “New RequestInvalidFault(“Invalid input. The input is smaller than 0.”)

Create a new variable.

5. Then, set up the fault contract in the “Send Invalid Data Fault Exception” activity. Use either Message content of type FaultException or Parameter content with a single parameter of type FaultException.

6. If you chose the latter option of Parameter content in the preceding step, perform the tasks in the steps that follow. .

7. Type in a name for the parameter, such as inputInvalidFaultException; when browsing a type, type FaultException into Type Name in the Browse and Select a .NET Type dialog box for faster searching.

Browsing for a type.

8. Choose FaultException<T> to specify custom error details, and then select MyService.RequestInvalidFault as T from the drop-down list.

Select the correct type and for any generics, select type from the drop down list.

9. Initialize a new instance as its value: “New FaultException(Of RequestInvalidFault) (myRequestInvalidFault)”, click OK, and then save and build the project.

Initialize the parameter value.

Configure the MEX Endpoint for the Workflow Service for Metadata Exchange1. By default, the web.config file is created with tagless or nameless service, meaning that there is

not a Service section in the default Web.config file. To add a MEX endpoint to expose the metadata for testing, add explicit service endpoints to the Web.Config file by opening the Web.Config from Visual Studio and then, inside the System.serviceModel tag, add the following:

<system.serviceModel>

<services> <service name="MyService1" > <endpoint address="http://localhost/private/MyService/Service1.xamlx" binding="basicHttpBinding" contract="IService"/> <endpoint address="" binding="mexHttpBinding" contract="IMetadataExchange" /> </service> </services>

<behaviors>…

2. Check if the service is up and running by going to http://localhost/myservice/service1.xamlx and seeing if the standard service message that starts with “You have created a service…” is at the beginning of the page.

Note The service has two endpoints: one is a MEX endpoint, and the other is an HTTP endpoint. When browsing the service via a web browser or when adding the service as a service reference, the service exchanges metadata via MEX endpoint.

Testing the Fault Contract 1. Examine the WSDL file: click the link to the wsdl file, for example, in the format of:

http://localhost/MyService/Service1.xamlx?wsdl. The WSDL file should be open in the browser. See that one of the messages defined is the fault message, and see that the operation has input, output, and fault elements.

WSDL file for the workflow service.

2. Add a Client project to the solution: in Visual Studio, right-click FaultExceptionExample in Solution Explorer, and then add a new Console App project called Client.

Adding a new project

3. Add a service reference from the client project

Adding a service reference

4. Write the Main function: open Program.cs in the Client project, use the following code as the Main function where the input is -5, add “using System.ServiceModel” and a reference to the dll in the Client project, and then build the project.

using System;using System.Collections.Generic;using System.Linq;using System.Text;

using System.ServiceModel;

namespace Client{ class Program {

static void Main(string[] args) { ServiceReference1.ServiceClient client = new ServiceReference1.ServiceClient(); int? data = -5;

// Use the 'client' variable to call operations on the service. try { client.GetData(ref data); Console.WriteLine("return val: " + data.ToString()); Console.ReadLine(); } catch (FaultException e) {

Console.WriteLine(e.CreateMessageFault().GetDetail< ServiceReference1.RequestInvalidFault>().Message);

Console.ReadLine(); }

// Always close the client. client.Close();

}

}}

5. Run the solution with the Client project as the startup project: with -5 being the input, the invalid request message should appear in the console. Try changing -5 to 5. 6 should be returned as the incremented number.