Home > Blogs > VMware PowerCLI Blog

PowerCLI 6.3 R1: Get-ESXCLI Why the V2?

If you have installed the latest release of PowerCLI (6.3 R1) then you may have noticed a warning if you have run the Get-ESXCLI cmdlet that looks a little like this:

image

What does it mean?

Whilst talking to the community and listening to our customers we heard that there were a couple of issues with this cmdlet, some that lead to problems with scripts breaking when being used against environments that have more than one version of ESX or maybe upgraded versions of ESX using older scripts with this cmdlet.  Lets take a bi of a deeper dive into these issues so you can understand why we made the change and how the new –V2 version is so much better!

Lets discuss the 2 main problems….

1. Positional values and the $null variable

When using the Get-ESXCLI cmdlet we would only allow invocation based on positional parameters, this was somewhat painful as providing just 1 parameter for a esxcli which had 15 options would result in long, weird looking scripts with a lot of $null parameters to fill the blanks, it was hard to work out which parameters where needed and where they fit in between the $null entires.  Lets take a look at the “ESXCLI network diag ping” namespace for example, to call this namespace and ping a given address twice in ESXCLI you would need to call the namespace with a –count and a –host option as per the docs here.  We would have had to find out where to put these when calling the Get-ESXCLI cmdlet and where to add the $null for everything we didn’t want to use.

Once done we would end up with a script which may look like the following:

$esxcli = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1)

$esxcli.network.diag.ping(2,$null,$null,“10.0.0.8”,$null,$null,$null,$null,$null,$null,$null,$null)

Not the most intuitive way to do things but it worked right?! Well, yeah kind of but that leads us to problem 2…

2.  Mixed environments or upgraded environments

One of the rules for updating ESXCLI namespaces is that you are allowed to add options but not remove or modify existing ones, this stops breaking changes for anyone using ESXCLI in a script, the issue was that when people were using these through PowerCLI and potentially using it against multiple hosts of different versions we could have a different number of $null parameters as we need one for every parameter we don’t use.

For example, we may have the following example in ESX 5.1:

$esxcli = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1)

$esxcli.network.diag.ping(2,$null,$null,“10.0.0.8”,$null,$null,$null,$null,$null,$null,$null,$null)

This may work fine but then what if we at VMware extending this namespace to give it an extra option, we would need an extra $null through Get-ESXCLI, so for example in ESX 5.5 this may be:

$esxcli = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1)

$esxcli.network.diag.ping(2,$null,$null,“10.0.0.8”,$null,$null,$null,$null,$null,$null,$null,$null,$null)

As you can see, if we ran either the 5.1 version against a 5.5 hosts or the 5.5 version against the 5.1 host we would have errors and broken scripts.  Of course you could check for each version but this starts to get complex when sharing scripts for others to use and the multiple versions of esxcli namespaces we have out there.

So what does V2 do that’s different?

The Get-ESXCLI cmdlet has now been updated with a –V2 parameter which supports specifying method arguments by name, essentially we are able to fix both issues above and provide an easier way to explore what an ESXCLI namespace requires and allow us to provide only the items we care about, lets walk though the same example but using the –V2 switch

Firstly lets store the new version in a variable like we did above:

$esxcli2 = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1) -V2

Next we can find out what options are available to set for the namespace by calling the new CreateArgs method and storing this in a variable:

$arguments = $esxcli2.network.diag.ping.CreateArgs()

Now we can see what’s in the variable by calling it:

PowerCLI C:\> $arguments

Name                           Value
—-                           —–
host                           Unset, ([string], optional)
wait                           Unset, ([string], optional)
df                             Unset, ([boolean], optional)
interval                       Unset, ([string], optional)
ttl                            Unset, ([long], optional)
debug                          Unset, ([boolean], optional)
nexthop                        Unset, ([string], optional)
count                          Unset, ([long], optional)
netstack                       Unset, ([string], optional)
size                           Unset, ([long], optional)
ipv4                           Unset, ([boolean], optional)
ipv6                           Unset, ([boolean], optional)
interface                      Unset, ([string], optional)

As you can see, its helped us out here, it has prefilled this array with the options we can specify, now all we need to do is assign values to the entries we want to use:

$arguments.count = 2

$arguments.host = “10.0.0.8”

If we look at what’s in the variable again we can see we have set just the two entries we need:

PowerCLI C:\> $arguments

Name                           Value
—-                           —–
host                           10.0.0.8
wait                           Unset, ([string], optional)
df                             Unset, ([boolean], optional)
interval                       Unset, ([string], optional)
ttl                            Unset, ([long], optional)
debug                          Unset, ([boolean], optional)
nexthop                        Unset, ([string], optional)
count                          2
netstack                       Unset, ([string], optional)
size                           Unset, ([long], optional)
ipv4                           Unset, ([boolean], optional)
ipv6                           Unset, ([boolean], optional)
interface                      Unset, ([string], optional)

