The Sitecore API vs Glass.Mapper vs Synthesis
February 11, 2019
One of the basic functions of Sitecore is to store content in a database-driven backend and display it on webpages or external applications. A lot of heavy lifting is done in between, including one of the most important: mapping content and data to objects that the presentation layer can understand.
Accessing content in code is straightforward with the Sitecore API. This is the out-of-the-box API provided by Sitecore.Kernel.dll. It gets the job done, but it can be clunky to use for large codebases. While the Sitecore API should be known and understood by all Sitecore developers, most developers utilize an ORM ("object-relational mapping") tool to simplify some of the development process.
Mapping tools turn database-driven Sitecore items into ready-to-use models in C# code. Glass.Mapper is by far the most popular ORM for Sitecore thanks to its ease of use and extensibility, but there are other options. Let's look at and compare three common tools for mapping content in Sitecore: the Sitecore API itself, Glass.Mapper, and Synthesis.
I'll be comparing these tools in various ways, from setup to daily use to raw performance. All of these have options to support the Experience Editor, which is crucial for any Sitecore ORM or mapping strategy.
The Sitecore API provides near-direct access to item fields without writing raw SQL statements against the database (yeah... don't ever do that). It's a mature, well-tested API that has been a part of the core product for a long time. The API is the "low level" and "native" way to grab content from items - and also very fast. It doesn't get any simpler:
var item = Sitecore.Context.Database.GetItem("/sitecore/content/consoles/switch"); string name = item.Fields["ConsoleName"]; DateTime released = (DateField)item.Fields["ReleaseDate"];
If I were building a model from the above content, I would probably have more work to do. I would want to cast the content to a specific datatype, and of course I'd want to do some basic validation on the content before using it. Some Sitecore fields need to be cast or converted to different datatypes before being used; some of these are simple C# types (string, integer), others are custom Sitecore types (MultilistField, DateField, etc.).
Creating POCO models for domain and display logic is up to the developer, which provides maximum modeling flexibility at the cost of (usually) writing boilerplate code.
Getting Started (Sitecore API)
Getting set up to use the Sitecore API is simple. Developers will already be referencing common Sitecore assemblies such as Sitecore.Kernel.dll, which provide all the APIs required for loading and manipulating content (Sitecore.ContentSearch.dll).
While it's trivial and quick to load content with the API, Sitecore has plenty of "gotchas" to consider. For example, the value of the Sitecore context (
Sitecore.Context) greatly affects where content is loaded. Another example: how a developer calls
GetItem() changes based on information architecture strategies used inside Sitecore. Developers should implement design patterns that isolate the monotonous work of loading content, parsing fields, validating data, and mapping to models.
One easy way to help developers parse and safely access content fields is to create extension methods on the Sitecore
Item object. This keeps code API compatible, while allowing helper methods to do the bulk of the type-checking and casting.
Glass.Mapper's core feature is its best: mapping Sitecore content items to POCOs.
var context = new MvcContext(); var console = mvcContext.GetItem<GameConsole>("/sitecore/content/consoles/switch"); string name = console.ConsoleName; DateTime released = console.ReleaseDate;
In just two lines of code with Glass, I have a type-safe model with my item's fields ready to be used (there are more nuances to it, but this is a simple example). Once an item has been mapped, the POCO model has no connections back to Sitecore - it can be used as-is, passed around, and manipulated without any additional database calls. The actual POCO models can be created by hand or generated using external tools (TDS can do this).
Glass.Mapper is open-source, mature, and easily one of the most-popular mapping frameworks for Sitecore.
Getting Started (Glass.Mapper)
Glass is easy to install, setup, and use in Visual Studio. In short:
- Install the Glass.Mapper NuGet package
- Create concrete POCO models (or interfaces for proxy classes)
- Decorate your models with attributes to map to Sitecore templates and fields
- Start using the Sitecore or Glass API to load and map data
The Synthesis mapping framework makes mandatory what Glass considers optional: model/code generation. Rather than a developer decorating a custom POCO, Synthesis generates models directly from Sitecore templates. These strongly-typed models can then be used in a solution with no further modification:
Item item = Sitecore.Context.Database.GetItem("/sitecore/content/consoles/switch"); IConsoleItem console = item.As<IConsoleItem>(); string name = console.ConsoleName; DateTime released = console.ReleaseDate;
Conceptually speaking, the above code lands somewhere between the Sitecore API and Glass. Synthesis starts with a standard Sitecore
Item object and uses the
.As() extension method to map to the pre-generated
IConsoleItem type. Again, there are more nuances to consider, but at a high level we have a strongly-typed model ready to use with minimal code.
Like Glass, Synthesis is open-source, mature, and well-proven in the Sitecore development community.
Getting Started (Synthesis)
Synthesis sets up a lot like Glass, but with a few key differences. A high-level setup looks like this:
- Install the Synthesis Nuget package
- Configure Synthesis to recognize Sitecore templates for mapping
- Run a model generation via
- Import the model to your solution
- Load items from Sitecore and map them to Synthesis objects
Read part two of this series to compare the setup process, developer learning curve, and day to day usage of each ORM tool.
Do you have questions, comments, or corrections for this post? Find me on Twitter: @SitecoreSpark