Fluent Interface to Simplify an API

The mail goal of an API is to facilitate the use of commands and attributes to achieve certain functionality.  Over time, an API may have evolved and become somewhat obscure on its usage which reduces its usability and increases the implementation time.

To clean/simplify an API you can apply a fluent interface to it. This allows you to modify the API with a more descriptive interface which improves its usability. At the same time, this preserves the current API interface and eliminates the risk of introducing bugs to code that is already implemented.  To get a better understanding, let‘s take a look at an order system. To create an order, an API often uses the following code:

//customer and order detail
Customer cust = new Customer() { CustomerId = 12900 };
OrderItem item1 = new OrderItem { Name = "Pen", PricePerUnit = .99, Quantity = 10, Sku = "1675" };
OrderItem item2 = new OrderItem { Name = "Notepad", PricePerUnit = 2.99, Quantity = 10, Sku = "5456" };
OrderItem item3 = new OrderItem { Name = "Marker", PricePerUnit = 1.99, Quantity = 10, Sku = "9836" };

//standard API to create the order
OrderHeader oh = new OrderHeader();
oh.Customer = cust;

That code sample is a simple API order system that is creating an order request with three items. You may argue that the code is really simple to follow, and there is no need to refactor, and I agree with you. However, we should think of a more complex API which may require you to add so many lines of code and call methods that are not that descriptive. With that in mind, let’s look now at how we can make the order creation a bit fluent:

//Fluent API

You can see that the code reads more like a sentence or language than actual method calls. It is descriptive and easier to use which is our main goal.  So how does the code for this look?  Well, let’s see now:
/// <summary>
/// defines a domain specific interface
/// </summary>
interface FluentOrderHeader
FluentOrderHeader WithItems(params OrderItem[] item);
FluentOrderHeader WithCustomer(Customer cust);
void CompleteAndSend();


/// <summary>
/// partial class to expose fluent api
/// </summary>
partial class OrderHeader : FluentOrderHeader
public static FluentOrderHeader CreateOrder()
return new OrderHeader();

public FluentOrderHeader WithItems(params OrderItem[] items)
foreach (OrderItem item in items)
return this;

public FluentOrderHeader WithCustomer(Customer cust)
this.Customer = cust;
return this;

public void CompleteAndSend()


We first define the interface with the methods that can help our API become fluent.  You should note that each call returns the instance reference. This allows for the chaining of the methods.  The next step is to create a partial class of the OrderHeader that implements our interface. This allows us to isolate the changes to the partial class without making any modifications to the current code. This new class handles the implementation changes using the existent API.

In my opinion, a fluent interface should be used to simplify obscure APIs which are often used in several projects. If the API is only use by one system, the effort to adapt a fluent interface may not be necessary. We need to keep in mind that a fluent implementation requires a bit more thinking, so it can actually provide a descriptive and fluent set of methods which allows any developer to easily follow it. Do not confuse this with just method chaining. The main different between method chaining and fluent interface is that with the latter we are trying to define a domain specific language that tries to target a specific task. Method chaining just facilitates the use of APIs by returning a reference, so it can be used in subsequent calls.


Add a Custom List on Office 365 Developer Preview

The way to add a custom list on the Developer preview (SharePoint 2013) is a bit different than adding the custom list on SharePoint 2010. The option to add a list is bundled under the concept of an app. From your team site, add a custom list by following these steps:

  • Click on Site Contents

  • Click on add an app

  • Click on Custom List

  •  Enter the list name

The rest of views to further configure the list are similar to the ones from the 2010 version. The ribbon and options are basically the same. The biggest difference to notice is the design of the pages.

List properties
Office 365 Ribbon

Application Hosting Models for SharePoint 2013

SharePoint 2013 provides developers with the following hosting models for their custom applications:

SharePoint-Hosted apps

These applications are JavaScript based applications that are hosted on a SharePoint website (host web). These applications have access to SharePoint artifacts like list and Web Parts. No server-side code is available for these applications. This model is a perfect fit for client side widget implementation and pages that can interact with lists using the Client Object Model.

Provider-Hosted apps - Cloud Hosted

These applications are hosted outside the SharePoint farm, but they can use the resources and services from SharePoint by using the SharePoint Client Object model or the REST/ODATA-based web services. Since these apps are not hosted on SharePoint, they need to use OAuth tokens to obtain access. The hosting of these applications can be done on windows Azure or any other hosting location. The development team is responsible for the provisioning of these applications which is the main difference to the Autohosted mode.

Autohosted apps – Cloud Hosted

These apps are hosted on Windows Azure Web sites. Similar to Provider-Hosted apps, these applications can also interact with SharePoint using the same standards for resource utilization and security. The provisioning of these apps is done automatically when the application is installed. Each one of these apps requires a new Windows Azure Web site.

Hybrid-Hosted Apps

This is a combination of SharePoint-Hosted and cloud-hosted components. An example would be an application that uses an external application to read information which can then be inserted into a SharePoint list.



The Sandboxed Code Host Service was too busy to handle the request

When trying to add a SharePoint sandbox webpart on a page, you may get this error:

"The sandboxed code execution request was refused because the Sandboxed Code Host Service was too busy to handle the request"

This error takes place for custom solutions, so you can still add other webparts, but not your custom sandbox webpart. This problem is usually present on the development environment because SharePoint can't check certificate revocation. The quick way to address this is to redirect the url to the local environment.

Open the host file and add this entry: (host file should be at system32/drivers/etc) crl.microsoft.com

Save the host file and re-start the SharePoint 2010 User Code Host Service. You can now try to add the webpart to a page.  The webpart should get added. You should now be able to also debug your webpart from Visual Studio.

Please note that this solution is only applicable for development environments. This is not recommended for production environments.