The following is a write up of a part of session HBI1729BU ,that was presented at VMworld US 2019.

The code shown in this post is also available in the PowerCLI Community Repository.

Concept

The idea behind this snippet came when I had checked what was in $global:DefaultVIServers for the n-th time in a short PowerCLI session.

And it’s probably not only that specific variable that must be all too familiar to most of us. Any entry in the following list of variables and cmdlets must have been executed by most of us multiple times.

$Global:DefaultVIServer
$Global:DefaultVIServers
$PSVersionTable
Get-Location
Get-Module -Name VMware.PowerCLI

It would be an important timesaver, when the information returned by those instructions, would be permanently in view. At your fingertips, so to say.

The use of the PowerShell profile(s) and the Prompt function, immediately came to mind.

Not to overload your PS prompt, I decided to show part of the information in the console’s Window Title bar. That can be done by assigning a value to $host.ui.RawUI.WindowTitle. 

Implementation

The Code

#
# Provide environment information in the PS Console
#
# History:
# 1.0 - August 4th 2019 - LucD
#       Initial version (for session HBI1729BU VMworld US 2019)
#
# 1) PS prompt
# - current (local) time
# - execution time of the previous command
# - shortened PWD
# 2) Window title
# - User/Admin
# - PS-32/54-Edition-Version
# - PCLI version
# - git repo/branch
# - VC/ESXi:defaultServer-User [# connections]

function prompt
{
    # Current time
    $date = (Get-Date).ToString('HH:mm:ss')
    Write-Host -Object '[' -NoNewline
    Write-Host -Object $date -ForegroundColor Cyan -BackgroundColor DarkBlue -NoNewline
    Write-Host -Object ']' -NoNewline

    # Execution time previous command
    $history = Get-History -ErrorAction Ignore -Count 1
    if ($history)
    {
        $time = ([DateTime](New-TimeSpan -Start $history.StartExecutionTime -End $history.EndExecutionTime).Ticks).ToString('HH:mm:ss.ffff')
        Write-host -Object '[' -NoNewLine
        Write-Host -Object "$time" -ForegroundColor Yellow -BackgroundColor DarkBlue -NoNewline
        Write-host -Object '] ' -NoNewLine
    }

    # Shorted PWD
    $path = $pwd.Path.Split('\')
    if ($path.Count -gt 3)
    {
        $path = $path[0], '..', $path[-2], $path[-1]
    }
    Write-Host -Object "$($path -join '\')" -NoNewline

    # Prompt function needs to return something,
    # otherwise the default 'PS>' will be added
    "> "

    # Refresh the window's title
    Set-Title
}

function Set-Title
{
    # Running as Administrator or a regular user
    $userInfo = [Security.Principal.WindowsIdentity]::GetCurrent()
    if ((New-Object Security.Principal.WindowsPrincipal $userInfo).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator))
    {
        $role = 'Admin'
    }
    else
    {
        $role = 'User'
    }

    # Usertype user@hostname
    $user = "$role $($userInfo.Name)@$($env:computername)"

    # PowerShell environment/PS version
    $bits = 32
    if ([Environment]::Is64BitProcess)
    {
        $bits = 64
    }
    $ps = " - PS-$($bits): $PSEdition/$($PSVersionTable.PSVersion.ToString())"

    # PowerCLI version (derived from module VMware.PowerCLI)
    $pcliModule = Get-Module -Name VMware.PowerCLI -ListAvailable |
    Sort-Object -Property Version -Descending |
    Select-Object -First 1
    $pcli = " - PCLI: $(if($pcliModule){$pcliModule.Version.ToString()}else{'na'})"

    # If git is present and if in a git controlled folder, display repositoryname/current_branch
    $gitStr = ''
    if ((Get-Command -Name 'git' -CommandType Application -ErrorAction SilentlyContinue).Count -gt 0)
    {
        $gitTopLevel = git rev-parse --show-toplevel 2> $null
        if ($gitTopLevel.Length -ne 0)
        {
            $gitRepo = Split-Path -Path $gitTopLevel -Leaf
            $gitBranch = (git branch | Where-Object { $_ -match "\*" }).Trimstart('* ')
            $gitStr = " - git: $gitRepo/$gitBranch"
        }
    }

    # If there is an open vSphere Server connection
    # display [VC|ESXi] last_connected_server-connected_user [number of open server connections]
    if ($global:defaultviserver)
    {
        $vcObj = (Get-Variable -Scope global -Name 'DefaultVIServer').Value
        if ($vcObj.ProductLine -eq 'vpx')
        {
            $vcSrv = 'VC'
        }
        else
        {
            $vcSrv = 'ESXi'
        }
        $vc = " - $($vcSrv): $($vcObj.Name)-$($vcObj.User) [$($global:DefaultVIServers.Count)]"
    }

    # Update the Window's title
    $host.ui.RawUI.WindowTitle = "$user$ps$pcli$vc$gitStr"
}

