Before upgrading to the latest PowerCLI 6.5.1 on a production Windows Server, there are quite a few things you must commit to. Also, it needs to be done in one sitting. Can you really edit all of those .ps1 files, upgrade all components and test it now?

There's more, and we'll dig in. First, let me say that the VMware documentation on this topic is perfect (PowerCLI 6.5.1 Install Walkthrough). What we will cover here is supplemental, philosophical and tactical. These are just notes from the field. Go!

Old PowerCLI versions must be removed. Technically, PowerCLI 6.5.1 is a fresh install.

Background

Historically, we have enjoyed an extremely flexible upgrade experience with PowerCLI. It has always been backwards (and forward) compatible. It's quite incredible actually.

However, we may be spoiled to a degree. Now that things have changed a bit, I see people upgrading PowerCLI on production servers and breaking automation and scheduled tasks.

If you are upgrading your workstation, have at it. However, before upgrading PowerCLI on a server you should learn the pressure points.

QUICK FACTS

Last available .exe build: PowerCLI 6.5 R1 Build 4624819
First PSGallery version: PowerCLI 6.5.1 Build 5377412

The naming similarity is due to VMware changing their standard to follow the PSGallery module versioning.

Checklist

Follow this checklist to inspire ideas and take what's relevant to your environment.

prepare

  • Handle Existing PowerCLI Scripts (if any, check for Add-PSSnapin)
  • PowerShell Version (PowerShell 3.0 minimum; PowerShell 5.1 preferred)
  • .Net Framework version (.Net Framework 4.5 required)
  • Scheduled Tasks that use PowerCLI (if any, check for Add-PSSnapin)
  • PowerShell $PROFILE (check profiles that may call Add-PSSnapin)
  • Impl Changes (if upgrading from PowerCLI 5.x)

upgrade

  • Remove PowerCLI from Control Panel (if exists)
  • Remove PowerCLI folder (if exists)
  • Find-Module -Name VMware.PowerCLI
  • Install-Module -Name VMware.PowerCLI -Scope AllUsers -AllowClobber -Force

configure

  • Configure PowerCLI with Set-PowerCLIConfiguration

consume

Enjoy automatic module loading in 6.5.1 or manually load with:

  • Get-Module -Name VMware.PowerCLI -ListAvailable | Import-Module

In the coming sections, I will describe each of the above items.

Handle Existing Scripts

This is perhaps the most important part of the upgrade. We need to review all .ps1 files on the server and remove any lines with Add-PSSnapin. These would be files created by you or your company (if any).

If you cannot commit to changing the relevant lines of code in all .ps1 files, you should schedule a time that it can be performed and tested properly.

After installing PowerCLI 6.5.1, modules are automatically loaded. This means you can remove lines or snippets related to Add-PSSnapin. Further, you do not need to replace that snippet with updated code (i.e. Import-Module is optional).

If you want your scripts to support legacy PowerCLI versions, you can change the code to a universal loader (i.e. something that supports 5.x to 6.5.1+ such as Invoke-PowerLoader).

Legacy Loader

Formerly, we would load one or more snapins:

Add-PSSnapin VMware.VimAutomation.Core
Add-PSSnapin VMware.VimAutomation.Vds

Latest Loader

This requires installation of PowerCLI 6.5.1 which we have not gotten to yet. However, the following shows the manual technique to load the modules once on 6.5.1, if desired. You probably won't do this since the modules load automatically on first use.

Get-Module -Name VMware.PowerCLI -ListAvailable | Import-Module

PowerShell Version

In my experience, this is extremely flexible. While there were some issues last year or so (i.e. with Tech Previews and maybe PowerShell 5.0), currently it's safe to upgrade. I recommend going to PowerShell 5.1, which at the time of this writing is the latest.

For more details see Install and Configure WMF 5.1 which covers every possible OS upgrade path. Must read if on PowerShell 3.

