How do you "log a reason" using PowerCLI when rebooting or shutting down ESXi host?

I am sure many of you have seen this UI prompt asking you to specify a reason before issuing a reboot or shutdown of an ESXi host and I assume most of you spend a few seconds to type in a useful message and not just random characters, right? 😉

Have you ever tried performing the same reboot or shutdown operation using the vSphere API or PowerCLI (which leverages the API)? Have noticed, there is not a way to specify a message like you can in the UI?

Here is a table of the PowerCLI cmdlets and the respective vSphere API that is used to perform these two operations:

When looking at either the PowerCLI and/or vSphere API documentation, we can confirm that there are no fields to specify a message which can lead to an assumption that this is simply not possible or that the functionality might be provided by a private API. Fortunately, this is not the case and the functionality is in fact in the public vSphere API and has been for quite some time.

When you specify a message prior to rebooting or shutting down, this message is actually persisted and implemented as an Event within vCenter Server as shown in the screenshot below.

Instead of being able to specify a message that is only applicable to an ESXi host, I believe the original vSphere API designers thought that this functionality could also be useful and applied more broadly across any number of the vSphere Inventory objects, not just ESXi hosts. As such, this functionality which the vSphere UI uses is provided by the LogUserEvent() method which is part of the EventManager API. Customers or solutions can leverage this mechanism to log custom user defined events which is then persisted with the lifecycle fo the vSphere Inventory Object or as far back as your retention period for vCenter Server Events.

Going back to our original question, if you want to specify a message prior to rebooting or shutting down an ESXi host, the following snippet below demonstrates the use of the vSphere API via PowerCLI:

$eventManager = Get-View eventManager
$vmhost = Get-VMHost -Name 192.168.30.11
$message = "This message will be logged"

$eventManager.LogUserEvent($vmhost.ExtensionData.MoRef,$message)