FluentSP – The Fluent SharePoint API

12/10/2011 Date: 1:54:00 AM Posted By SharePoint

Download FluentSP 1.0 from Codeplex.com

Once you are doing a lot of SharePoint programming you know you often have to write lengthy pieces of code to implement simple tasks like querying SharePoint lists. Nowadays you can read a lot of fluent APIs or fluent interface. For instance, jQuery, a JavaScript library that had successfully introduced a fluent API to handle the hierarchical structure of the HTML documents.

Today, I want to introduce a small library I have developed, FluentSP, a modern fluent interface around the classic SharePoint 2010 API. By using FluentSP instead of the classic SharePoint API, you will be able to chain methods and act on sets of items of the underlying SharePoint objects.

What is a fluent API?
Checkout this CodeProject article A Look at Fluent APIs and the Wikipedia article Fluent interface.

To start into the fluent API you call the Use() method on SPSite, SPWeb, SPWebCollection or SPListCollection. The Use() method is implemented as an extension method that will return the entry facade object (see facade table below). Another entry point to the fluent API is the static class SP with its static methods CurrentSite, CurrentWeb, CurrentLists or RootWebLists.

view source
print?
1 SPContext.Current.Site.Use()... // => Returns the SPSiteFacade as entry point
2
3 // OR:
4 SP.CurrentSite()... // => Returns the SPSiteFacade as entry point

Using the entry facade instance you can start chaining the available facade methods as follows:

