John W Powell : Design Pattern

Consume SharePoint Web Services with WCF using the Repository, Gateway, Mapper, Domain Model and Factory Design Patterns

johnwpowell — Sun, 04 Jan 2009 00:53:00 GMT

The SharePoint developer community has produced a wealth of knowledge and code samples that demonstrate how to consume SharePoint web services and leverage them in domain-specific applications. This information is often task-centric, such as "How to add an Item to a List using SharePoint Web Services." In this article, we will take a framework-centric approach and apply sound, fundamental object-oriented (OO) design principles to implement a reusable library for working with the SharePoint web services.

Motivation and Goals

My motivation for this article is to help you create a foundation for a framework that can be used in one, or reused across many SharePoint-integrated applications. I also want to demonstrate how good software design principles can (and should) be applied to SharePoint development, and confess my own sins for not always following them. For some reason, I often find myself thinking procedurally when developing a SharePoint customization. Perhaps it's because the product is a 70% solution and requires a different mindset and approach than a large greenfield software project does. Maybe customers expect results faster when you build it on SharePoint, and I've taken shortcuts to meet them. Or maybe I've just been lazy, but in any case, here are some of the issues I've seen or been responsible for:

Re-writing the same SharePoint code on each new project
Not refactoring within and across applications
Tightly coupling application code to the XML input and output from SharePoint services
Lack of a domain model; designing procedurally instead of applying domain-driven design (DDD)
Not having well-defined layers and strategies
Failure to design for testability and not writing unit tests

Here are some of the goals I would like to achieve with this framework:

Implement a domain model that is independent and decoupled from the SharePoint services
Define a set of patterns and strategies for communicating with the SharePoint services
Create a reusable library that can be used in many different domain-specific applications
Use DDD and Test-Driven-Design (TDD)
Apply good OO principals and patterns
Use Windows Communication Foundation (WCF)

Design

In the next section, I'll walk through the implementation and the process I went through to arrive at the design below. Generally speaking, I used DDD and TDD (where it made sense) and followed the Single Responsibility principle. If you are not familiar with this, it is often described as "a class should only have one reason to change." I call it the "and test." I describe the purpose of the class and if I have to use the word and, I consider refactoring some of the functionality to another class.

In the diagram below, the client application uses the repository and domain classes. The repository is responsible for retrieving domain objects based on criteria. The repository uses one or more service gateways to get the information it needs. The service gateway communicates with the SharePoint web services using a WCF client. The service calls typically return XML responses, and it is the job of the service response mapper to translate the XML to a domain object. Finally, the WCF client factory creates clients configured to call the SharePoint services.

Get the code

Implementation

In this example, the goal is to get all the lists in a given site. Following DDD, we will start the design in the domain layer and create a list class that has a title property:

Create the list repository class to define the method clients will call the get the lists in a given site:

Following TDD, we'll create a unit test that will fail until we implement the repository:

Return to the repository class and add the implementation to call the lists service gateway which we haven't created yet. How did I know to create a lists service gateway? I decided to have a gateway that corresponds to each SharePoint web service and did some research to find the exact service and method that would return the lists for a given site. The implementation below is very simple, but you can imagine a more complex repository that uses several service gateways and does some additional processing to construct a domain object graph.

Create the lists service gateway so the project will compile:

Create a failing unit test for the lists service gateway:

Next we'll add a reference to the SharePoint Lists service. Note: Visual Studio will add an app.config and a Properties > DataSources folder and you can delete both of them. We are going to configure WCF programmatically.

Return to the lists service gateway and fill in the implementation. Now I'm pulling a "Julia Childs" on you. I already went through several iterations of TDD and refactoring to arrive at the implementation below. Initially this method had all the code to call the web service, and there was no WCF client factory nor a mapper. After implementing this logic in several gateways, I refactored the commonality to classes. It made sense to have a factory to construct WCF clients in a consistent way and allow me to make a change in one place if I discovered something new. The Single Responsibility "and test" led me to refactor the mapping code to a separate class and the end result is a much cleaner implementation:

Next, we'll implement the WCF client factory. As you can see, it has been through a few iterations of TDD and refactoring starting with the service url class. This class contains constants and methods for working with SharePoint service urls. The other thing you'll notice is the the WCF configuration that is typically done in a configuration file is being done programmatically in the service binding factory class.