Next all we need to do is send these options back by using the Invoke method and providing our set $arguments variable:

$esxcli2.network.diag.ping.Invoke($arguments)

lets put this together so you can see how easy this is now:

$esxcli2 = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1) -V2

$arguments = $esxcli2.network.diag.ping.CreateArgs()

$arguments.count = 2

$arguments.host = “10.0.0.8”

$esxcli2.network.diag.ping.Invoke($arguments)

Conclusion

As you can see, not only is this much easier to understand but we also don’t have to use lots of $null entries and it will also work against multiple versions of ESXi or allow you to share your scripts knowing that they will work against any version of ESXi that supports the namespaces you used in ESXCLI.

A Win, Win situation here, so why wouldn’t you use the –V2 option?!

This entry was posted in ESXCLI and tagged on by .
Alan Renouf

About Alan Renouf

Alan Renouf is a Product Line Manager at VMware focusing on API's, SDK's and CLI's, He is responsible for providing the architects and operators of private and public cloud infrastructure with the toolkits/frameworks and command-line interfaces they require to build a fully automated software-defined datacenter. Alan is a frequent blogger at http://blogs.vmware.com/PowerCLI a book author and has a personal blog at http://virtu-al.net. You can follow Alan on twitter as @alanrenouf.



PowerCLI 6.3 R1: Get-ESXCLI Why the V2?

If you have installed the latest release of PowerCLI (6.3 R1) then you may have noticed a warning if you have run the Get-ESXCLI cmdlet that looks a little like this:

image

What does it mean?

Whilst talking to the community and listening to our customers we heard that there were a couple of issues with this cmdlet, some that lead to problems with scripts breaking when being used against environments that have more than one version of ESX or maybe upgraded versions of ESX using older scripts with this cmdlet.  Lets take a bi of a deeper dive into these issues so you can understand why we made the change and how the new –V2 version is so much better!

Lets discuss the 2 main problems….

1. Positional values and the $null variable

When using the Get-ESXCLI cmdlet we would only allow invocation based on positional parameters, this was somewhat painful as providing just 1 parameter for a esxcli which had 15 options would result in long, weird looking scripts with a lot of $null parameters to fill the blanks, it was hard to work out which parameters where needed and where they fit in between the $null entires.  Lets take a look at the “ESXCLI network diag ping” namespace for example, to call this namespace and ping a given address twice in ESXCLI you would need to call the namespace with a –count and a –host option as per the docs here.  We would have had to find out where to put these when calling the Get-ESXCLI cmdlet and where to add the $null for everything we didn’t want to use.

Once done we would end up with a script which may look like the following:

$esxcli = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1)

$esxcli.network.diag.ping(2,$null,$null,“10.0.0.8”,$null,$null,$null,$null,$null,$null,$null,$null)

Not the most intuitive way to do things but it worked right?! Well, yeah kind of but that leads us to problem 2…

2.  Mixed environments or upgraded environments

One of the rules for updating ESXCLI namespaces is that you are allowed to add options but not remove or modify existing ones, this stops breaking changes for anyone using ESXCLI in a script, the issue was that when people were using these through PowerCLI and potentially using it against multiple hosts of different versions we could have a different number of $null parameters as we need one for every parameter we don’t use.

For example, we may have the following example in ESX 5.1:

$esxcli = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1)

$esxcli.network.diag.ping(2,$null,$null,“10.0.0.8”,$null,$null,$null,$null,$null,$null,$null,$null)

This may work fine but then what if we at VMware extending this namespace to give it an extra option, we would need an extra $null through Get-ESXCLI, so for example in ESX 5.5 this may be:

$esxcli = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1)

$esxcli.network.diag.ping(2,$null,$null,“10.0.0.8”,$null,$null,$null,$null,$null,$null,$null,$null,$null)

As you can see, if we ran either the 5.1 version against a 5.5 hosts or the 5.5 version against the 5.1 host we would have errors and broken scripts.  Of course you could check for each version but this starts to get complex when sharing scripts for others to use and the multiple versions of esxcli namespaces we have out there.

So what does V2 do that’s different?

The Get-ESXCLI cmdlet has now been updated with a –V2 parameter which supports specifying method arguments by name, essentially we are able to fix both issues above and provide an easier way to explore what an ESXCLI namespace requires and allow us to provide only the items we care about, lets walk though the same example but using the –V2 switch

Firstly lets store the new version in a variable like we did above:

$esxcli2 = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1) -V2

Next we can find out what options are available to set for the namespace by calling the new CreateArgs method and storing this in a variable:

$arguments = $esxcli2.network.diag.ping.CreateArgs()

Now we can see what’s in the variable by calling it:

PowerCLI C:\> $arguments

