With the PowerCLI installation comes a shortcut to a PowerShell sessions, loaded with all the PowerCLI goodness. And this is ideal to make your first steps in the wonderful world of PowerShell and PowerCLI.

But soon you’ll start using more advanced features of PowerShell. You’ll be scheduling jobs, running parallel workflows, start using PowerCLI in Desired State Configuration (DSC). At that moment, the simple PowerCLI session doesn’t cut it anymore, and even the Init scripts that are installed together with PowerCLI, will not give you the exact environment as you want it. Hence my Universal PowerCLI Loader!

I have been using a “Universal PowerCLI loader” function since quite some time now. I thought it was time to prettify it a bit, and share it with the community.

To create the Universal PowerCLI loader, I first needed to take stock of what all the different PowerCLI versions require and bring. The result of that inquiry is reflected in the following spreadsheet.

Some clarifications on the table:

Columns E, F and G: contain hyperlinks to the respective Release Notes, Download link and Online Helppage for each PowerCLI release. Note that the download will require you to enter a MyVMware account.

Columns H and I: the minimum and maximum supported PowerShell version

Columns J and K: the minimum and maximum supported OS (for workstations) on which you can use PowerCLI

Columns L till P: the required .Net version

Columns Q and R: the minimum and maximum supported vSphere version. These are just an indication, always use the VMware Product Interoperability Matrixes to determine which version is required.

Columns U and V: the number of cmdlets available for the “regular” modules and for the “Cloud” modules. To get the total number of cmdlets in a specific release, add these two numbers together.

Some interesting observations that can be made from this table:

• The table starts with PowerCLI 5.1.0.2, since I personally think you should never need an older version. If you do, let me know, and I’ll see if I can expand the table and the function.
• Notice that with PowerCLI 5.8 a separate installation for PowerCLI for Tenants was introduced (row 7)
• With the PowerCLI v6.x series, modules were introduced
• Not all cmdlets are currently migrated from PSSnapins to Modules, hence the mix of PSSnapin and Modules
• WMF 5 support is included from the PowerCLI v6.3. Note that this is for the WMF 5 that comes with Windows 10. The WMF 5 that is still in preview, and that will probably be released with Windows 2016, is not yet officially supported

The Function

