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.
    .PARAMETER ETag
        The current NGT settings ETag. Retrieved automatically when omitted.
    .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,
        [Parameter()][ValidateNotNullOrEmpty()][string]$ETag
    )

    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 = if ($ETag) { $ETag } else { @($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)
    }
}