Name                           Value
—-                           —–
host                           Unset, ([string], optional)
wait                           Unset, ([string], optional)
df                             Unset, ([boolean], optional)
interval                       Unset, ([string], optional)
ttl                            Unset, ([long], optional)
debug                          Unset, ([boolean], optional)
nexthop                        Unset, ([string], optional)
count                          Unset, ([long], optional)
netstack                       Unset, ([string], optional)
size                           Unset, ([long], optional)
ipv4                           Unset, ([boolean], optional)
ipv6                           Unset, ([boolean], optional)
interface                      Unset, ([string], optional)

As you can see, its helped us out here, it has prefilled this array with the options we can specify, now all we need to do is assign values to the entries we want to use:

$arguments.count = 2

$arguments.host = “10.0.0.8”

If we look at what’s in the variable again we can see we have set just the two entries we need:

PowerCLI C:\> $arguments

Name                           Value
—-                           —–
host                           10.0.0.8
wait                           Unset, ([string], optional)
df                             Unset, ([boolean], optional)
interval                       Unset, ([string], optional)
ttl                            Unset, ([long], optional)
debug                          Unset, ([boolean], optional)
nexthop                        Unset, ([string], optional)
count                          2
netstack                       Unset, ([string], optional)
size                           Unset, ([long], optional)
ipv4                           Unset, ([boolean], optional)
ipv6                           Unset, ([boolean], optional)
interface                      Unset, ([string], optional)

Next all we need to do is send these options back by using the Invoke method and providing our set $arguments variable:

$esxcli2.network.diag.ping.Invoke($arguments)

lets put this together so you can see how easy this is now:

$esxcli2 = Get-ESXCLI -VMHost (Get-VMhost | Select -first 1) -V2

$arguments = $esxcli2.network.diag.ping.CreateArgs()

$arguments.count = 2

$arguments.host = “10.0.0.8”

$esxcli2.network.diag.ping.Invoke($arguments)

Conclusion

As you can see, not only is this much easier to understand but we also don’t have to use lots of $null entries and it will also work against multiple versions of ESXi or allow you to share your scripts knowing that they will work against any version of ESXi that supports the namespaces you used in ESXCLI.

A Win, Win situation here, so why wouldn’t you use the –V2 option?!

This entry was posted in ESXCLI and tagged on by .
Alan Renouf

About Alan Renouf

Alan Renouf is a Product Line Manager at VMware focusing on API's, SDK's and CLI's, He is responsible for providing the architects and operators of private and public cloud infrastructure with the toolkits/frameworks and command-line interfaces they require to build a fully automated software-defined datacenter. Alan is a frequent blogger at http://blogs.vmware.com/PowerCLI a book author and has a personal blog at http://virtu-al.net. You can follow Alan on twitter as @alanrenouf.

13 thoughts on “PowerCLI 6.3 R1: Get-ESXCLI Why the V2?

  1. Chris Sprinkle

    While this change certainly makes it easier when faced with a large number of parameters, unless I’m missing the right method, it makes the simple task of something like listing modules more complex. Previously, after creating the esxcli connection ($esxcli = Get-ESX hostname), to list the modules required $esxcli.system.module.list() and nothing more. Similarly, listing the current claimrules required $esxcli.storage.core.claimrule.list(). Now we must go through the process of creating the arguments and setting them when all we needed was a simple list.

    For now, when I’m just at the PowerCLI prompt and performing adhoc commands I can just use the previous version. Within scripts I can perform the added steps to allow the compatibility between different versions of ESXi. Unfortunately the warning about using the older version indicates that it is deprecated.

    Thanks for the work you’ve done with PowerCLI. I couldn’t get work done without it.

    Reply
    1. Chris Sprinkle

      I’ll correct myself before someone else does. 🙂

      Apparently it was as simple as adding .Invoke() to the end of the .list method. Pretty easy. I retract what I replied earlier since V2 is the way to go now.

      Live and learn.

      Reply
  2. Pingback: ESXCLI updates in PowerCLI 6.3 R1 | Cody Hosterman

  3. gajendra d ambi

    what is the netstack option here? can it be used to change the tcpip stack? like creating l3 vmotion portgroup? because i tried and it didnt work 🙁

    Reply
  4. Pingback: Get-EsxCli on steroids - The Crazy Consultant

  5. Pingback: Doppele 3Par LUN Exporte für ESXi erkennen - my cloud-(r)evolution

  6. Pingback: Script - PowerCLI SCSI UNMAP Funktion - my cloud-(r)evolution

  7. Pingback: PowerCLI study guide – core concepts - The Crazy Consultant

  8. Pingback: Script - SCSI Unmap (VAAI UNMAP) - my cloud-(r)evolution

  9. Rahul

    Great ,You have cleared my confusion .It is really helpful. The way you explained each and everything in your article is really great. Thanks for sharing.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*