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

Important

Cloud Services (classic) is now deprecated for all customers as of September 1st, 2024. Any existing running deployments will be stopped and shut down by Microsoft and the data will be permanantly lost starting October 2024. New deployments should use the new Azure Resource Manager based deployment model Azure Cloud Services (extended support).

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 runs.

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 use 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"

Important

When setting the password, make sure that you meet the complexity requirements.

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 aren't 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 Remote Desktop Protocol (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, the deployment slot is used, but you can choose to use the staging slot instead.

Get-AzureServiceRemoteDesktopExtension -ServiceName $servicename

Remove Remote Desktop extension from a service

If you already enabled the remote desktop extension on a deployment and need to update the remote desktop settings, first remove the extension. Then, 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 step is required on existing deployments that have the remote desktop extension enabled. For new deployments, you can 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

Note

To completely remove the extension configuration, you should call the remove cmdlet with the UninstallConfiguration parameter.

The UninstallConfiguration parameter uninstalls any extension configuration that is applied to the service. Every extension configuration is associated with the service configuration. Calling the remove cmdlet without UninstallConfiguration disassociates the deployment from the extension configuration, thus effectively removing the extension. However, the extension configuration remains associated with the service.

Next steps