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!
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!