Our Sitecore Setup, Environment and Best Practices Part 1

I am going to talk about our Sitecore environment including the different servers involved, the process of building new functionality and fixing bugs. This post is the product of a lot of blood, sweat, tears + money. It hopefully might give you some direction in how to set up your environment. The project has gone from simple to complex, back to simple and probably ended up somewhere in between. Our set up is probably not in its final state yet as we have found that things don’t last long in our Agile environment. Constant tweaks here and there in aid of improvement.

To start with, we wanted a robust, tested system with as many regression tests as possible. To support this we chose to use continuous integration (CI). The annoying thing is that Sitecore and CI don’t really fit hand in glove. The main pain is the fact that a working environment is a mix of code and data. We found it nice and easy to add code into Subversion and for that code to be automatically checked out, built and tested on a CI box. However how do you handle data changes? For example you could delete a bunch of nodes in Sitecore and break the site, change the template types, change names, change permissions. How do you tie this in with the versioned code.

We decided that trying to directly tie data into the CI process would be super hard. You could have some event serialize the items in the tree and do something with them but we decided it was a time sink for the project.

Moving forward we have stuck with two real areas for testing for our CI, firstly using WatiN for the front end of the web site as well as unit testing and integration tests for core business logic.

Development Environment a.k.a. “Dev Dirty”

This is where the ball starts rolling. This is the developers local machine. The developers local machine is connected to a shared database, shared amongst the other developers. (Caveat – We try not to work on the same task at the same time as we find caching can cause an issue (usually resolved with an IE cache clear and IIS reset)).

We have 2 main branches in our Subversion repository. One called “current” which is the current code we are working on in our development environments and one called “test” for our test environment.