Here is the implementation of the service binding factory:

The gateway uses a mapper to map the XML response from the SharePoint web service to a domain object. The XML response is in the form of <element attribute1...n /> which, in this case, translates nicely to domain objects and properties. The code below uses Linq to find all List elements and for each one it calls MapInternal which creates a list object from the element:

Now if we return to the repository GetLists unit test, it passes and output each list title in the site:

Summary

In this article and walkthrough, I demonstrated how DDD, TDD, patterns and good OO principles can be applied to implement a framework that consumes SharePoint web services. Even though I focused on the web services, the SharePoint API can also be regarded as a service and the same fundamentals can be applied to developing applications that run on the server. I hope this inspires and helps you to implement your own framework and improve the quality and reuse of your SharePoint code.

Get the code

References and Additional Reading

Implementing the "Only Talk to Friends" pattern using the InternalsVisibleTo Attribute

johnwpowell — Fri, 09 May 2008 15:24:00 GMT

Did your parents ever tell you "don't talk to strangers?" They were trying to protect you, and even though you are all grown up now, that principle is still relevant--to the design of your software, that is. The basic idea is that classes should limit their surface area and not expose that which reveals implementation details. Let's go though an example to illustrate these concepts.

In a traditional layered architecture you logically divide components by responsibility. In this example, we will use a domain, business and data access logic layer each realized as a Visual Studio 2008 project. In our contrived architecture, we want the business layer to be the "gatekeeper" for retrieving customer domain objects. The business layer uses the data access logic layer to fetch a customer, so we might expose the data access class as a property of the business class as demonstrated here:

Here's the code to use this design:

So what's wrong with this approach? We have violated a core principal of object oriented design by exposing implementation details. Just like your parents protected you from strangers, classes should not expose their children or any other details about implementation. You may have heard of this concept by another name such as:

Don't Talk to Strangers
Principal of Least Knowledge
Demeter's Law

Consumers don't need to know how the CustomerBusiness fetches a Customer, it only needs to know that CustomerBusiness fetches a customer. So, let's revise the design using a technique called interface promotion. This involves hiding a child object and promoting all or some of its interface to the parent. The new design looks like this:

Here's the code to use the new design:

Only Talk to Friends

The responsibility of the business layer is to act as a "gatekeeper" and control access to the underlying layers. Although it might seem that we have accomplished our goal with this design, there is another issue that needs to be addressed. Remember the layered architecture? Business logic is in one project/assembly and data access logic is in another. In order for CustomerBusiness to use CustomerData, the methods in CustomerData must be public. The implication of this is a consumer can reference the data access layer and call it's public methods, bypassing any logic in the business layer. To solve this problem, I would like to introduce a technique that I call only talk to friends.

The intent of the only talk to friends pattern is provide a mechanism for an assembly to expose it's interface to specified friend assemblies. In our example, the data access logic layer would only expose it's interface to the business layer. In order to accomplish this, let's revisit the design and make the CustomerData class and its methods internal:

Now for the magic. Add the InternalsVisibleTo attribute to the AssemblyInfo.cs file in the Data project thereby exposing anything internal in the data access logic layer to the business layer.

The InternalsVisibleTo attribute exposes anything internal in one assembly to the specified friend assembly. It would be nice if we could be more granular than the entire assembly, but this approach will work well for most circumstances.

Sometimes It's OK to Talk to Strangers

There is one exception for breaking the "do not talk to strangers" principle, and that is unit testing. When we write the unit test for CustomerBusiness, we only want to test CustomerBusiness, not CustomerData or the database. In order to do this, we mock the CustomerData class. For this work, CustomerBusiness will need to provide a mechanism that allows the unit test to replace the CustomerData instance in CustomerBusiness. There are a few techniques for doing this such as dependency injection (and I do have an article planned on this subject), but one way is to allow CustomerData to be passed into the CustomerBusiness constructor as follows.

Note that the constructor that allows the data access object to be specified is internal. Once again, you use the InternalsVisibleTo attribute granting access only to the business layer unit tests.

Summary

I hope this article has reinforced the object-oriented principle "don't talk to strangers," and provided a modern spin, "only talk to friends," that you can add to your toolbox.