-
Notifications
You must be signed in to change notification settings - Fork 23
Configuration
Synthesis has one place for configuration: the Synthesis.*.config files located in your web site’s App_Config/Include folder. This file’s primary purpose is to configure the implementations used for Synthesis’ Provider Model, and the parameters for each provider. The Provider Model is how Synthesis allows customization of its behaviors, such as which templates get objects generated for them or how to translate a Sitecore field name into a Synthesis field type.
Synthesis can have up to 4 config files. Synthesis.config belongs everywhere. Synthesis.ControlPanel.config and Synthesis.Startup.config can be removed in a CD environment. Synthesis.Mvc.config is for Sitecore MVC sites.
Out of the box Synthesis comes with a set of very flexible providers. These providers are configurable by using the very powerful configuration grammar Sitecore provides. The stock Synthesis.config file includes all possible parameters for each standard provider and is heavily commented. This document won’t be covering each parameter in detail, so make sure to look over the configuration file. If you choose to implement your own provider, you may implement a different set of parameters. Synthesis has five different types of provider. Let’s take a closer look at each one.
In Synthesis lexicon the Generator is the component that generates the concrete and interface implementations of a Sitecore template. The Generator Parameters Provider then is a provider that configures where and how the generator emits code, such as namespaces, output file paths, and the base class of all concrete model objects. This provider must implement the Synthesis.Generation.IGeneratorParametersProvider interface. The default implementation just maps the provided parameters onto the properties of the Synthesis.Generation.GeneratorParameters class.
Synthesis needs to be given a set of templates from which it should generate an object model or compare against when checking if the model is synchronized. It also needs to know which fields on those templates are valid model properties and which should be ignored – for example, you probably don’t need a property for Sitecore’s Icon field. This is the purpose of the Template Input Provider. This provider must implement the Synthesis.Templates.ITemplateInputProvider interface. The default implementation uses a ridiculously flexible system where you can include or exclude templates and fields in almost any way imaginable – by path, name, ID, or even wildcards. The default Template Input Provider has over 70 integration tests to check if it’s behaving correctly – it’s that flexible. The configuration grammar for the default provider is documented in the stock configuration file.
Note: Because of their additive nature, you may find that interfaces are generated for templates you have excluded using the Template Input Provider. This will occur if a template that is included for generation derives from a template that is not included. You can use this to your advantage by not including “abstract” templates that you don’t want a concrete implementation of and still having their interface available via a derived template’s implementation.
When a template synchronization check runs, Synthesis needs to know which .NET types could possibly contain Synthesis generated objects. Similarly, when the Presentation Framework looks for custom Presenters, it needs to have a list of candidate .NET types where presenters could live. This is the purpose of the Type List Provider. The provider returns a superset of classes that could include generated objects or presenters, and should cache the set of objects for later quick retrieval. Implementations must implement the Synthesis.Configuration.ITypeListProvider interface. There are two default implementations of this provider: Synthesis.Configuration.AppDomainTypeListProvider returns the complete set of types loaded into the entire AppDomain and is guaranteed to find all types in any loaded assembly. It requires no configuration, but adds a marginal amount of time (200ms-1s) to the web application’s startup time. Synthesis.Configuration.ConfigurationTypeListProvider takes a more precise approach, allowing you to specify exactly which assemblies you want to search for types in using a configuration grammar. It is several times faster than the AppDomainTypeListProvider, but may require reconfiguration during refactoring.
When the Generator processes a field on a Sitecore template, it has to be able to figure out what .NET type it should use to represent that field. This is where the Field Mapping Provider comes in. The Field Mapping Provider implements a conversion mapping between a Sitecore field and a .NET type. This provider is one of the most powerful customization points Synthesis offers – you can change the mapping to your own class and implement custom behaviors for a field type across your entire model. All of the default field classes use largely virtual properties and methods to allow you to easily patch their behaviors. This provider must implement the Synthesis.FieldTypes.IFieldMappingProvider interface. The default implementation uses an XML grammar similar to Sitecore’s FieldTypes.config file to map a template field name such as “Single-Line Text” to a .NET type such as Synthesis.FieldTypes.TextField, and is documented in the stock configuration file.
Synthesis has the ability to compare its generated object model to the current state of templates in Sitecore and look for differences. It accomplishes this by storing a signature value for each template in an attribute on the generated interfaces. When a comparison occurs, the signature is calculated for the template in Sitecore and then compared with the stored signature on the interface; if they match, the template is considered to be synchronized. This is where the Template Signature Provider is used; this provider creates a unique signature for a template’s current state. Provider implementations must implement the Synthesis.Templates.ITemplateSignatureProvider interface. The default provider implementation creates a SHA-1 hash of the template's name, path, ID, and the names and IDs of each field on the template.
This class controls how Sitecore template field names are converted into index field names for Sitecore 7 LINQ querying. The default provider, Synthesis.ContentSearch.Lucene.LuceneIndexFieldNameTranslator, uses field naming rules for the Lucene provider. At present there is no analog for the SOLR provider but it would be easy enough to write.
This translator must match the field translation rules used by Sitecore for your indexing technology (in implementations of Sitecore.ContentSearch.AbstractFieldNameTranslator, which unfortunately requires an Index context which we don't have so hence a parallel interface).