When we pull a feature task off the Scrum board, we would create a branch off the “current” and call it something like Feature – [Seb's New Feature]. This means I can go off and work on this new feature. When I am done with the code I create WatiN tests that test the frond end UI and any business logic testing. We use a Model View Presenter pattern to break open the larger/more complex stuff so that we can test it.

When I am done and happy, I will check this back into to my Feature – [Seb's New Feature] branch. I will then jump back on to the current branch and merge my feature back in. (I am told that this is the easiest way of doing it).

Cruise Control Environment

Upon me checking code back into the current branch, a seperate box running Cruise Control picks up on the fact that something in the code has changed in Subversion. It then runs a custom NAnt build file that pulls out the latest version of code from Subversion, compiles it, tests all our of Nunit and Watin tests and then alerts us to whether or not the build worked. You can at this point make it even more swanky and have it check code coverage (NCover), quality of the code (FXCop) etc…

Development Environment a.k.a. “Dev Clean”

We have experimented with pushing information between environments via packages as well as full blown system publishes (add the destination as a publishing target and it will overwrite it for you). We are currently trying to stick to piecemeal packages for each task/bug we work on. We can then commit those into Subversion under our branch so we can see which code was related to which piece of Sitecore Data.

To give an example, say I changed 2 templates in Sitecore as part of a new feature, I would create a package containing them, and save it under a folder called “Uninstalled Packages” under my feature branch.

This process gives us the ability to logically group and version code + data.

Any way back on track – The Development environment is the next environment upstream of our Local development machines. It is still a development environment, however this is the make or break point to test to see whether our packages work.

We will do an update on the codebase using subversion behind the scenes and install the package using the package installer in Sitecore. If it doesn’t work we go back and re-create the package. Repeat until it works, and re-commit to Subversion.

We are now ready to push onto a Quality Assurance testing environment. The environments upstream of Dev will be covered over the next posts Tune back in for more.

Whether to reference by GUID or Path in Sitecore

Here is an interesting debate – whether to use GUIDs or Paths to reference Items in Sitecore.

There are advantages and disadvantages to both routes:

By GUID: If you reference an Item by GUID it will mean that you can move it around the Sitecore tree and even rename it without your code breaking. The caveat with this method is that a GUID is not as representative as a path in giving an indication of what the Item is.

To find its path, place the GUID in the Sitecore search, then mouse over to find the path.

By Path: If you reference an Item by path it means you can read the Item’s location easily, however, if you move it around in the tree or rename it, the code will break.

 

My suggestions for referencing an Item are in the following order:

1. Try to add the Item you want to reference as a link from a field in another important, stationary Item in Sitecore. For example, say you wanted to link to a Meta Data folder in your tree, you could create a field in your Site root called “Meta Data” which was a link field to your Meta Data folder.If this doesn’t apply…
    
2. Use a GUID to reference your item, and some sort of comment in the code to give an idea as to what the GUID relates to.Next best…
    
3.  Use a path to reference your item. It would be beneficial to accompany the code with some sort of NUnit Integration Test which would alert you if the path is not there.

I did come up with an alternative which offers slight benefit to the second and third options above and decided to throw it up onto my blog incase any one else found it interesting. It works in a way similar to ConfigurationManager.AppSettings dictionary, in that you can pass it a key name and it will return you a value. However in this case, using Sitecore Templates, we create a GUID Mapping template that will model a name value pair mapping. Where the mapping is a link to a Sitecore Item. So effectively we would say to GUIDManager that we wanted the GUID for the “Meta Data” item and if we had mapped this in Sitecore, it would return us the Meta Data GUID. (We could even make this return an object if we really wanted).

Ultimately what we get from this class is the flexibility of the GUID in that the underlying link can move round the tree and be renamed and not break our code, as well as having an easy to read, meaningful name.

I’ll post up some Sitecore configuration pictures next week, to explain the GUID Mapping template.

    public static class GUIDManager
    {
        /// <summary>
        /// This method will get the GUID for the given name
        /// </summary>
        /// <param name="name">The name to get</param>
        /// <returns>The associated GUID</returns>
        public static string GetGUID(string name)
        {
            if(string.IsNullOrEmpty(name))
            {
                return null;
            }

            try
            {
                string guidStorageLocation = ConfigurationManager.AppSettings["GUIDStorageLocation"];

                // Check to see whether the storage location has been set
                if(!string.IsNullOrEmpty(guidStorageLocation))
                {
                    // Check to see whether the storage item exists
                    Database database = Sitecore.Data.Database.GetDatabase("master");

                    Item guidStorageItem = database.GetItem(new ID(guidStorageLocation));
                    
                    if(guidStorageItem != null)
                    {
                        Item guidMapping = guidStorageItem.Children[name];

                        // Check to see whether the specified mapping exists
                        if(guidMapping != null)
                        {
                            // Return the GUID from the mapping
                            return guidMapping["GUID"];
                        }
                    }
                }

                return null;
            }
            catch (Exception)
            {
                return null;
            }
        }
    }

Screenshot of an example GUID Mapping

Screenshot of a GUID Mapping template

Sitecore and Item transactions

As I have been doing a lot of work with bulk data insertion and manipulation within Sitecore, coupled with the belief that I don’t think Sitecore offers you the ability to use transactions, I have created my own stand in, simple transaction class.

It utilizes generics and .Net’s disposable interface http://msdn.microsoft.com/en-us/library/system.idisposable.aspx to achieve an easy to read transaction.

If you look at the following code, the first segment shows you how to use the Transaction.cs, the second segment is Transaction.cs. You can see we wrap the transaction in a using statement, which will call the rollback delegate if an exception is thrown at any point. Or alternatively we can call transaction.dispose() which will roll back the transaction also.

How to use Transaction.cs

    public class UtilityMethods
    {
        private Transaction<Item> transaction;

        public void AddChildItems(Item parentItem, string newChildName, TemplateID childTemplateID, int numberOfChildrenToAdd)
        {
            using(transaction = new Transaction<Item>(Rollback))
            {
                for (int i = 0; i < numberOfChildrenToAdd; i++)
                {
                    Item insertedChild = parentItem.Add(newChildName, childTemplateID);
                    transaction.TransactionableItems.Add(insertedChild);
                }
            }
        }

        public void Rollback()
        {
            using (new SecurityDisabler())
            {
                if (transaction != null && transaction.TransactionableItems.Count > 0)
                {
                    foreach (Item item in transaction.TransactionableItems)
                    {
                        try
                        {
                            item.Delete();
                        }
                        catch (Exception)
                        {
                            continue;
                        }
                    }
                }
            }
        }
    }

Transaction.cs

    /// <summary>
    /// This class models a transaction
    /// </summary>
    /// <example>
    /// using(Transaction transaction = new Transaction(// Provide delegate to handle rollback here))
    /// {
    ///     // Sitecore insert
    ///     // Sitecore update
    ///     // Sitecore insert
    ///     transaction.Commit();
    /// }
    /// </example>
    public class Transaction<T> : IDisposable
    {
        public delegate void RollBack();

        private readonly RollBack rollBack;
        private bool isCommited;
        private readonly List<T> transactionItems = new List<T>();

        /// <summary>
        /// Public constructor
        /// </summary>
        ///
<param name="rollBack">A method to use to rollback with</param>
        public Transaction(RollBack rollBack)
        {
            this.rollBack = rollBack;
        }

        /// <summary>
        /// Handles the dispose call
        /// </summary>
        public void Dispose()
        {
            // If the transaction is not commited
            // and object is disposing, rollback
            if (!isCommited && rollBack != null)
            {
                rollBack();
            }
        }

        /// <summary>
        /// Sets the commited flag to true,
        /// rollback cannot happen after commit is called
        /// </summary>
        public void Commit()
        {
            isCommited = true;

            transactionItems.Clear();
        }

        /// <summary>
        /// Gets the list of transactionable Items
        /// </summary>
        public List<T> TransactionableItems
        {
            get { return transactionItems; }
        }

        /// <summary>
        /// Returns whether or not the transaction was comitted
        /// </summary>
        public bool WasCommited
        {
            get { return isCommited; }
        }
    }