Overview
In this article, we will cover basic things you should know before starting to work with the Fluent API.
Fluent API: Entry Point, Facades and Methods
The Sitefinity Fluent API could be used by referencing the Telerik.Sitefinity and Telerik.Sitefinity.Model namespaces. These namespaces are defined in the Telerik.Sitefinity.dll assembly.
Each Fluent API call starts with the App static class:
using Telerik.Sitefinity
..
var blog = App.WorkWith().Blog().CreateNew().SaveChanges();
..
Whenever you want to access the Fluent API methods, you should always start with the App class.
What is following is:
- WorkWith() method or
- Prepare() method
WorkWith() should be used when you use the default providers and you want to get to the specific Fluent API, like in our case - Blogs.
Prepare() should be used when you want to get to specific Fluent API, but want to use custom providers for the content types, taxonomies or pages.
Consider the following examples:
using Telerik.Sitefinity
..
//create a blog with the default blogs provider
var blog = App.WorkWith().Blog().CreateNew().SaveChanges();
..
and:
using Telerik.Sitefinity
..
//create a blog with a predefined custom blogs provider
var blog = App
.Prepare()
.SetBlogsProvider("XmlBlogs")
.WorkWith()
.Blog()
.CreateNew()
.SaveChanges();
..
Note how we have added Prepare().SetBlogsProvider() in the second example. You should always use Prepare() when you want to set different provider to work with, or even different transaction and scope for the database queries.
Saving/Discarding Changes
Each Fluent API call could end up with one of the following:
- SaveChanges()
- CancelChanges()
- Done()
SaveChanges() is saving all the changes in the database, it other words, it commits the transaction. This means that several fluent api statements could be initiated, and all actions will be commited at once when SaveChanges() is called. There is an overload of the SaveChanges() method - SaveChanges(bool UpgradeDatabase), which is used when structural changes to the database are made. This is needed for example when a new data types are created dynamically.
CancelChanges() discards any actions initated within the current call.
Done() is used within child facades. It saves the changes in the current scope, but the transaction is not runned until SaveChanges() is called. More information on this is available in Child Facades Topic
The changes could be saved in one more case - SaveChanges() is implemented on disposing fluent execution. Here is a code example:
...
using (var t = App.WorkWith())
{
t.Blog().CreateNew().Do(b => { b.Title = "Blog Title"; });
}
// the disposing occurs here
//SaveChanges() is executed internally, and the new blog settings are persisted.
This is especially useful if you want to make several operations at once. Let's say you want to work with several types of content items, but execute only one transaction:
using (var fluent = App.WorkWith())
{
// create 10 content items
for (int i = 0; i < 10; i++)
{
fluent.ContentItem()
.CreateNew()
.Do(ci =>
{
ci.Title = "Content item " + i.ToString();
ci.Author = "Ivan";
});
}
// create 20 events
for (int i = 0; i < 20; i++)
{
fluent.Event()
.CreateNew()
.Do(ev =>
{
ev.Title = "Event " + i.ToString();
ev.EventStart = DateTime.Now;
});
}
}
// all items will be commited automatically in one transaction upon the exit of the using block
For more information on the content creation, check Creating Content Items topic.