Public/Start-PrismVM.ps1

function Start-PrismVM {
    <#
    .SYNOPSIS
        Turns on a VM.
 
    .DESCRIPTION
        Powers on the Virtual Machine with the given external identifier.
 
        This is a conditional operation: the v4 API requires the current ETag of the
        VM (supplied as an If-Match header). This function first performs a GET
        to obtain a fresh ETag for each VM.
 
    .NOTES
        Implements:
          POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/power-on (operationId: powerOnVm)
 
        Uses the selected session's ApiVersion for the endpoint.
 
    .PARAMETER PrismSession
        The server/FQDN of the PrismSession to use. May be omitted when only one session exists.
 
    .PARAMETER ExtId
        The globally unique identifier (UUID) of the VM to power on.
 
    .PARAMETER VM
        A PrismVM object, supplied explicitly or through the pipeline. Uses its
        ExtId and originating session unless -PrismSession is specified.
 
    .EXAMPLE
        Start-PrismVM -ExtId 'e731e375-c1de-4a2b-8c86-19a8b6968f3a'
 
    .OUTPUTS
        A PrismTask reference describing the asynchronous power-on task.
    #>


    [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'ByVM')]
    [OutputType([PrismTask])]
    param(
        [Parameter(Mandatory = $false,
            HelpMessage = 'Prism Session Name')][string]$PrismSession,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'ById',
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            HelpMessage = 'VM external identifier (UUID)')]
        [Alias('Id', 'VmExtId')][ValidateNotNullOrEmpty()][string]$ExtId,

        [Parameter(Mandatory = $true, ParameterSetName = 'ByVM', ValueFromPipeline = $true)]
        [ValidateNotNull()][PrismVM]$VM
    )

    process {
        $vmId = if ($PSCmdlet.ParameterSetName -eq 'ByVM') { $VM.ExtId } else { $ExtId }
        if ([string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' }
        $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByVM' -and -not $PSBoundParameters.ContainsKey('PrismSession')) {
            $VM.PrismSession
        } else { $PrismSession }
        if (-not $PSCmdlet.ShouldProcess($vmId, 'Power on VM')) { return }

        $PrismSessionConfig = Get-PrismSession $sessionName
        $vmPath = 'vmm/v{0}/ahv/config/vms/{1}' -f $PrismSessionConfig.ApiVersion, $vmId

        $requestETag = Get-PrismResourceEtag -PrismSession $PrismSessionConfig.Name -Path $vmPath

        $headers = @{
            'If-Match'        = $requestETag
            'NTNX-Request-Id' = (New-Guid).Guid
        }

        $RequestSplat = @{
            PrismSession = $PrismSessionConfig.Name
            Method       = 'POST'
            Path         = ('{0}/$actions/power-on' -f $vmPath)
            Header       = $headers
        }
        $Response = Invoke-PrismRequest @RequestSplat
        return [PrismTask]::new($Response.data, $PrismSessionConfig.Name)
    }
}