Public/Set-PrismNgtSetting.ps1

function Set-PrismNgtSetting {
    <#
    .SYNOPSIS
        Updates the Nutanix Guest Tools settings of a VM.
    .DESCRIPTION
        Sets the VM's enabled NGT capabilities. VSS maps to VSS_SNAPSHOT and SSR
        maps to SELF_SERVICE_RESTORE. The supplied list replaces the capabilities;
        include both VSS and SSR to enable both. Retrieves the current NGT payload
        and preserves its other fields, including guest status, in the PUT body.
        Uses a PrismVM's originating session unless explicitly overridden.
        Uses the selected session's ApiVersion and returns an asynchronous PrismTask.
    .PARAMETER VM
        A PrismVM, supplied explicitly or through the pipeline.
    .PARAMETER ExtId
        The VM external identifier (UUID), instead of a VM object.
    .PARAMETER Capabilities
        The desired NGT capabilities: VSS and/or SSR. An empty array clears the list.
    .PARAMETER PrismSession
        The server/FQDN of the session. Overrides the VM's originating session.
        May be omitted for ID lookup when only one session exists.
    .EXAMPLE
        $vm | Set-PrismNgtSetting -Capabilities VSS, SSR | Wait-PrismTask
    .EXAMPLE
        Set-PrismNgtSetting -ExtId $vmId -Capabilities VSS -PrismSession 'pc.lab.local'
    .OUTPUTS
        PrismTask
    .NOTES
        PUT /vmm/v{ApiVersion}/ahv/config/vms/{extId}/guest-tools
        VSS is enabled through the VSS_SNAPSHOT capability. IsVssSnapshotCapable
        reports guest status; changing that property does not enable VSS.
    #>

    [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'ByVM')]
    [OutputType([PrismTask])]
    param(
        [Parameter(Mandatory, ParameterSetName = 'ByVM', Position = 0, ValueFromPipeline)]
        [ValidateNotNull()][PrismVM]$VM,

        [Parameter(Mandatory, ParameterSetName = 'ById', Position = 0,
            ValueFromPipeline, ValueFromPipelineByPropertyName)]
        [Alias('Id', 'VmExtId')][ValidateNotNullOrEmpty()][string]$ExtId,

        [Parameter(Mandatory)][AllowEmptyCollection()][ValidateCount(0, 2)]
        [ValidateSet('VSS', 'SSR')][string[]]$Capabilities,

        [Parameter()][string]$PrismSession
    )

    process {
        $vmId = if ($PSCmdlet.ParameterSetName -eq 'ByVM') { $VM.ExtId } else { $ExtId }
        if ([string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' }
        if (-not $PSCmdlet.ShouldProcess($vmId, 'Update NGT capabilities')) { return }

        $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByVM' -and -not $PSBoundParameters.ContainsKey('PrismSession')) {
            $VM.PrismSession
        } else { $PrismSession }
        $sessionConfig = Get-PrismSession $sessionName
        $path = 'vmm/v{0}/ahv/config/vms/{1}/guest-tools' -f $sessionConfig.ApiVersion, $vmId
        # Prism validates status fields in the PUT body too. Omitting a true
        # status such as isReachable can be interpreted as an invalid false value.
        # Read the body and ETag together so the update uses one current snapshot.
        $GetSplat = @{
            PrismSession     = $sessionConfig.Name
            Method           = 'GET'
            Path             = $path
            PassThruResponse = $true
        }
        $current = Invoke-PrismRequest @GetSplat
        $body = ($current.Content | ConvertFrom-Json -AsHashtable -ErrorAction Stop).data
        if ($body -isnot [System.Collections.IDictionary]) {
            throw "No NGT settings were returned for VM '$vmId'."
        }
        $requestETag = @($current.Headers.ETag)[0]
        if (-not $requestETag) { throw "No ETag was returned for VM '$vmId' NGT settings." }

        $capabilityMap = @{ VSS = 'VSS_SNAPSHOT'; SSR = 'SELF_SERVICE_RESTORE' }
        $body.capabilities = @($Capabilities | ForEach-Object { $capabilityMap[$_] } | Select-Object -Unique)

        $headers = @{
            'If-Match'        = $requestETag
            'NTNX-Request-Id' = (New-Guid).Guid
        }
        $RequestSplat = @{
            PrismSession = $sessionConfig.Name
            Method       = 'PUT'
            Path         = $path
            Header       = $headers
            Body         = $body
        }
        $response = Invoke-PrismRequest @RequestSplat
        [PrismTask]::new($response.data, $sessionConfig.Name)
    }
}