I have had a lot of fun lately installing and playing around with different object mapping frameworks for Sitecore. We, as Sitecore developers, have some great options thanks to the hard work of others in the community. After a lot of configuration and testing I decided to use Synthesis as my ORM for an upcoming project.
Synthesis is very easy to install via a Nuget package and it works out of the box if you will be working directly out of the Sitecore web root. However, as many others in the Sitecore community have mentioned, working directly out of the Sitecore web root is not always the best option. In fact it’s quickly becoming a best practice to separate your code from the base install of Sitecore (Excellent 2 part blog post about this set-up). Here at bv02 (my place of employment) we always follow this best practice when setting up a new project and use TDS to move the necessary files to the Sitecore web root on build. This means that in order for me to use Synthesis in a real world project I needed to find a way to get it working outside the web root. Thankfully the configuration file for Synthesis allows you to make the necessary changes and you can use Synthesis outside the web root without too much trouble at all!
Installing Synthesis
First off, if you are working outside the web root and attempt to install the Synthesis Nuget package in your Visual Studio project then you will quickly find out that this is not going to work straight away (That’s what I did). After thinking about it for a moment I realized that this makes perfect sense.
Let’s take a look at the instructions for manually installing Synthesis instead of using the Nuget package. This shows us that we need to add a Sitecore config file, an assembly, and register a HttpHandler and HttpModule in the web.config. We need to make these additions and changes to our Sitecore web root (ie: Under the “\Website” folder wherever your Sitecore instance is installed).
After following the manual installation, you should now be able to access the Synthesis control panel at “[sitecoreProjectUrl]/synthesis.axd” which allows you to trigger a rebuild of the auto-generated model files and also see if they are in sync with your Sitecore template items.
It is important to note that you will need to ensure that the dynamic debug compilation attribute is set to true in your web.config file or the option to rebuild the model files will not be visible in the Synthesis control panel.
Configuration changes to the Synthesis.config file
However, at this point if you attempt to generate the model files you will notice that they are added to the “/Website” folder in your Sitecore installation. This is not at all what we want! Instead we want the auto-generated Synthesis.Model.cs and Synthesis.Model.Concrete.cs files to be added to our Visual Studio solution that resides outside of the Sitecore web root. In order to fix this let’s jump into the Synthesis.config file that you added to the “App_Config\Include” folder of your Sitecore installation.
The Synthesis.config file is fairly extensive and gives us a lot of great configuration options but to begin with we are only interested in the ItemOutputPath setting and the InterfaceOutputPath setting. These two settings allow you to change the output path for the auto-generated Synthesis.Model.cs and Synthesis.Model.Concrete.cs files! Point the paths to your Visual Studio working directory and then regenerate the files using the Synthesis control panel at “[sitecoreProjectUrl]/synthesis.axd”.
While you’re in the Synthesis.config file, take a moment to set which Sitecore templates you want included in your model. You can include/exclude templates or fields using the includedPaths, excludedTemplates, and excludeFields settings.
That’s it! You should now be able to see the newly generate files (Synthesis.Model.cs and Synthesis.Model.Concrete.cs) in your Visual Studio project. Just make sure to include the files in the project, rebuild, and start coding with the help of Syntheis.
This type of set up is perfect for me since it leaves Synthesis installed on my local instance of Sitecore but will not deploy any Synthesis configuration files to the QA, staging or production instances of the site when I deploy with TDS. The Synthesis.Model.cs and Synthesis.Model.Concrete.cs files get compiled into the project assembly and deployed with the rest of the code! Perfect!
Big thanks to @kamsar for building this framework. Next, I look forward to testing out one of his other projects called Blade which helps separate out the logic from Sitecore renderings.
Sitecore.Context.Item 
Great post Scott!
The reason for the under-webroot default config is an attempt to lower the configuration barrier to entry by having defaults that ‘just work’ out of the box. Of course that didn’t just work here so maybe I need to rethink that! In actual sites we do store the generated files in a separate project as it doesn’t really make sense to store the model alongside the website.
Perhaps I should work on some sort of getting started experience for when you first install that walks you through config settings you probably need to change.
You’ll still need Synthesis.config on your deployed environments, or at least a few aspects of it, particularly if you’re using LINQ-to-indexes with it. Most of it is not relevant in prod though.
Thanks for the tip about Synthesis.config on deployed instances. I should be able to include the config file in my VS project so it gets deployed with the rest of the code through TDS. I’ll test that out and update the post.
I 100% agree with your decision to have the default configuration use the “under the web root” approach. I think the majority of people are still working that way anyways – which is totally fine. When I first started playing around with Synthesis that is how I installed it since it’s fast to get up and running for a test site.
I think it would be more than enough if you just added a small paragraph to the documentation that speaks to working outside the web root. As long as it’s clear that it is possible then it’s not a huge issue to go through the manual install. The biggest thing for me was that while I was evaluating Synthesis I was not sure I was going to be able to get this to work outside the web root. It almost scared me off.
Anyways, Thanks again. I really like using Synthesis so far! The most important thing is it makes coding more fun which is good motivation for me and my team.