It's an excellent article for all, but especially important for older operating systems such as Windows Server 2008 R2 (which I have done a lot of). I had the luxury of being aggressive early on so my 2k8 R2's were all running PS4 already. Upgrade to 5.1 was no problem. YMMV so please vet older operating systems. All of my 2012 and 2012 R2 PowerShell upgrades were very smooth as well.

PowerShell is available as a unique download package for each of the Windows operating system types. Modern versions come packaged as the Windows Management Framework. For example, the latest is WMF 5.1 which has the following download choices:

WMF 5.1 Downloads

Choose the appropriate version depending on your OS:

W2K12-KB3191565-x64.msu
Win7AndW2K8R2-KB3191566-x64.zip
Win7-KB3191566-x86.zip
Win8.1AndW2K12R2-KB3191564-x64.msu
Win8.1-KB3191564-x86.msu

> Tip: If you install the wrong version, it will safely fail.

For 2012 and 2012 R2, the install is just an .msu that you download and double-click. You will be prompted to allow elevation and you should be prepared to reboot upon completion of the install (or sometime soon thereafter).

For Windows Server 2008 R2, you will notice that it is distributed as a .zip. This package comes with a very well written .ps1 that checks compatibility before installing the included update. Just download the .zip, unblock it, extract the contents, and run the .ps1 from an elevated PowerShell prompt. Your system will reboot immediately after the install.

Not covered here, but you can also download the latest Microsoft PowerShell Core for Linux, macOS, and nano. You can also get the regular Windows bits there too.

https://github.com/PowerShell/PowerShell

Compatibility for VMware

We can see in the .psd1 module manifest that PowerCLI 6.5.1 needs a minimum of PowerShell 3.0:

# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '3.0'

Because PowerCLI is now exclusively available from the PSGallery, we do not need My VMware to get the bits. This is excellent. However, just know that older operating systems may need special attention to access the gallery. Go with WMF 5.1 and you will be good to go (or read the docs to get up and running on PS3 or PS4 which are both supported on the PSGallery now).

If you ever need the .exe install of an older version of PowerCLI, you cannot get that from https://vmware.com/go/powercli any longer! You must download from the Additional Tools tab of the relevent vSphere release on https://my.vmware.com.

.NET Framework Version

This one is easy; Just perform Windows Updates and you will get what's needed. The VMware.PowerCLI module currently requires a minimum of .NET Framework 4.5. We can see the requirement in the module manifest (.psd1) for PowerCLI 6.5.1 below:

# Minimum version of the .NET Framework required by this module
DotNetFrameworkVersion = '4.5'

Windows Scheduled Tasks

This is a show stopper if you don't check. You absolutely must know what Scheduled Tasks (if any) are loading PowerCLI.

You should take the time to view the settings of each Windows Scheduled Task and observe the .ps1 that it calls. Then, open the script in an editor to review if changes are needed (i.e. removing Add-PSSnapin lines).

Warning: Always check the Windows Task Scheduler before installing PowerCLI 6.5.1. Here you may find custom scripts that your company runs to generate health checks, deployments, etc.

Impl Types

If you are upgrading from PowerCLI 5.x to 6.5.1, then you should also check your scripts for any strong typing of VMware Impl objects. For more information see PowerCLI Best Practice: Correct Use of Strong Typing.

If you are already at PowerCLI 6.0 or greater on the device in question then you are probably good to go.

Unrelated Note About vSphere Tags

If your script is doing any vSphere Tagging, be aware that on vSphere 6.0 and greater you should be tagging as administrator@vsphere.local or take the time to assign the permissions needed.

Tagging was first introduced in PowerCLI 5.5 R2. This is a critical admin skill to master.

Profiles

The final thing to check is the PowerShell $PROFILE. For example, login as the desired user and then check if a PowerShell $PROFILE exists (Test-Path $PROFILE).

