Helix Project Creation Script

Creating Helix Solutions and Modules with PowerShell

Helix is a set of overall design principles and conventions for Sitecore development, put forth by Sitecore in hopes of providing the community a path toward standardized solution development. As noted in the official documentation:

Helix provide a set of guidelines for your Sitecore projects. The Habitat example provides you with a pre-built and tested set of common modules that you can use as an inspiration to your project. Both improve the efficiency of your projects, reduce costs and time to market. As more and more people and organisations adopt the Helix conventions and principles, it will become a Sitecore standard. This means that people who are familiar with the conventions or the Habitat example will be able to work more easily on other convention-based projects with minimal training. It will be easier for Sitecore Product Support to understand projects built using the conventions, enabling them to resolve issues more quickly. Sitecore will test its software using the conventions so any compatible project that has been implemented for a customer will be more reliable. And since Sitecore will test its software using the conventions, Sitecore will be able to provide better guidance on how to update and upgrade existing Sitecore projects when new versions and new products are released.

(“Why be interested at all in Helix or Habitat?“, http://helix.sitecore.net/introduction/what-is-helix.html#why-be-interested-at-all-in-helix-or-habitat, April 16, 2018)

Some Basic Principles

Before we can dig into the script and creating Helix based solutions and modules, I want to reference some basic principles from the Helix documentation.

A Module is a conceptual grouping of assets which relates to a business requirement. For example, when the company asks that their Sitecore solution contains website search, all assets, business logic and configuration relating to search belongs to the Search module.

In technical terms, project often refers to Visual Studio project, but conceptually can also to the process of implementing the business requirements into an implementation.

The layer concept in Helix supports the architecture by making the dependency flow completely clear everywhere in the solution, in Sitecore, in Visual Studio and even in the file system. Furthermore, the layers provide a structure that is extremely suitable for creating and maintaining solutions of any size and steers both new and experienced developers to producing more maintenance-friendly and clean code. Layers helps control the direction of dependencies the importance of which is described by the Stable Dependencies Principle or SDP, which is one of the cornerstone principles in Modular Architecture:

Helix - Dependencies Direction

File System and Solution Layout

In the Helix documentation, (and a review of the sample Habitat site) one will find a very specific recommended (if not expected) layout and naming of folders both in the Visual Studio Solution as well as the file system. The uniqueness of this ‘recommended’ layout makes the initial setup of a solution very time consuming and increasingly error prone when you start to deal with adding modules at the different layers. The following two images, taken from the Helix documentation show what the Visual Studio Solution and corresponding file system begin to look like.

Helix - Visual Studio Solution, from Sitecore           Helix - File System, from Sitecore

Helpful but difficult

My team enjoys the flexibility as well as cleanliness of a solution built on the Helix principles. What we find most difficult is the extra leg work required in making the file system as well as the Visual Studio Solution appropriate to meet the principles. Trying to solve this problem has led us to try several solutions available in the Sitecore Community, many function very nicely, but didn’t always meet the needs of my teams. So I setout to solve some of these issues, including :

  • No use of custom templates and files to ease setup across machines
  • Option for serialization project creation
  • Pre-loading basic NuGet packages for a module
  • New projects added into the solution by default

Helix Project Creator PowerShell Module

Enough with the intro stuff and into the meat of what you’ve come looking for…a script to ease your Helix headaches and focus on the fun of implementing solutions. TheCodeAttic.Helix.ProjectCreator can be pulled from GitHub at https://github.com/gillissm/TheCodeAttic.Helix.PowerShellProjectCreator.

Setup and Use the Simple Manual Process

The first thing you need to do is retrieve the script from the GitHub repository. As this is hosted on GitHub there are numerous ways you can go about getting things ready to use. In an attempt to make adaption as easy as possible I’ve simplified setup to the following four steps for you:

  1. Open PowerShell command prompt as Admin.
  2. Change the directory to a working/temporary location
  3. Enter the following command
    (Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/gillissm/TheCodeAttic.Helix.PowerShellProjectCreator/master/ProjectCreatorEasyInstall.ps1).Content | Out-File "ProjectCreatorEasyInstall.ps1"
  4. Then enter
    .\SELRES_09210478-5ac2-4be5-81ef-480eb16e800fSELRES_66c735a3-48ae-4ec2-9967-83d5f083a6f6SELRES_906c181e-dccb-4538-a6c3-1eb25a8f6853ProjectCreatorEasyInstallSELRES_906c181e-dccb-4538-a6c3-1eb25a8f6853SELRES_66c735a3-48ae-4ec2-9967-83d5f083a6f6SELRES_09210478-5ac2-4be5-81ef-480eb16e800f.ps1
  5. Now go implement some awesome Sitecore solutions!

Setup and Configure the Manual Way

As an alternate to the above, you can pull the script from the GitHub repository and load it into Package Manager Console each time you need it with the following steps:

  1. Download from the GitHub repository to your local system in the manner that suits your workflow the best.
  2. Each time you wish to leverage the module in Visual Studio you will need to enter the following in the Package Manager Console
    Import-Module "C:\MyFiles\TheCodeAttic.Helix.PowerShellProjectCreator.psm1"

    Helix - Open Package Manager Console

Manual Process – Full Setup

OR you could download and configure the module manually (this is what ProjectCreatorEasyInstall.ps1 does for you.)

  1. Go to C:\Users\\Documents\WindowsPowerShell\Modules
  2. Create a new folder called “TheCodeAttic.Helix.PowerShellProjectCreator”
  3. Download the GitHub repository into the above directory
  4. Go up a level in the file system, should be at C:\Users\\Documents\WindowsPowerShell\
  5. Open (or create) NuGet_profile.ps1
  6. Add the following
    Import-Module TheCodeAttic.Helix.PowerShellProjectCreator
  7. Each time you run Visual Studio the module will be available to use in the Package Console Manager

Using Helix Project Creation

Create a new Helix Solution

  1. Open Visual Studio as Admin
  2. Open the Package Manager Console
    Helix - Open Package Manager Console
  3. Create a new Helix based solution by running Invoke-VisualStudioSolution
    Invoke-VisualStudioSolution -SolutionPath 'C:\Code\Coffeehouse.Demo.SXA'  -SolutionName 'Coffeehouse.Demo.SXA'

    Helix - Open Package Manager Console

Add a new module to a solution

  1. Open Visual Studio as Admin
  2. Open your Solution
  3. Open the Package Manager Console
  4. ‘Wake-up’ the $dte object by running
    $dte.Solution.FullName
    Helix - Wake-up $dte
  5. Add new module by running Invoke-NewModule
    Invoke-NewModule -ModuleName 'Coffeehouse.Demo.SXA.Coupon' -Layer 'Feature' -UseGlass -UseTDS

    Helix - Executing Invoke-NewModule

    Helix - Invoke-NewModule output

    Helix - Invoke-NewModule output, continued

  6. Go write some Sitecore code!!!!

Proof is in the pudding, they say

After running the Invoke-NewModule command your solution explorer should now look like the following:

Helix - New Module in Solution Explorer

And your file system will have the this:

Helix - New Module in File Explorer

References

The Sitecore Community members are always out to help each other, and some other Helix project creation solutions that may fit your work stream better are:

Advertisements

Requires Qualified Assembly Name, ugh!

You are plugging away at writing this super sweet class, to be used in your latest application, and then you hit the wall! Nothing builds because the configuration file requires a reference to the fully qualified assembly name…ugh!!!

The first thing you do is scratch your inner mind trying to recall what makes up this name. (At least that is what I end up doing every time.) It seems depending on what you are working on you will either need a four-part name or a ‘five-part name’.

The four-part fully qualified name consists of the following in the following order:

Assembly Name, Version= 0.0.0.0, Culture=culture code, PublicKeyToken=public key

(It is common for culture to be set to ‘neutral’ if there is nothing contained that is specific to a cultural style.)

What I consider the to be the five-part name is the four-part name with the namespace and class name that is being referenced prefixed.

Namespace.Class Name, Assembly Name, Version=0.0.0.0, Culture=culture code, PublicKeyToken= public key

With the background details explained, how as a lazy programmer can we retrieve the fully qualified name without a lot of clicks? The old stand by use to be to fire up reflector, throw your assembly in and poof there was the four part assembly name, but any more finding a really good reflector is much more difficult (and there is a lot of extra clicking involved by using a second program.)

Visual Studio 2010 has a great feature in allowing you to set up single clicks from the menu bar and via hotkeys to external tools…which means a perfect fit for a simple PowerShell command.

  1. Go to Tools -> External Tools.
  2. The External Tools dialog box should open for you. Click Add.
    image
  3. This will then generate a new value labeled [New Tool 1] and have it selected for you.
    image
  4. In the lower half, provide a Tittle for the new tool such as "4-Part Name".
  5. In the Command, textbox you will enter the following
    powerhell.exe
  6. In the Arguments, textbox enter the following
    -command "[System.Reflection.AssemblyName]::GetAssemblyName(\"$(TargetPath)\").FullName
  7. Select Use Output window to force the assembly name into the output window of Visual Studio.
  8. The completed dialog should resemble the following
    image
  9. Click OK.
  10. Your command should now display under Tools.
    image
  11. To get the four part name,
    1. Select the project or any file in the project from Solution Explorer or Solution Navigator
    2. Go to Tools –> 4-Part Name
    3. See the four part name displayed in the Output window
      image

References:
MSDN AssemblyName.GetAssemblyName()
MSDN Type.FullName
MSDN Details on Assemnly Names