iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
💭

PowerShell Cmdlet to Reinstall AVD RdAgent and Related Software (April 2024 Edition)

に公開
2024/08/07

TL;DR

  • This is an updated version of a previous article.
  • It has been simplified as Invoke-AzVMRunCommand now supports -InlineScript.
  • There are other minor changes, but the usage remains the same.

Introduction

I previously wrote an article titled PowerShell Cmdlet for re-installing AVD RdAgent, etc., and this is an updated version of it.
Previously, it was necessary to prepare cim.ps1 as a separate script, but since Invoke-AzVMRunCommand now supports -InlineScript, I have changed it to use that.
There are also various other minor changes, but the overall user experience remains unchanged.

Updated PowerShell script

Here it is.

reset-azwvdsessionhostagent.ps1
Function Reset-AzWvdSessionHostAgent() {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)] [string] $ResourceGroupName,
        [Parameter(Mandatory = $true)] [string] $Location,
        [Parameter(Mandatory = $true)] [string] $HostPoolName,
        [Parameter(Mandatory = $true)] [string] $SessionHostVMName,
        [Parameter(Mandatory = $true)] [string] $DomainName
    )

    try {
        $sessionHost = Get-AzWvdSessionHost -HostPoolName $HostPoolName -Name "${SessionHostVMName}.${DomainName}" -ResourceGroupName $ResourceGroupName -ErrorAction SilentlyContinue
    
        if ($sessionHost) {
            Write-Debug "$(Get-Date -Format 'h:mm:ss tt') - Deleting session host '${SessionHostVMName}' from session pool '${HostPoolName}'."
            Remove-AzWvdSessionHost -HostPoolName $HostPoolName -Name "${SessionHostVMName}.${DomainName}" -ResourceGroupName $ResourceGroupName
        } else {
            Write-Debug "$(Get-Date -Format 'h:mm:ss tt') - Session host '${SessionHostVMName}' does not exist in host pool '${HostPoolName}'. Skipping deletion."
        }
    } catch {
        # Log the caught exception, assuming it's an unexpected error.
        Write-Error "An unexpected error occurred: $_"
    }

    Write-Debug "$(Get-Date -Format "h:mm:ss tt") - Deleting DSC extension from session host `"${SessionHostVMName}`"."
    Remove-AzVMExtension -ResourceGroupName $ResourceGroupName -Name Microsoft.PowerShell.DSC -VMName $SessionHostVMName -Force | Out-Null

    Write-Debug "$(Get-Date -Format "h:mm:ss tt") - Deleting RdAgent and AVD-related softwares from session host `"${SessionHostVMName}`"."
    $commandId = "RunPowerShellScript"
    $script = @"
Get-CimInstance -Class Win32_Product -Filter 'Name="Remote Desktop Agent Boot Loader"' | Invoke-CimMethod -MethodName Uninstall
Get-CimInstance -Class Win32_Product -Filter 'Name="Remote Desktop Services Infrastructure Agent"' | Invoke-CimMethod -MethodName Uninstall
Get-CimInstance -Class Win32_Product -Filter 'Name LIKE "Remote Desktop Services Infrastructure Geneva Agent %"' | Invoke-CimMethod -MethodName Uninstall
"@
    Invoke-AzVMRunCommand -ResourceGroupName $ResourceGroupName -VMName $SessionHostVMName -CommandId $commandId -ScriptString $script | Out-Null

    Write-Debug "$(Get-Date -Format 'h:mm:ss tt') - Get AVD registration key for the host pool '${HostPoolName}'."
    $HostpoolToken = (Get-AzWvdRegistrationInfo -ResourceGroupName $ResourceGroupName -HostPoolName $HostPoolName).Token

    if ($null -eq $HostpoolToken) {
        $HostpoolToken = (New-AzWvdRegistrationInfo -ResourceGroupName $ResourceGroupName -HostPoolName $HostPoolName -ExpirationTime $((Get-Date).ToUniversalTime().AddHours(3).ToString('yyyy-MM-ddTHH:mm:ss.fffffffZ'))).Token
    }

    # Convert hostpoolToken to SecureString
    $SecureHostpoolToken = ConvertTo-SecureString $HostpoolToken -AsPlainText -Force

    Write-Debug "$(Get-Date -Format 'h:mm:ss tt') - Re-installing RdAgent to session host '${SessionHostVMName}' for binding to host pool '${HostPoolName}'."
    New-AzResourceGroupDeployment -ResourceGroupName $ResourceGroupName -TemplateFile template.json -vmName $SessionHostVMName -location $Location -hostpoolToken $SecureHostpoolToken -hostpoolName $HostPoolName | Out-Null
}
  • The verb ReInstall- was not recommended in Approved Verbs for PowerShell Commands, so I have changed it to Reset-.
  • Added some error handling around Remove-AzWvdSessionHost in case the session host has already been deleted.
  • Since hostpoolToken used in template.json has changed to a SecureString, I am using ConvertTo-SecureString.
  • Corrected the format string passed to Get-Date -Format... ("h:MM:ss tt" → 'h:mm:ss tt'; MM outputs the numerical month, so it was a pure mistake...)

