Introduction to Sitecore Patching

There are several instances when you make updates to your Sitecore.config file, changes can include:

  • Adding new pipelines and processors for any custom feature implementation.
  • Updating/overriding the default values for some of the setting values like cache sizes and etc.
  • Adding new Sitedefination for your Sitecore instances.

So, to make any of the updates mentioned above, we have to perform following task(s):

  • Code changes (class file updates) and/or
  • Configuration file(s) changes (this is to make sure we register the changes in Sitecore)

Once you are done with you class and config changes, we need to register the changes in Sitecore, this is required so that Sitecore can identify the changes you made, and the functionality works as expected.

There are two approaches for registering the custom updates in Sitecore:

  1. By adding/updating the config changes directly in Sitecore.config file (not recommended)  or
  2. Creating a patch file (with extension .config)  which includes all the changes required, and placing file under App_Config/Include folder, we can create separate sub folders as well.

 

ankit-sitecore-download

Both the approaches works fine as expected, but there is an issue with approach 1.

How would you handle the updates in Sitecore.config file when you are planning for an upgrade later?, provided that you made several changes to Sitecore.config file, it may results issues after the upgrade.(think about it carefully before making changes directly to default Sitecore.config file)

How about if we think about creating a patch file, and putting all our changes there?, and this works well even if you are going for an upgrade at later stage, as you are not adding/updating anything on default Sitecore.config file directly, all the custom changes are coming as part of your patch file(s), This also helps in easy maintenance and troubleshooting.

Patch files are merged with Sitecore.config in alphabetical order. This means configuration in a patch file named a.config will appear before configuration in a patch file named b.config.

If the same configuration is found in multiple patch files, the configuration from the last patch file processed is the configuration that is used.

We can create as many patch files as we want, it all depends on the feature/requirement(s) and the way you want to organize your configuration files in your solution.

For example – you can create separate patch file for any Import functionality we have in the system, and this includes all the settings that needs to be added for specific one, also, there can exists separate patch file which includes custom indexes if exists any?

Note: Patching only works on the Sitecore configuration section, no other file or section can be patched with this.

Place in solution where patch files are placed, i.e under “App_Config/Include” folder

/App_Config/Include/zCustom.config
/App_Config/Include/events/zCustomEvents.config
/App_Config/Include/etl/zCustomEtl.config

Sitecore patching can be used for following operation(s):

  1. Adding a new setting
  2. Deleting a setting
  3. Adding or updating an attribute.
  4. Inserting an element before a specific element.
  5. Inserting an element after a specific element.

Simple example of Sitecore Patching:

This will set the default database for your website to master, this helps in testing the application without publising changes to web db
(Make sure to revert it back once you are done- and never make this change in QA/Production)

Sitecore-patching

How to see the result after Patching?

Now, how we can see the file which includes all the patches which we have applied, there is no physical .config file which can be used, In order to see the final result, please use this URL

http://%5Byour-localhost-name%5D/sitecore/admin/ShowConfig.aspx

Sitecore patching is an important part of day to day development, and we should leverage this as much as possible, to make sure we can make the system more stable and maintainable.

You can learn more about Sitecore Patching here:

Thanks and let me know if you have any feedback/comments on the same.

Happy learning 🙂

Advertisements

Sitecore MongoDB Blog series: Part 3-Creating custom contact facets

In previous blog post, we gone through introduction of MongoDB with Sitecore which includes scaling, contacts and understanding MongoDB queries.

In this blog post we will go through and understand, how to create a custom contact facet and how to deploy it to Sitecore.

By default there are facets which Sitecore uses, and you can find the details here:

\App_Config\Include\Sitecore.Analytics.Model.Config

<entities>
<contact>
<factory type=”Sitecore.Analytics.Data.ContactFactory, Sitecore.Analytics” singleInstance=”true” />
<template type=”Sitecore.Analytics.Data.ContactTemplateFactory, Sitecore.Analytics” singleInstance=”true” />
<facets>
<facet name=”Personal” contract=”Sitecore.Analytics.Model.Entities.IContactPersonalInfo, Sitecore.Analytics.Model” />
<facet name=”Addresses” contract=”Sitecore.Analytics.Model.Entities.IContactAddresses, Sitecore.Analytics.Model” />
<facet name=”Emails” contract=”Sitecore.Analytics.Model.Entities.IContactEmailAddresses, Sitecore.Analytics.Model” />
<facet name=”Phone Numbers” contract=”Sitecore.Analytics.Model.Entities.IContactPhoneNumbers, Sitecore.Analytics.Model” />
<facet name=”Picture” contract=”Sitecore.Analytics.Model.Entities.IContactPicture, Sitecore.Analytics.Model” />
<facet name=”Communication Profile” contract=”Sitecore.Analytics.Model.Entities.IContactCommunicationProfile, Sitecore.Analytics.Model” />
<facet name=”Preferences” contract=”Sitecore.Analytics.Model.Entities.IContactPreferences, Sitecore.Analytics.Model” />
</facets>
</contact>
</entities>

In this specific example, we will show how to add a custom string value to existing contact card, we can call this Facet “Education

In order to create a custom Facet, we need following components:

  1. Interface (that’s used to create a contract/facet)
  2. Implementation
  3. Configuring the system to use new Facet.

Interface:

Education is the Facet, and the Education property we define for this is Element for this Facet,so we need to create Facet and Element interface.

Here is IProfileEducationFacet Interface, this should inherit IFacet.

IProfileFacet

Next step is to create IProfileEducationElement Interface, here is the sample snippet for the same:

IProfileEducationElement

Implementation:

Once we have Interfaces created for Facet and Element, next step will be to create class that can implement those interfaces.

ProfileEducationFacet class

ProfileFacet

ProfileEducationElement class

ProfileEducationElement

 

Once the Facets and Elements are created, next step will be to register these Facets and Elements in Sitecore, we also call this deploying to Sitecore.

In order to deploy these facets and Elements, we can either update the default configuration file, or we can also create a patch file, which will have changes specific to Education Facets.

Here is the patch file for ref:

FacetDeployPatch

<configuration xmlns:patch=”http://www.sitecore.net/xmlconfig/”&gt;
<sitecore>
<model>
<elements>
<element patch:after=”*[@interface=’Sitecore.Analytics.Model.Entities.IBehaviorProfileValue, Sitecore.Analytics.Model’]” interface=”Sample._Classes.xDBProfile.Elements.IProfileEducationElement, Sample.Sitecore”
implementation=”Sample._Classes.xDBProfile.Elements.ProfileEducationElement, Sample.Sitecore” />
<element patch:after=”*[@interface=’Sitecore.Analytics.Model.Entities.IBehaviorProfileValue, Sitecore.Analytics.Model’]” interface=”Sample._Classes.xDBProfile.Facets.IProfileEducationFacet, Sample.Sitecore”
implementation=”Sample._Classes.xDBProfile.Facets.ProfileEducationFacet, Sample.Sitecore” />
</elements>
<entities>
<contact>
<facets>
<facet patch:after=”*[@name=’Preferences’]” name=”Education” contract=”Sample._Classes.xDBProfile.Facets.IProfileEducationFacet, Sample.Sitecore” />
</facets>
</contact>
</entities>
</model>
</sitecore>
</configuration>

Getting and setting properties are done using GetAttribute and SetAttribute methods retrieved from Sitecore.Analytics.Model.Framework.Element and Sitecore.Analytics.Model.Framework.Facet.

Happy learning 🙂