# Set title after starting session
Set-Title

Annotations

Line 19-51: Replacement function for the PS prompt.

Line 22-25: Current time in the format ‘HH:mm:ss’. Note that ‘HH’ asks for a 24-hour value.

Line 28-35: The execution time of the previous command, in the format ‘HH:mm:ss:ffff’.

Line 28: The execution time is based on the content of PS History. With Get-History we obtain the start time of the command, and with New-TimeSpan we obtain the duration for running that command.

Line 38-43: These lines take the path to the current folder, and shorten that path to only show the start of the path and the last two directories. When the path is shortened, it is indicated by two dots.

Line 53-114: Function to populate the Windows Title bar

Line 56-64: These lines determine if the PS session is started “As Administrator” or as a regular user.

Line 67: The user and station information.

Line 70-75: The PS edition (Desktop or Core) and the PS version.

Line 78-81: If installed, the version of VMware PowerCLI. Note that this looks at the VMware.PowerCLI module to obtain that version number.

Line 84-94: If the git command is present on the station, these lines will check if the current directory is inside a git repository. It will then display the name of the git repository and the current branch.

Line 98-110: These lines check if there is an open connection to a vSphere Server. It will show if the connected vSphere Server is a vCenter or an ESXi node.

Line 109: If multiple connections to a vSphere Servers are open, this will display the number of these connections. The vSphere Server that is shown is the last connected one. This corresponds with what is kept in the $global:DefaultVIServer variable.

Line 117: Initial call to the Set-Title function. This will populate the Windows Title bar when the PS console is opened.

Installation

You can just copy and rename the code to one of the profile files. To make that process easier, I also provide the following installation script.

[cmdletbinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
param(
    #        [Parameter(Mandatory = $true)]
    [ValidateSet('CurrentUserCurrentHost', 'CurrentUserAllHosts',
        'AllUsersCurrentHost', 'AllUsersAllHosts')]
    [string]$Scope,
    [switch]$NoClobber,
    [switch]$Backup,
    [string]$NewProfile = '.\NewProfile.ps1'
)

if ($PSCmdlet.ShouldProcess("$($Profile.$Scope)", "Create $Scope profile"))
{
    $profilePath = $Profile."$Scope"
    Write-Verbose -Message "Target is $profilePath"
    $createProfile = $true
    if (Test-Path -Path $profilePath)
    {
        Write-Verbose -Message "Target exists"
        if ($NoClobber)
        {
            Write-Verbose -Message "Cannot overwrite target due to NoClobber"
            $createProfile = $false
        }
        elseif ($Backup)
        {
            Write-Verbose -Message "Create a backup as $profilePath.bak"
            Copy-Item -Path $profilePath -Destination "$profilePath.bak" -Confirm:$false -Force
        }
        elseif (-not $NoClobber)
        {
            Write-Verbose -Message "Target will be overwritten"
        }
        else
        {
            Write-Verbose -Message "Use -NoClobber:$false or -Backup"
        }
    }
    if ($createProfile)
    {
        if (-not $NewProfile)
        {
            $script:MyInvocation.MyCommand | select *
            $folder = Split-Path -Parent -Path $script:MyInvocation.MyCommand.Path
            $folder = Get-Location
            $NewProfile = "$folder\NewProfile.ps1"
        }
        Write-Verbose -Message "New profile expected at $NewProfile"
        if (Test-Path -Path $NewProfile)
        {
            Write-Verbose -Message "Copy $NewProfile to $profilePath"
            Copy-Item -Path $NewProfile -Destination $profilePath -Confirm:$false
        }
        else
        {
            Write-Warning -Message "Could not find the new profile file!"
            Write-Warning -Message "Use the NewProfile parameter or store a NewProfile.ps1 file in folder $folder."
        }
    }
}

Save the above code to a .ps1 file, let’s say install-profile.ps1. Also copy the profile code to a .ps1 file, let’s say newprofile.ps1.

You can now install this new profile with a simple call.

.\install-profile.ps1 -NewProfile .\NewProfile.ps1 -Scope CurrentUserCurrentHost -Backup 

The installation script has a number of parameters:

• NewProfile : the file that contains the profile you want to install
• Scope : for which Scope you want to install the new profile.
• Backup : backup the current profile before overwriting it.
• NoClobber : avoids overwriting an existing profile file.

Usage

When the new profile is installed, and when you restart your console session, you will see the new profile in action.

The following screenshot shows the features of the new profile.

And the following short video shows the installation process and the features the profile offers.

Enjoy!

In the XML file the configuration settings of each node are present in the Config nodes.

With the following script you select one of the nodes as the reference node and the script will then compare the config properties of all the other nodes against this reference node.

The script will produce a CSV file that contains all differences.

Note that a lot of these differences are quite obvious, like for example hostname, MAC address…, and can thus be safely ignored during the review.

The CSV file has this layout

The first column, named Path, is the XMLPath to the property in the XML file.

The 2nd and 3rd columns show the name of the reference node (RefHost) and the name of the node (CmpHost) that was compared against the reference node.

The Name column shows the name of the property.

The RefValue and CmpValue show the property values that were found on the reference node and on the node that was compared against the reference node.

The AttributeDiscrepancy and the ChildrenDiscrepancy columns are Boolean flags that show if the script at one point lost synchronisation between the RefHost and the CmpHost for the attributes or for the child nodes.

As an example of the possible benefit of such a comparison, I discovered that on my test environment the CSV file showed a difference for the Inventory/Cluster/Host/Config/Firewall/Ruleset Count between the two cluster nodes.

This indicated that the firewall rules on both ESX nodes were not the same. And indeed after further checking I discovered that I forgot to active a firewall rule on the 2nd node.

Note that current script is not too intelligent. It will not try to synchronise between the two nodes when one of the nodes is missing an entry. As an example you will notice that the firewall rules will run async from a certain point onwards. On the other hand this also gives you a good indication where the problem is located. In this case the aam firewall rule was missing on the 2nd node.

As an example let’s take the “Enable VM Monitoring” option for a cluster.

This option belongs to the HA settings of a cluster. The only fact you have to know, is that the HA settings of a cluster are stored under the DAS properties in the SDK. And that is most probably the case for historical reasons.

In the XML file that contains the cluster’s profile we can easily find the property.

The next step is to find out how we can change the property.A method I use regularly, and which works in most cases, is the following.

The VmMonitoring property belongs to the ClusterDasConfigInfo object as can be seen in the Type attribute..

In the vSphere API Reference Documentation we go, via the Data Object Types, to the ClusterDasConfigInfo object. At the top of the right panel we see that the object is a property of the ClusterConfigSpec.

Via the hyperlink we go to the description of that object. On the reference page we see that the ClusterConfigSpec object is a parameter to the ReconfigureCluster_Task method.

The ReconfigureCluster_Task page contains a message that states we should use the ReconfigureComputeResource_Task since API 2.5. Since we are working in a vSphere environment, which is API 4.0, we go for the new method.

On the reference page for the ReconfigureComputeResource_Task method we see which parameters we will need.

How to call _Task methods from the SDK will be the subject of another post.

This is part 1 of these scripts. This script shows and explains how I used PowerShell to export the configuration of my vSphere environment, or part of it, to an XML file.

If you investigate any of the Managed Objects which are based on the ManagedEntity object, in your vSPhere environment, you will notice that all configuration parameters are contained in an object under the property called configuration or configurationEx.

For example within a HostSystem object there is a configuration object.

Within a ComputeResource object there is since API 2.5 a configurationEx object.

If we could “dump” the content in a usable format to an external file, we would have an exact description of the Managed Object on file.

That’s when I came up with the following script. It will start from an vSphere inventory location, and from there it will write all the configuration parameters to an XML file.

The concept of recursively investigating all the properties of a managed object has been done before, in a somewhat different form, by Hugo Peeters. See his List ALL properties and subproperties of a variable in Powershell article.

The following script exports all properties to an XML file.

The script takes a number of parameters that determine what will be exported to the XML file.

Looking at resulting XML file (which can be quite big depending on the size of your vSPhere environment), you notice that the Hosts & Clusters view on the cluster is present. For each of the cluster elements the XML file also contains all the configuration properties.

<span style="text-decoration: underline;">Note</span>: I use <a href="http://www.xmlpad.com/xmlpad3.htm">XMLPad 3</a> to browse the XML files. The screenshot shows the Table View.

In the Config and ConfigurationEx nodes you can find all the properties of these objects. This gives you an easy and offline method if looking up specific settings and configuration options for the cluster.

The previous screenshot shows how you can, for example,  easily report on the NTP settings of an ESX server.

Another useful feature is that these XML files allow you to keep an audit track of the configuration of your vSphere environment. There are a number of 3rd party tools available that allow you compare XML files.

The XML file also tells you what type a specific property is. For arrays the script uses a special convention to show the array elements. Since an XML nodename can’t contain square brackets, the array elements are shown as Server-0- instead of Server[0].