What is patching?
Best practice nowadays is to keep your Sitecore.config file completely untouched. Do not directly change settings found here. Do not add new settings either. Patching allows you to modify existing settings and add new settings to the Sitecore.config without ever directly touching the Sitecore.config file itself. Patching will help you deduce whether something is wrong with your instance due to the fresh install process or due to custom settings needed for your particular solution. It will also help make subsequent upgrades even easier too by moving all the custom changes somewhere else.
How do you patch?
Simply create a config file that gets deployed to the App_Config folder. All your custom changes do not have to be in a single patch file. You can create as many patch files as you like. My recommendation is to follow Helix best practices here. If you are patching a new setting related to something foundational, you should patch it inside the App_Config/Foundation area.
Let’s take a look at a sample patch file. See the code below:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<sitecore>
<services>
<configurator type="Feature.SampleProject.IoC.ArticleConfigurator, Feature.SampleProject" />
</services>
</sitecore>
</configuration>
When this is deployed, Sitecore will look for the <services> node. It will then add this configurator to the <services> node. If a <services> node was not found, it would then create one in Sitecore.config. If you need to run a certain process before another one, you can specify to patch it in a certain position with attributes such as patch:before or patch:after. You can read more on this in the Sitecore documentation here.
Creating patch files during the upgrade process
If your solution is already making good use of patching, you likely won’t have to worry about doing anything in this blog post. You are lucky. Others not so much. If your solution is not patching, you will want to go ahead and get the jump on this during the upgrade process. To successfully introduce patching, I highly recommend downloading a text compare tool like Beyond Compare.
In your currently live Sitecore version, navigate to <host_name>/sitecore/admin/showconfig.aspx in your browser. Copy all of the XML found there. Then do a text compare to find the differences between the customized Sitecore.config and a fresh untouched Sitecore.config for the same Sitecore version. When patching a solution for the very first time during an upgrade, I recommend creating one config file to house all the settings you are patching. You can save separating out the patch file into multiple files as a post-upgrade activity.
After creating this patch file housing all the custom settings, you can then deploy it to your fresh install of the Sitecore version you are upgrading to. After doing so, you may run into several errors of DLLs missing, etc. Once you have deployed your upgraded code (later in this series), you can then see if Sitecore still continues to fail to load in the browser. If you cannot figure out why it won’t come up, try removing the deployed patch file. Then check to see that Sitecore comes up. If it does, then add back in the patch file, but with only adding one custom setting at a time until you find the setting that causes Sitecore to fail.
Failed access to the showconfig page
If you have pulled the solution to your local and cannot access the showconfig.aspx page because you do not have admin access, there is a workaround. In your deployed files, find the unlock_admin.aspx page under sitecore/admin. Copy that file and place it under the sitecore folder. The reason for this move is because anything under the admin folder requires you to be authenticated as an admin to access. Then open that file. You will need to make a couple changes. Below are two code snippets showing what certain lines are before changes and what they should be changed to.
// BEFORE private bool enableUnlockButton = false; // AFTER private bool enableUnlockButton = true;
// BEFORE
Membership.GetUser("sitecore\\admin").UnlockUser();
// AFTER
var user = Membership.GetUser("sitecore\\admin");
user.UnlockUser();
user.ChangePassword(user.ResetPassword(), "b");
After saving these changes, navigate to <host_name>/sitecore/unlock_admin.aspx. Clicking on the unlock button there will reset the admin user’s password to “b”. Only do this in your local environment. Do not do this in the upper environments. This would pose as a major security risk if you did this in a publicly accessible upper environment.
