Experience Sitecore ! | Routine for renaming a Helix module

Experience Sitecore !

More than 200 articles about the best DXP by Martin Miles

Routine for renaming a Helix module

That would be a quick one. Once you decide to rename existing module, you should follow this consequence order to avoid potential errors. When modifying a module, the higher layer of the changed module is - the more changes require to commit. There is a general consequence of steps below, some of them may not be necessary for your module, so you may skip them. Anyway, here we go:

  1. In serialization file, rename module name for each of predicate records. However, do not rename serialization config file itself at this stage. Publish that particular config to web root (Alt + ,; ALT + P hotkey combination) in order to overwrite existing config. That will enable change tracking for serialization for new paths already.
  2. Once published, rename corresponding items in Sitecore, as per serialization predicates changed on the previous step. Keep in mind that not all predicates are listed in serialization as they are configured at other places by the wildcard (ie. templates), but you need also to change them as well. As the result, there will be a new folder created under src\{layer}\{module_name}\serialization\ and it will have all root items serialized, per each of predicate.
  3. No go to Unicorn console (/unicorn.aspx) and re-serialize modified project. That will bring the rest of the items serialized.
  4. Now it's time to rename the module in Visual Studio:
    1. Change solution folder
    2. Change project name, right underneath solution folder
    3. Remove project out of solution and move it into parent folder having a new name, then add this project back to the solution as existing.
    4. Change Assembly Name and Default Namespace, also perform changes at AssemblyInfo.cs file.
    5. Iterate through all C# classes and adjust the namespaces to match the one changed at 4.3, (In case you're using ReSharper, it will highlight you invalid namespace, so hit ALT + ENTER in and select "Move to {your_new} namespace"). For T4 code generated models however it would be nice to delete those models and re-create just to ensure code generates correctly.
    6. Now go to App_Config/include folder and rename configs: {module_name}.{layer}.config and {module_name}.{layer}.Serialization.config
    7. Do the same for other configs, ie. App_Config/Environment/{layer} and so on.
    8. Also, in configs, you'll need to adjust namespaces, where {type, assembly} are referenced. That may be for instance a configuration of dependency injection, route definition, or any other references to custom classes.
    9. Go and check your /Views folder in order to adjust references
  5. Next step is to delete old module already existing at web root (if you're deploying on clean - you may omit this step). To get rid of existing items with old name, delete the following:
    1. App_Config\Include\{layer}\ - all configs having old module name as the part of their filename
    2. Within /bin folder, delete compiled module, for example: {Solution_name}.{old_name}.Website.dll
    3. Clean up /Views folder for old references as well.
  6. Now it is a good time to remove old serialization - it is kept under an old project name, actually almost duplicating the same you've produced at step 3 (except location and serialized paths, of course). 
  7. Before publishing changes to web root folder, go to Sitecore and rename strongly type references within the Sitecore content. That's in case you've got any custom functionality stored within items that having references in format "{srong_type, assembly}", so please go to Sitecore and rename them all to new namespaces, as was set in 4.3
  8. Finally, re-build the solution and use gulp script, select: publish-all-{layer} task.
  9. If you're renaming a project layer - there're few more things to be done. You would likely to change hostName attribute of the site definition node. In that situation, adjust IIS binding and create a hosts file record for that hostname (if not yet there).
  10. Post-deploy step: rename other content stored in Sitecore items. As for example, you could have a layout called oldsiteLayout.cshtml. Despite it still functions, it would be great to change its name to newsietLayout.cshtml for consistency. But in that case, you also need to change that name in Layout definition item for that project in Sitecore. Do that for all layouts or other affected items.
  11. Last, but not the least. Perform manual and/or integration tests in order to make sure your solution won't break. Breaking tests are always good as they make you critically review certain pieces of implementation, refactor them, or at least keep tests actual to your solution.

Hope that guide helps.

Comments are closed