function Enable-PowerCLI
{
<# .SYNOPSIS Load PowerCLI modules and PSSnapins .DESCRIPTION This function will load all requested PowerCLI modules and PSSnapins. The function will, depending on the installed PowerCLI version, determine what needs to be loaded. .NOTES Author: Luc Dekens .PARAMETER Cloud Switch to indicate if the Cloud related cmdlets shall be loaded .PARAMETER InitScript The PowerCLI PSSnapin have associated initialisation scripts. This switch will indicate if that script needs to be executed or not. .EXAMPLE PS> Enable-PowerCLI
.EXAMPLE
  PS> Enable-PowerCLI -Cloud
#>

  [CmdletBinding()]
  param(
    [Switch]$Cloud,
    [Switch]$InitScript
  )

  $PcliPssnapin = @{
    'VMware.VimAutomation.License' = @(2548067)
    'VMware.DeployAutomation' =@(2548067,3056836,3205540,3737840)
    'VMware.ImageBuilder' = @(2548067,3056836,3205540,3737840)
  }

  $PcliModule = @{
    'VMware.VimAutomation.Core' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.Vds' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.Cloud' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.PCloud' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.Cis.Core' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.Storage' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.HA' = @(2548067,3056836,3205540,3737840)
    'VMware.VimAutomation.vROps' = @(3056836,3205540,3737840)
    'VMware.VumAutomation' = @(3056836,3205540,3737840)
    'VMware.VimAutomation.License' = @(3056836,3205540,3737840)
  }

  # 32- or 64-bit process
  $procArch = (Get-Process -Id $pid).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
  if($procArch -eq 'x86'){
    $regPath = 'HKLM:\Software\VMware, Inc.\VMware vSphere PowerCLI'
  }
  else{
    $regPath = 'HKLM:\Software\WOW6432Node\VMware, Inc.\VMware vSphere PowerCLI'
  }
  
  # Check if PowerCLI (regular or Tenant) is installed
  if(!(Test-Path -Path $regPath))
  {
    $regPath = $regPath.Replace('VMware vSphere PowerCLI','VMware vSphere PowerCLI for Tenants')
    if(!(Test-Path -Path $regPath))
    {
        Throw 'Can not find a PowerCLI installation!'        
    }
  }
  
  # Get build
  $buildKey = 'InstalledBuild'
  Try{
    $pcliBuild = Get-ItemProperty -Path $regPath -Name $buildKey |
        Select -ExpandProperty $buildKey -ErrorAction Stop
  }
  Catch{
    Throw "PowerCLI doesn't seem to be installed on this system!"
  }

  # Get installation path
  $installPathKey = 'InstallPath'
  Try{
    $pcliInstallPath = Get-ItemProperty -Path $regPath -Name $installPathKey |
        Select -ExpandProperty $installPathKey -ErrorAction Stop
  }
  Catch{
    Throw "PowerCLI doesn't seem to be installed on this system!"
  }

  # Load modules
  if($pcliBuild -ge 2548067)
  {
    $loadedModule = Get-Module -Name VMware* -ErrorAction SilentlyContinue | %{$_.Name}
    if($loadedModule -and $pcliBuild -ge 3737840)
    {
      $loadedModule = $loadedModule | where{$_ -notmatch 'Common$|SDK$'}
    }
  
    $targetModule = $PcliModule.GetEnumerator() | where{$_.Value -contains $pcliBuild} | %{$_.Key}
    $targetModule = $targetModule | where{$loadedModule -notcontains $_}
    if(!$Cloud)
    {
      $targetModule = $targetModule | where{$_ -notmatch 'Cloud'}
    }
    if($targetModule)
    {
      $targetModule | where{$loadedModule -notcontains $_.Name} | %{
        Import-Module -Name $_ -Verbose:$false
      }
    }
  }
  
  # Load PSSnapin
  $loadedSnap = Get-PSSnapin -Name VMware* -ErrorAction SilentlyContinue | %{$_.Name}
  if($pcliBuild -ge 3737840)
  {
    $loadedSnap = $loadedSnap | where{$_ -notmatch 'Core$'}
  }

  $targetSnap = $PcliPssnapin.GetEnumerator() | where{$_.Value -contains $pcliBuild} | %{$_.Key}
  $targetSnap = $targetSnap | where{$loadedSnap -notcontains $_}
  if(!$Cloud)
  {
    $targetSnap = $targetSnap | where{$_ -notmatch 'Cloud'}
  }
  if($targetSnap)
  {
    $targetSnap | where{$loadedSnap -notcontains $_} | %{
      Add-PSSnapin -Name $_ -Verbose:$false

      # Run initialisation script
      if($InitScript)
      {
        $filePath = "{0}Scripts\Initialize-{1}.ps1" -f $pcliInstallPath,$_.ToString().Replace(".", "_")
        if (Test-Path $filePath) {
          & $filePath
        }
      }
    }
  }
}

Annotations

Line 27-44: in these tables the relation between the PowerCLI version and the required modules and PSSnapin are defined

Line 47-53: depending if the PowerShell session is a 32- or 64-bit process, another registry branch needs to be accessed.

Line 56-63: check if PowerCLI, or PowerCLI for Tenants, is actually installed on the station before continuing

Line 66-83: the buildnumber and the installation path are retrieved from the registry

Line 86-106: loads the requested PowerCLI modules, if we are in a PowerCLI v6.x environment. The logic first determines which modules are available, then substracts the ones that are already loaded and finally loads the missing ones. This means that the function can be called more than once.

Line 94: in combination with the table, define earlier, this line will check for each known PowerCLI module, if it is present in the current PowerCLI installation.

Line 109-135: similar logic as before with the modules, to load the required PowerCLI PSSnapins.

Line 127-133: execute the PSSnapin initialisation scripts if requested. The default is not to run these scripts.

Sample Usage

The purpose of the function is quite straightforward, it loads the PowerCLI PSSnapin and modules. The call to the function can be placed in the beginning of your scripts. No more need to handle the loading of PowerCLI in your scripts.

Enable-PowerCLI

This will load all PowerCLI PSSnapins and modules, depending on the installed PowerCLI version, minus the Cloud related modules and PSSnapins.

If you need the Cloud functionality, you just need to do

Enable-PowerCLI -Cloud

The Enable-PowerCLI function is available on my Github Scripts repository.

Note that the Enable-PowerCLI function can not be added to a module. The Add-PSSnapin cmdlets executed inside a module, are not propagated to the caller!
This is a know, unresolved issue.