view source
print?
1 SP.CurrentSite().Web("Home").List("Tasks").Items().ForEach(i => // Do something with the item i of type SPListItem...);
2
3 // OR:
4 SP.CurrentSite()
5 .Web("Home")
6 .List("Tasks")
7 .Items()
8 .ForEach(i => // Do something with...);

Each facade object is actually wrapping an underlying data item, for instance the SPSiteFacade class is the fluent wrapper of the SPSite class. Depending on what kind of facade methods you are calling the method is returning either the current facade instance (e.g., ForEach() or Where()) or the method is returning a new child facade object (e.g. Items()). During the process of chaining methods in such a way you will build up a tree or hierarchy of facade instances. In order to step back to the parent or previous facade instance you need to call the End() method:

view source
print?
1 site.Use()
2 .RootWeb()
3 .Site()
4 .End() // Returns SPWebFacade as parent facade
5 .Site()
6 .End() // Returns SPWebFacade as parent facade
7 .End(); // Returns SPSiteFacade as parent facade

FluentSP is currently missing a number of possible useful methods, but you can easily extend the FluentSP API with custom facade classes and extension methods, see below and source code for implementation examples.

Samples

view source
print?
1 SPSite site = SPContext.Current.Site;
2
3 // ----------------------------
4
5 // Outputs titles of all lists of the root web where the list title starts with T
6 site.Use().RootWeb().Lists().Where(l => l.Title.StartsWith("T")).ForEach(l => Console.WriteLine(l.Title));
7
8 // Outputs titles of all lists of the root web where the list title ends with a ts (using RegEx)
9 site.Use().RootWeb().Lists("ts$").ForEach(l => Console.WriteLine(l.Title)).Count(out c);
10
11 // Outputs titles of all lists of the root web in ascending order where the starts with T
12 site.Use().RootWeb().Lists().Where(l => l.Title.StartsWith("T")).OrderBy(l => l.Title).ForEach(l => Console.WriteLine(l.Title));
13
14 // Outputs titles of all lists of the root web in descending order where the starts with T
15 site.Use()
16 .RootWeb()
17 .Lists()
18 .Where(l => l.Title.StartsWith("T"))
19 .OrderByDescending(l => l.Title)
20 .ForEach(l => Console.WriteLine(l.Title));
21
22 // ----------------------------
23
24 // Delete all items in the Members list, then add 7 new members and then select and output
25 // the titles of a few of the newly created items
26 site.Use()
27 .RootWeb()
28 .List("Members")
29 .Do(w => Console.WriteLine("Deleting all members..."))
30 .Items()
31 .Delete()
32 .End()
33 .Do(w => Console.WriteLine("Adding all members..."))
34 .AddItems(7, (i, c) => i["Title"] = "Member " + c)
35 .Items()
36 .Skip(2)
37 .TakeUntil(i => ((string)i["Title"]).EndsWith("6"))
38 .ForEach(i => Console.WriteLine(i["Title"]));
39
40 // ----------------------------
41
42 // Search for lists that are created by specific a user and depending on the results
43 // displays different messages by calling the IfAny or IfEmpty methods
44 site.Use()
45 .RootWeb()
46 .Lists()
47 .ThatAreCreatedBy("Unknown User")
48 .IfAny(f => f.ForEach(l => Console.WriteLine(l.Title)))
49 .IfAny(l => l.Title.StartsWith("M"), f => Console.WriteLine("Lists found that starts with M*"))
50 .IfEmpty(f => Console.WriteLine("No lists found for user"))
51 .End()
52 .Do(w => Console.WriteLine("---"))
53 .Lists()
54 .ThatAreCreatedBy("System Account")
55 .IfAny(f => f.ForEach(l => Console.WriteLine(l.Title)));
56
57 // ----------------------------
58
59 var items = new List<SPListItem>();
60
61 // Query with Skip and TakeUnitl methods
62 site.Use().RootWeb().List("Members").Items().Skip(2).TakeUntil(i => i.Title.EndsWith("5")).ForEach(i => { items.Add(i); Console.WriteLine(i.Title); });
63
64 // Query with Skip and TakeWhile methods
65 site.Use()
66 .RootWeb()
67 .List("Members")
68 .Items()
69 .Skip(2)
70 .TakeWhile(i => i.Title.StartsWith("Member"))
71 .ForEach(i => { items.Add(i); Console.WriteLine(i.Title); })
72 .End()
73 .Items()
74 .Where(i => i.Title == "XYZ")
75 .ForEach(i => { items.Add(i); Console.WriteLine(i.Title); });
76
77 // ----------------------------
78
79 // Adds new items using the Do method with the passed facade object
80 site.Use()
81 .RootWeb()
82 .AllowUnsafeUpdates()
83 .List("Members")
84 .Do((f, l) => {
85 for(int c = 1; c <= 5; c++)
86 f.AddItem(i => i["Title"] = "Standard Member #" + c);
87 })
88 .AddItem(i => i["Title"] = "Premium Member")
89 .Items()
90 .OrderBy(i => i.Title)
91 .ForEach(i => Console.WriteLine(i["Title"]));

Extensibility Samples

view source
print?
1 // This sample is using the ThatAreCreatedBy extension method defined in Extensions.cs to show how to extend the fluent API
2 site.Use()
3 .RootWeb()
4 .Lists()
5 .ThatAreCreatedBy("System Account", "jbaurle")
6 .Count(c => Console.WriteLine("Lists found: {0}", c))
7 .ForEach(l => Console.WriteLine(l.Title));
8
9 // This sample uses the new SPWebApplicationFacade extenion defined in SPwebApplicationFacade.cs to show how to extend the fluent API
10 site.WebApplication.Use()
11 .Sites()
12 .ForEach(i => Console.WriteLine(i.Url));
13
14 // This sample uses an alternative implementation for SPSiteFacade defined in SPSiteFacadeAlternate.cs to show how to extend the fluent API
15 site.WebApplication.Use().WithFirstSite().DoSomething();
16 site.Use<SPSiteFacadeAlternate<BaseFacade>>().DoSomething();

The custom method ThatAreCreatedBy which is used in the first query of the extensibility samples is implemented as follows:

view source
print?
1 static class Extensions
2 {
3 public static SPListCollectionFacade<TParentFacade> ThatAreCreatedBy<TParentFacade>(this SPListCollectionFacade<TParentFacade> facade, params string[] names)
4 where TParentFacade : BaseFacade
5 {
6 // NOTE: This sample uses the GetCollection method of the given facade instance to retrieve the current
7 // collection and adds the its query (see LINQ Deferred Execution). The Set method updates the
8 // underlying collection. The GetCurrentFacade method will then return the current facade to allow
9 // method chaining.
10
11 if(names.Length > 0)
12 facade.Set(facade.GetCollection().Where(i => names.Contains(i.Author.Name)));
13
14 return facade.GetCurrentFacade();
15 }
16 }

For more samples and details check out the source code you can download from Codeplex.

Built-In Facades and Methods

See Codeplex



Tag: , ,