Public/Stop-PrismVM.ps1

function Stop-PrismVM {
    <#
    .SYNOPSIS
        Turns off a VM, either by a forced power-off or by an ACPI shutdown.
 
    .DESCRIPTION
        Stops the Virtual Machine with the given external identifier.
 
        -Method AcpiShutdown (default) performs a collaborative shutdown through the ACPI
        support in the guest operating system. This maps to the "Shutdown the VM using
        ACPI" endpoint.
 
        -Method PowerOff forcibly shuts down the VM, equivalent to removing the power
        cable. This maps to the "Turn off a VM" / "Force power off" endpoint and may
        cause data loss if operations are in progress.
 
        Both are conditional operations: 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-off (operationId: powerOffVm)
          POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/shutdown (operationId: shutdownVm)
 
        Uses the selected session's ApiVersion for both endpoints.
 
    .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 stop.
 
    .PARAMETER Method
        'AcpiShutdown' (default) for a graceful ACPI shutdown, or 'PowerOff' for a
        forced power-off.
 
    .PARAMETER VM
        A PrismVM object, supplied explicitly or through the pipeline. Uses its
        ExtId and originating session unless -PrismSession is specified.
 
    .EXAMPLE
        Stop-PrismVM -ExtId '40ca3d2a-daf3-4de9-969d-b25e5175c223'
 
    .EXAMPLE
        Stop-PrismVM -ExtId '40ca3d2a-daf3-4de9-969d-b25e5175c223' -Method PowerOff
 
    .OUTPUTS
        A PrismTask reference describing the asynchronous 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,

        [Parameter(Mandatory = $false)]
        [ValidateSet('AcpiShutdown', 'PowerOff')]
        [string]$Method = 'AcpiShutdown'
    )

    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 }
        $action = $Method -eq 'AcpiShutdown' ? 'shutdown' : 'power-off'

        if (-not $PSCmdlet.ShouldProcess($vmId, "Stop VM ($Method)")) { 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/{1}' -f $vmPath, $action)
            Header       = $headers
        }
        $Response = Invoke-PrismRequest @RequestSplat
        return [PrismTask]::new($Response.data, $PrismSessionConfig.Name)
    }
}