FAQ (2) – What is the Rangers HOL Package all about?

Article
01/14/2011

See https://blogs.msdn.com/b/willy-peter_schaub/archive/tags/faq/ for a list of all FAQs (frequently asked questions).

Q: What is the Rangers HOL Package all about?

The HOL acronym stands for Hands-On-Lab, which can also be thought of as a guided walkthrough.

When the Rangers develop a HOL, they have to develop not only the HOL, but also a HOL Package. In essence the life of a HOL typically includes:

Design of the HOL
Development of the HOL
Review and Testing of the HOL
Development of the HOL Package
Review and Testing of the HOL Package
Inclusion of HOL on Rangers Base Virtual Machine
Inclusion of HOL Package in Rangers VM Factory Task Sequence

Steps 1 – 5 are typically owned and completed by a feature area or Epic team within a Rangers project. Steps 1 to 3 are concerned with the design, development and testing of the HOL … out of scope for this discussion.

During step 4 the team develops a HOL package, which includes the following:

Prerequisite software and installation instructions
Prerequisite reference solution (optional), for example a sample application (Tailspin,. Simple Calculator, …)

One PowerShell script that creates the environment needed by the HOL, for example adding user accounts, creating team projects and checking in code.
Here is an example from the database guidance HOL:

    1: # Copyright © Microsoft Corporation.  All Rights Reserved.
    2: # This code released under the terms of the 
    3: # Microsoft Public License (MS-PL, https://opensource.org/licenses/ms-pl.html.)
    4: #
    5:  
    6: function SetupHOL
    7: {
    8:  $currentLocation = Get-Location
    9:  $tempLocation    = Get-content env:tfspowertooldir
   10:    
   11:  if(!("C:\HOL\DataDude\HOLSetup\Install" -eq $currentLocation))
   12:  {
   13:    "Please run script from C:\HOL\DataDude\HOLSetup\Install"
   14:    return
   15:  }
   16:  
   17:   # Create logs directory if does not exist
   18:  if ((Test-Path -path c:\HOL\Logs\) -ne $True)
   19:  {
   20:    New-Item c:\HOL\Logs\ -type directory
   21:  }
   22:   
   23:  Set-Location $tempLocation
   24:  
   25:  #Create team project with tfpt
   26:  Write-Host -Object:"Creating TeamProject DatabaseProjectGuidance"
   27:  Write-Host -Object:"============================================"
   28:  .\TFPT.EXE createteamproject /settingsfile:'C:\HOL\DataDude\HOLSetup\Install\DatabaseProjects.XML'
   29:  #waitForKey
   30:  
   31:  $tempLocation    = Get-content env:vs100comntools
   32:  Set-Location $tempLocation
   33:  
   34:  #Create Workspace
   35:  Write-Host -Object:"Create Workspace BuildAndDeploy"
   36:  Write-Host -Object:"==============================="
   37:  ..\IDE\TF.EXE workspace /new BuildAndDeploy /noprompt /collection:https://localhost:8080/tfs/DefaultCollection
   38:  ..\IDE\TF.EXE workfold  /map $/HOL_DatabaseProjects 'C:\HOL\DataDude' /workspace:BuildAndDeploy
   39:  ..\IDE\TF.EXE workfold  /unmap $/
   40:  
   41:  #Create the VC space as per HOL
   42:  Write-Host -Object:"Checkin code"
   43:  Write-Host -Object:"============"
   44:  ..\IDE\TF.EXE add       'C:\HOL\DataDude\BuildAndDeploy/AdventureWorksDB' /recursive
   45:  ..\IDE\TF.EXE checkin   'C:\HOL\DataDude\BuildAndDeploy/AdventureWorksDB' /comment:'HOL Automated Checkin' /recursive /noprompt
   46:  
   47:  Write-Host -Object:"Create drop share for TeamBuild and assign rights"
   48:  Write-Host -Object:"================================================="
   49:  Remove-Item -Recurse -Force "C:\Drops"
   50:  md C:\Drops
   51:  net share Drops=c:\Drops
   52:  "/GRANT:Everyone,FULL"
   53:  
   54:  Set-Location $currentLocation
   55: }
   56:  
   57: #displayWelcome    
   58: SetupHOL

The following image shows a typical layout of a HOL package:

Each HOL has an optional directory which contains stuff such as source code. In this case we have two HOLs for this specific project, namely CustomActivity and DeployWeb.
HOLSetup directory is standard and contains the PowerShell script.
README file contains instructions on how to install this specific set of HOLs

If we drill further into the HOLSetup directory we get:

SetupHOL.ps1 Powershell script is standard and is responsible to setup and configure the HOL prerequisite environment.
The two XML files are configuration files for the TFPT utility called in the script to create two Visual Studio Team Projects. There can be zero or more of these configuration files hiding in this directory, one for each Team Project to be created.

Note that the Rangers Base VM has a C:\HOL directory which accommodates all the HOL packages. The following shows the current C:\HOL home on the Rangers Base VM image (v2.3):

README file contains instructions on how to install all HOLs
SetupHOL_All.ps1 is a PowerShell script that strings together and executes all HOL SetupHOL.ps1 scripts.
One directory for each HOL, a logs directory which contains setup log files and a prerequisite software directory into which we drop all prerequisite software and installation instructions

Once step 5 has been completed by the package is forwarded to the VMFactory team, which adds the HOL to the current Rangers Base image. At this stage we are running the HOL Package PowerShell scripts manually (step 6), but in future releases of the VM Factory this will be tied into the overall base image task sequence (step 7).

Why invest in the HOL Package?

It standardises and automates the HOL prerequisites environment using simple technology and processes.
It allows us to automate the creation of all HOLs using the Rangers VMFactory (Codeplex).
Most importantly, it allows those that do not have access to our base image or want to use their own, to quickly and consistently setup the HOL in their environment.

How do I use a HOL Package?

Firstly you need to determine if you have received a project specific HOL Package, or a complete HOL Package. The former is typically distributed as part of Rangers projects on Codeplex, whereas the latter is made available on request or as part of the VMFactory.

Project Specific HOL Package

Copy/Extract the C:/HOL/* path of the package to C:/HOL
Locate the HOLSetup directory.
Read the _README_FIRST.txt file
Install and configure all prerequisite software
Execute the SetupHOL.ps1 PowerShell script, unless instructed otherwise in the README.

Complete HOL Package

Copy/Extract the C:/HOL/* path of the package to C:/HOL
Read the _README_FIRST.txt file in C:\HOL
Install and configure all prerequisite software
Execute the SetupHOL_All.ps1 PowerShell script in C:\HOL, unless instructed otherwise in the README.