If Test-Path $PROFILE returns $true that means the profile exists. This indicates that someone created the profile using New-Item -Type File -Path $Profile -Force or similar). If it exists, it may contain uses of Add-PSSnapin. So, open it up and check it in an editor.

As an example, the following PowerShell snippet opens up the current user's PowerShell $PROFILE in the Microsoft ISE, if it exists. Open an elevated PowerShell prompt and paste in the following snippet. Then, hit enter a couple of times to make it run:

If(Test-Path $PROFILE) {
    ise $PROFILE
}

If a $PROFILE is found, it will open up in the ISE. Here we can check for Add-PSSnapin, just like you did with the other .ps1 files.

You would probably only go thumbing through profiles if you noticed a scheduled task that runs as a service account for example. Let's say you've already identified the .ps1 that it runs and cleaned that up; Checking the PowerShell $PROFILE for the user that calls that critical task is just good business. You never know how elaborate the tech before you was.

Also, at a minimum, be aware that there is a $PROFILE for the entire system, a $PROFILE for each user, and less importantly a $PROFILE for the ise.

For more info see Understanding the Six PowerShell Profiles

Remove PowerCLI From Control Panel

If this is a fresh install, you can skip this section. However, for upgrades to existing PowerCLI installations, there are a couple of steps to perform before installing PowerCLI 6.5.1.

Step 1 - Remove PowerCLI

If PowerCLI exists in Add/Remove Programs, it should first be removed before installing the PowerCLI 6.5.1 module.

  • Navigate to Control Panel > Add Remove Programs or similar
  • Locate VMware PowerCLI
  • Click Remove
  • No reboot required

Step 2 - Remove PowerCLI Folder

Now that we have removed PowerCLI from Control Panel, the final step is to remove the old PowerCLI folder, if it exists.

Warning: You should be caffeinated for this step! If you delete the wrong folder it could be catastrophic. Also, if you have not taken a snapshot yet, do so now.

Procedure

Being careful not to delete any parent folders, remove ONLY the PowerCLI folder (if it exists):
C:\Program Files (x86)\VMware\Infrastructure\PowerCLI

Install PowerCLI Latest

Once you have performed the above cleanup (if any), you are ready to install PowerCLI 6.5.1. There are two parts to using the the PSGallery version of PowerCLI. First, we find the module, then we install it. You only have to install once. After that, you can enjoy automatic loading.

Using Find-Module

First, we will connect to the Gallery and look for available versions. This is done with Find-Module.

If this is your first time accessing the PSGallery, you will be prompted to update components. Answer to the affirmative and you should be up and running with the latest PSGallery requirements within some seconds.

Find-Module -Name VMware.PowerCLI

Using Install-Module

Here we actually perform the installation of the latest PowerCLI available on the PSGallery (currently 6.5.1 at the time of this writing). We have a choice in how we install (CurrentUser or AllUsers).

You will typically do AllUsers unless you have a reason not to.

#Install For AllUsers
Install-Module -Name VMware.PowerCLI -Scope AllUsers -AllowClobber -Force

-or-

#Install for CurrentUser
Install-Module -Name VMware.PowerCLI -Scope CurrentUser -AllowClobber -Force

Future versions can be upgraded using native PSGallery functionality. That is not covered here, but will certainly be great (nothing to download!).

Start Using PowerCLI

Now that PowerCLI 6.5.1 is installed, you can just start using it. Right from your regular blue PowerShell, simply run a PowerCLI command and the appropriate module will load. Let's start by checking the version.

Get-PowerCLIVersion

The above command has been around forever, but will be deprecated eventually. You can also list the module version the official way:

Get-Module -Name VMware.PowerCLI -ListAvailable | Select-Object -ExpandProperty Version

Importing PowerCLI Manually

Not needed on PowerCLI 6.5.1 and later. However, you can manually import if desired. Remember that you will get a Welcome to PowerCLI message if you do (compared to auto loading which returns no welcome message).

