Working with Custom Attributes in PowerCLI

I recently had a need to create some custom attributes for Clusters and VMs in vCenter. Having previously done this a few times a while back in vCenter I fired up Set-CustomField in PowerCLI 5.1, but was greeted with the following message:

$VM | Set-CustomField -Name "TestAttribute" -Value "True" WARNING: Use Set-CustomAttribute cmdlet. WARNING: The 'Set-CustomField' cmdlet is deprecated. Use the 'Set-CustomAttribute' cmdlet instead.

So it would work fine now, but going forward some of my code would be deprecated and potentially not work when PowerCLI was upgraded, so I looked for what the options now were, but before we do a quick review of what Set-CustomField gave you.

Having created the above, an additional column TestAttribute would be available in the vSphere client.

and is also viewable on the VM summary page

The additional TestAttribute column is also available in the vSphere web client:

However, it is not available in the summary page of the VM (admittedly you can’t add them here via the GUI either, like you can in the C# client):

In terms of accessing this data via PowerCLI there are a couple of ways to get at it:

$VM | Get-Annotation

$VM.CustomFields.Item("TestAttribute")

These commands always seemed slightly strange in that there was no Get-CustomField cmdlet, Set-CustomField could create a new one and also to remove a custom attribute you needed to specify a single entity, selecting multiple would result in errors after the first one, e.g. Get-VM | Remove-CustomField would remove the custom field after the first VM, but then subsequently produce an error.

$VM | Remove-CustomField -Name "TestAttribute"

Get-Command \*Field\*

So moving on, what is available now? Enter the Verb-Attribute cmdlets:

Get-Command \*Attribute\*

we now have a Get cmdlet, to access those already created.

Now we must first create the custom attribute, then we can view created custom attributes with Get-CustomAttribute and set values with Set-Annotation

New-CustomAttribute -TargetType "VirtualMachine" -Name "TestAttribute2"

$VM | Set-Annotation -CustomAttribute "TestAttribute2" -Value "True"

Get-CustomAttribute

The data can be accessed the same way as before using PowerCLI

$VM | Get-Annotation

$VM.CustomFields.Item("TestAttribute")

From a GUI perspective, the story is the same as before:

We can now remove the custom attribute in a more typical PowerShell style:

Get-CustomAttribute -Name "TestAttribute2" | Remove-CustomAttribute -Confirm:$false

One thing to watch out for that tripped me up with this change was when I used New-CustomAttribute to create a custom attribute with multiple TargetTypes, e.g. Cluster,VirtualMachine. While this worked fine in my test environment using PowerCLI 5.1, when I ran the code in production to subsequently Set-Annotation on a new attribute it would fail with the issue detailed here. Turned out that the PowerCLI version in production was 5.0.

Set-Annotation: The specified parameter 'CustomAttribute' expects a single value, but your name criteria 'TestAttribute' corresponds to multiple values

It hasn’t been confirmed yet, but it looks like there is an issue with Set-Annotation in PowerCLI 5.0 that is fixed in 5.1.