Also, here is the necessary template.json.

template.json
{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "artifactsLocation": {
            "defaultValue": "https://wvdportalstorageblob.blob.core.windows.net/galleryartifacts/Configuration_1.0.02643.274.zip",
            "type": "String",
            "metadata": {
                "description": "The base URI where artifacts required by this template are located."
            }
        },
        "vmName": {
            "type": "String"
        },
        "location": {
            "defaultValue": "",
            "type": "String",
            "metadata": {
                "description": "Location for all resources to be created in."
            }
        },
        "hostpoolToken": {
            "type": "SecureString",
            "metadata": {
                "description": "The token for adding VMs to the hostpool"
            }
        },
        "hostpoolName": {
            "type": "String",
            "metadata": {
                "description": "The name of the hostpool"
            }
        },
        "aadJoin": {
            "defaultValue": false,
            "type": "Bool",
            "metadata": {
                "description": "IMPORTANT: You can use this parameter for the test purpose only as AAD Join is public preview. True if AAD Join, false if AD join"
            }
        }
    },
    "variables": {},
    "resources": [
        {
            "type": "Microsoft.Compute/virtualMachines/extensions",
            "apiVersion": "2021-07-01",
            "name": "[concat(parameters('vmName'), '/', 'Microsoft.PowerShell.DSC')]",
            "location": "[parameters('location')]",
            "properties": {
                "publisher": "Microsoft.Powershell",
                "type": "DSC",
                "typeHandlerVersion": "2.73",
                "autoUpgradeMinorVersion": true,
                "settings": {
                    "modulesUrl": "[parameters('artifactsLocation')]",
                    "configurationFunction": "Configuration.ps1\\AddSessionHost",
                    "properties": {
                        "hostPoolName": "[parameters('hostpoolName')]",
                        "registrationInfoTokenCredential": {
                            "UserName": "PLACEHOLDER_DO_NOT_USE",
                            "Password": "PrivateSettingsRef:RegistrationInfoToken"
                        },
                        "aadJoin": "[parameters('aadJoin')]",
                        "UseAgentDownloadEndpoint": true
                    }
                },
                "protectedSettings": {
                    "Items": {
                        "RegistrationInfoToken": "[parameters('hostpoolToken')]"
                    }
                }
            }
        }
    ],
    "outputs": {}
}
  • Previously, the hostpoolToken was provided in plain text, but it seems to have become more secure with the unfamiliar protectedSettings syntax and the conversion of hostpoolToken to a SecureString.

Usage

It's straightforward, as shown below.

Reset-AzWvdSessionHostAgent -ResourceGroupName <ResourceGroupName> -Location <Location> -HostPoolName <HostPoolName> -SessionHostVMName <SessionHostVMName> -DomainName <DomainName>

If you wait a little while, RdAgent and other components should be installed.

Summary

I've updated the content regarding the re-installation of the AVD RdAgent since some time has passed.
It has become a bit simpler because Invoke-AzVMRunCommand now supports -InlineScript.

References

  • PowerShell Cmdlet for re-installing AVD RdAgent, etc.

https://zenn.dev/skmkzyk/articles/avd-rdagent-reinstall

  • Resizing the OS disk of an Azure VM

https://zenn.dev/skmkzyk/articles/extend-os-disk-azure-vm

  • Azure Virtual Desktop agent overview

https://learn.microsoft.com/azure/virtual-desktop/agent-overview?wt.mc_id=MVP_391314

  • Approved Verbs for PowerShell Commands

https://learn.microsoft.com/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?wt.mc_id=MVP_391314

  • Desired State Configuration extension with Azure Resource Manager templates - Azure Virtual Machines

https://learn.microsoft.com/azure/virtual-machines/extensions/dsc-template#settings-vs-protectedsettings?wt.mc_id=MVP_391314

Discussion