Enable Remote Desktop Connection for a Role in Azure Cloud Services (classic) using PowerShell

Remote Desktop enables you to access the desktop of a role running in Azure. You can use a Remote Desktop connection to troubleshoot and diagnose problems with your application while it is running.

This article describes how to enable remote desktop on your Cloud Service Roles using PowerShell. See How to install and configure Azure PowerShell for the prerequisites needed for this article. PowerShell utilizes the Remote Desktop Extension so you can enable Remote Desktop after the application is deployed.

Configure Remote Desktop from PowerShell

The Set-AzureServiceRemoteDesktopExtension cmdlet allows you to enable Remote Desktop on specified roles or all roles of your cloud service deployment. The cmdlet lets you specify the Username and Password for the remote desktop user through the Credential parameter that accepts a PSCredential object.

If you are using PowerShell interactively, you can easily set the PSCredential object by calling the Get-Credentials cmdlet.

$remoteusercredentials = Get-Credential

This command displays a dialog box allowing you to enter the username and password for the remote user in a secure manner.

Since PowerShell helps in automation scenarios, you can also set up the PSCredential object in a way that doesn't require user interaction. First, you need to set up a secure password. You begin with specifying a plain text password convert it to a secure string using ConvertTo-SecureString. Next you need to convert this secure string into an encrypted standard string using ConvertFrom-SecureString. Now you can save this encrypted standard string to a file using Set-Content.

You can also create a secure password file so that you don't have to type in the password every time. Also, a secure password file is better than a plain text file. Use the following PowerShell to create a secure password file:

ConvertTo-SecureString -String "Password123" -AsPlainText -Force | ConvertFrom-SecureString | Set-Content "password.txt"

To create the credential object from the secure password file, you must read the file contents and convert them back to a secure string using ConvertTo-SecureString.

The Set-AzureServiceRemoteDesktopExtension cmdlet also accepts an Expiration parameter, which specifies a DateTime at which the user account expires. For example, you could set the account to expire a few days from the current date and time.

This PowerShell example shows you how to set the Remote Desktop Extension on a cloud service:

$servicename = "cloudservice"
$username = "RemoteDesktopUser"
$securepassword = Get-Content -Path "password.txt" | ConvertTo-SecureString
$expiry = $(Get-Date).AddDays(1)
$credential = New-Object System.Management.Automation.PSCredential $username,$securepassword
Set-AzureServiceRemoteDesktopExtension -ServiceName $servicename -Credential $credential -Expiration $expiry

You can also optionally specify the deployment slot and roles that you want to enable remote desktop on. If these parameters are not specified, the cmdlet enables remote desktop on all roles in the Production deployment slot.

The Remote Desktop extension is associated with a deployment. If you create a new deployment for the service, you have to enable remote desktop on that deployment. If you always want to have remote desktop enabled, then you should consider integrating the PowerShell scripts into your deployment workflow.

Remote Desktop into a role instance

The Get-AzureRemoteDesktopFile cmdlet is used to remote desktop into a specific role instance of your cloud service. You can use the LocalPath parameter to download the RDP file locally. Or you can use the Launch parameter to directly launch the Remote Desktop Connection dialog to access the cloud service role instance.

Get-AzureRemoteDesktopFile -ServiceName $servicename -Name "WorkerRole1_IN_0" -Launch

Check if Remote Desktop extension is enabled on a service

The Get-AzureServiceRemoteDesktopExtension cmdlet displays that remote desktop is enabled or disabled on a service deployment. The cmdlet returns the username for the remote desktop user and the roles that the remote desktop extension is enabled for. By default, this happens on the deployment slot and you can choose to use the staging slot instead.

Get-AzureServiceRemoteDesktopExtension -ServiceName $servicename

Remove Remote Desktop extension from a service

If you have already enabled the remote desktop extension on a deployment, and need to update the remote desktop settings, first remove the extension. And enable it again with the new settings. For example, if you want to set a new password for the remote user account, or the account expired. Doing this is required on existing deployments that have the remote desktop extension enabled. For new deployments, you can simply apply the extension directly.

To remove the remote desktop extension from the deployment, you can use the Remove-AzureServiceRemoteDesktopExtension cmdlet. You can also optionally specify the deployment slot and role from which you want to remove the remote desktop extension.

Remove-AzureServiceRemoteDesktopExtension -ServiceName $servicename -UninstallConfiguration

Additional resources

How to Configure Cloud Services