Exception Shielding #2: Customers Service

To illustrate the implementation of the Exception Shielding design pattern, we will use a sample based on very simple WCF service: the Customers Service.

This is a generic service that provides a single operation that allows the client to register new customers.

Design

The service design is quite simple. It follows the recommendations of the Web Service Software Factory and the architecture is represented by the following diagram:

Implementation

The service implementation, using the Service Factory and before Exception shielding, is very simple.

ICustomersService.cs:

using System;
using System.ServiceModel;
using ServiceSoftware.CustomersService.DataContracts;
using ServiceSoftware.CustomersService.FaultContracts;

namespace ServiceSoftware.CustomersService.ServiceContracts
{
    [ServiceContract(Name = "ICustomersService")]
    public interface ICustomersService
    {
        [OperationContract]
        void Create(Customer request);
    }
}

CustomersService.cs:

using System;
using System.ServiceModel;
using ServiceSoftware.CustomersService.ServiceContracts;

namespace ServiceSoftware.CustomersService.ServiceImplementation
{
    [ServiceBehavior(Name = "CustomersService")]
    public class CustomersService : ICustomersService
    {
        #region ICustomersService Members

        public void Create(DataContracts.Customer request)
        {
            CustomersServiceAdapter adapter =
                new CustomersServiceAdapter();
            adapter.Create(request);
        }

        #endregion
    }
}

CustomersServiceAdapter.cs:

using System;
using ServiceSoftware.CustomersService.BusinessLogic;
using ServiceSoftware.CustomersService.ServiceContracts;

namespace ServiceSoftware.CustomersService.ServiceImplementation
{
    public class CustomersServiceAdapter : ICustomersService
    {
        #region ICustomersService Members

        public void Create(DataContracts.Customer request)
        {

            // Translate data contract to a business entity

            Translator translator = new Translator();
            BusinessEntities.Customer customer =
                translator.TranslateDataContract(request);

            // Execute operation

            CreateCustomer manager = new CreateCustomer();
            manager.CreateCustomerAction(customer);

        }

        #endregion
    }
}

Expected Errors

A part from communication errors between the client and the service, there are a number of errors that can be anticipated for a service like this:

• The client tries to create a customer that already exists.
• The client sends a request to create a customer without providing the minimum required data (in this case the customer identifier and the customer name).

At the end of the day, considering that the service uses a SQL Server database to store the customers, these two expected errors are tied two errors that will be raised by the database.

You could consider a number of additional expectable errors - any error that an INSERT statement can produce in SQL Server - including any error resulting from additional validations in the business logic layer. For the sake of simplicity and because that's enough to illustrate the exception shielding pattern, you will consider only these two errors.

Shielding the Service

Exception Shielding becomes important in a service like this because:

• We don't want the client (or the user executing the client) to have to deal with SQL Server error messages (not so user-friendly).
• We don't even want him to know that we're using a SQL Server database.
• But we do want to present the user with simple messages that allow him to understand the error (and his mistake).

Basically, for the two errors in consideration, we want to present the following error messages:

• "The specified customer already exists."
• "The customer cannot be created because all the required that was not provided."

Any other error raised executing the operation should present the user with a generic message: "The request cannot be serviced because of an unexpected error.".

Next time: Exception Shielding in WCF