Enjoy!

The script

Get-Command -Module VMware.VimAutomation.Core | %{
	$meta = New-Object System.Management.Automation.CommandMetadata (Get-Command $_.Name)
	$paramNr = 0
	$meta.Parameters.GetEnumerator() | %{
		$attribute = $_.Value.Attributes | where {$_.GetType().Name -eq "ParameterAttribute"}
		Select -InputObject $_ `
			-Property @{N="Cmdlet";E={if($paramNr -eq 0){$meta.Name}}},
				@{N="Parameter Name";E={$_.Key}},
				@{N="Parameter Aliases";E={[string]::Join(',',($_.Value.Aliases.GetEnumerator() | %{$_}))}},
				@{N="ParameterSets";E={[string]::Join(',',($_.Value.ParameterSets.GetEnumerator() | where {$_.Key -ne "__AllParameterSets"} | %{$_.Key}))}},
				@{N="ConfirmImpact";E={if($paramNr -eq 0){$meta.ConfirmImpact}}},
				@{N="OBN";E={if(($_.Value.Attributes | where {$_.GetType().Name -eq "ObnArgumentTransformationAttribute"})){$true}else{$false}}},
				@{N="Mandatory";E={$attribute.Mandatory}},
				@{N="Pipeline";E={$attribute.ValueFromPipeline}},
				@{N="Position";E={if($attribute.Position -ne 0x80000000){$attribute.Position}}}
		$paramNr++
	}
} | Export-Csv "C:\PowerCLI-Xref.csv" -NoTypeInformation -UseCulture

Annotations

Line 2:  With the System.Management.Automation.CommandMetadata object we gain access to the cmdlet metadata.

Line 4: The Parameters property gives access to a hash table that holds all the information we are after.

Line 12: The OBN attribute indicates if for that specific parameter the value can be provided as an Object By Name.

Line 15: A parameter that is not a positional parameter will have the value 0x80000000

The file

The CSV file that the script produces looks like this

You can see all the PowerCLI cmdlets, the parameter sets that exist for a cmdlet, the eventual aliases that exist, the confirmimpact setting,  if you can pass a specific parameter as an Object By Name, if the parameter is mandatory, if a parameter accepts pipeline input and finally the position number if it concerns a positional parameter.

Oddities

When you look closer at the CSV file you will notice that there are some oddities present. Most probably, the majority of these slipped it between successive PowerCLI builds. A short overview of what I noticed. Feel free to mention others in a comment.

Alias names

To say the least, they are not really consistent.

You would assume that the VMHost parameter has alias called Host. With most of the cmdlets that is the case, but there are exceptions.

Parameter sets

This handy feature seems to have some quirks as well.

Why would the RunAsync parameter have a dedicated parameter set for the Move-Datacenter cmdlet ?

Why does the DistributedSwitch parameter belong to a seperate parameter set on the New-NetworkAdapter cmdlet but not on the Set-NetworkAdapter ?

Confirm impact

Some of these settings do not look consistent and logical to me. What are the criteria to decide if the impact is Low, Medium or High ?

Postional parameters

The Position of a parameter is indicated with an integer, which starts at 0.

When you display the parameters with the Get-Help cmdlet, the position index is incremented by 1. This leads to the funny situation that you have no positional parameter in position 1.

I’m probably not seeing the bigger picture and I don’t know why some decissions were taken during the development of some of the cmdlets.

But perhaps the Dev Team could enlighten us and produce “The making of” blog post or video

Note that the following list is my personal list and that it is definitely not my aim to list all available PowerShell snapins and modules. That would be a sheer impossible task, seen the abundance of the currently available  snapins and modules.

Previous entries in this series were My PS toolbelt and My PS library.A few words of explanation on the following table.

In the Fmt column I tried to indicate in which format the add-on comes, as a snapin, as a module or as both. The entries that have src in this column have to be dot-sourced.

In the PSv column you can find which PowerShell version the add-on requires.

The Bit column indicates, where possible, if the add-on provides a 32- and/or a 64-bit version. Some add-ons come with their own DLLs and I had to rely on the author’s information to fill in this column.

I will try to update/correct this table regularly but feel free to let me know if you happen to have corrections or more recent information.

And you’re of course welcome to send pointers to snapins and modules not in this table that you consider useful.