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)
TL;DR
- This is an updated version of a previous article.
- It has been simplified as
Invoke-AzVMRunCommandnow 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 toReset-. - Added some error handling around
Remove-AzWvdSessionHostin case the session host has already been deleted. - Since
hostpoolTokenused intemplate.jsonhas changed to aSecureString, I am usingConvertTo-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
hostpoolTokenwas provided in plain text, but it seems to have become more secure with the unfamiliarprotectedSettingssyntax and the conversion ofhostpoolTokento aSecureString.
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.
- Resizing the OS disk of an Azure VM
- Azure Virtual Desktop agent overview
- Approved Verbs for PowerShell Commands
- Desired State Configuration extension with Azure Resource Manager templates - Azure Virtual Machines
Discussion