Get-Module -Name VMware.PowerCLI -ListAvailable | Import-Module

-or-

Get-Module -Name VMware* -ListAvailable | Import-Module

Customize PowerCLI

The following shows my current PowerCLI configuration using Get-PowerCLIConfiguration. I have a few things customized.

You will notice that there are settings for Session, User, and AllUsers. Later, we will use Set-PowerCLIConfiguration with the Scope parameter to set these individually.

PS C:\> Get-PowerCLIConfiguration | fl *

DefaultVIServerMode         : Multiple
ProxyPolicy                 : NoProxy
ParticipateInCEIP           : True
CEIPDataTransferProxyPolicy : UseSystemProxy
DisplayDeprecationWarnings  : True
InvalidCertificateAction    : Ignore
WebOperationTimeoutSeconds  : 300
VMConsoleWindowBrowser      :
Scope                       : Session

DefaultVIServerMode         : Multiple
ProxyPolicy                 :
ParticipateInCEIP           : True
CEIPDataTransferProxyPolicy :
DisplayDeprecationWarnings  : True
InvalidCertificateAction    :
WebOperationTimeoutSeconds  :
VMConsoleWindowBrowser      :
Scope                       : User

DefaultVIServerMode         : Multiple
ProxyPolicy                 : NoProxy
ParticipateInCEIP           : False
CEIPDataTransferProxyPolicy :
DisplayDeprecationWarnings  : True
InvalidCertificateAction    : Ignore
WebOperationTimeoutSeconds  :
VMConsoleWindowBrowser      :
Scope                       : AllUsers

PS C:\>

Well, that's kind of boring because it's really the same thing three times. It's important to note that this exists though, so I am showing it. Observe that there is a section for each Scope in the above output.

Now, let's make a change to DisplayDeprecationWarnings for the local user's scope.

Set-PowerCLIConfiguration -Scope User -DisplayDeprecationWarnings:$false

As another example, let's make a change for the entire server (so all users benefit). For this, we can use the -Scope parameter again, but this time with a string value of AllUsers.

Set-PowerCLIConfiguration -Scope AllUsers -WebOperationTimeOut 600

The Scope parameter of Set-PowerCLIConfiguration is of type [VMware.VimAutomation.ViCore.Types.V1.ConfigurationScope]. However, it uses ValidateSet so you can tab complete through the options or just pass it the string value of 'Session', 'User' or 'AllUsers.

Honestly, you don't need to mess around with Scope unless you really like the granularity. If you just run the Set-PowerCLIConfiguration commands (without Scope), you will get the results you are looking for. In fact, most people don't even run the Set-PowerCLIConfiguration at all because the defaults are typically fine. YMMV.

SUMMARY

In this post, we reviewed the elements involved in a proper upgrade to PowerCLI 6.5.1. Specifically, we called attention to some of the items that are critical to upgrading a production installation. I hope it gets you thinking about what it means for you in your environment.

APPENDIX - Quick Upgrade Guide

For the full details and video examples, see the official PowerCLI 6.5.1 Install Walkthrough, PowerCLI Install Process for PowerShell Gallery, and the initial release post at VMware Blogs: New Release PowerCLI 6.5.1

STEPS

  • Upgrade Powershell to 5.1 (or 3.0 minimum)

    https://msdn.microsoft.com/en-us/powershell/wmf/5.1/install-configure

  • Uninstall PowerCLI from Control Panel > Add/Remove Programs

  • Remove the folder 'C:\Program Files (x86)\VMware\Infrastructure\PowerCLI' (if exists)

    Warning: Do not delete parent folders

  • Find-Module -Name VMware.PowerCLI #connects to PSGallery

  • Install-Module -Name VMware.PowerCLI -AllowClobber -Scope <AllUsers|CurrentUser> -Force

  • Get-Module -Name VMware.PowerCLI -ListAvailable | Import-Module #optional