Remote Desktop Services Provider for Windows PowerShell
Updated: February 18, 2010
Applies To: Windows Server 2008 R2
PROVIDER NAME
Remote Desktop Services
DRIVES
RDS:
SHORT DESCRIPTION
Provides access to Remote Desktop Services settings from within Windows PowerShell.
DETAILED DESCRIPTION
The Remote Desktop Services module for Windows PowerShell contains the RDS provider, which lets you manage Remote Desktop Services (RDS) settings through Windows PowerShell. For example, you can use the RDS provider to view and change settings for a Remote Desktop Session Host (RD Session Host) server, configure Remote Desktop Gateway (RD Gateway) servers, configure Remote Desktop Licensing (RD Licensing) servers, publish RemoteApp programs, and create and configure RD Session Host server farms.
You can use Windows PowerShell to script complex and recurring administrative tasks on RD Session Host servers. Also, you can work with Remote Desktop Services settings and perform complex tasks directly from the Windows PowerShell command line, without having to write, save, and run scripts.
The RDS provider for Windows PowerShell presents a hierarchical view of the configuration settings for an RD Session Host server. These settings are exposed in the Windows PowerShell RDS: drive. To work with the RDS provider, change your location to the RDS: drive by using the set-location rds: or cd rds: command. You can use standard Windows PowerShell cmdlets, such as Get-Item, Set-Item, and Get-ChildItem, to navigate the provider and work with configuration settings.
Settings in the RDS provider are organized into six directories:
The RDSConfiguration directory contains settings that apply to the Remote Desktop Session Host (RD Session Host) role service.
The Gateway directory contains settings that apply to the Remote Desktop Gateway (RD Gateway) role service.
The LicenseServer directory contains settings that apply to the Remote Desktop Licensing (RD Licensing) role service.
The ConnectionBroker directory contains settings that apply to the Remote Desktop Connection Broker (RD Connection Broker) role service.
The RemoteApps directory contains the list of published applications and the settings that apply to them.
The RDSFarms directory contains settings that apply to RD Session Host server farms.
To get a list that presents a current value, permissible values, and permissible operations for each item, type Get-ChildItem (or its alias, dir) in the RDS provider. Each item in the list has an associated description. The description is not visible in the default directory listing. To display the descriptions for items in a directory, type Get-ChildItem | Format-list. The description briefly describes the purpose of the item and the possible values for it.
In some locations in the RDS provider, the behavior of the standard cmdlets has been changed so that they perform actions specific to the RDS provider. We call these cmdlets custom cmdlets. For example, when you call the New-Item cmdlet from the location RDS:\LicenseServer\LicenseKeyPacks, the provider creates a new license key pack. When you call the New-Item cmdlet from the location RDS:\RDSConfiguration\Connections, the provider creates a new connection.
Some custom cmdlets work with items that you cannot navigate to in the provider. To use these custom cmdlets, you must provide a path to the item you want to work with. For example, to set the TimeZoneRedirection item, you must call the Set-Item cmdlet with the path parameter set to RDS:\RDSConfiguration\TimeZoneRedirection.
Some custom cmdlets have required parameters that are different from those required by the standard cmdlets. If you call a custom cmdlet and do not provide values for these parameters, you will be prompted for them.
To get help for a custom cmdlet, type Get-Help CmdletName, and specify the path by using the path parameter. If you do not specify the path when calling Get-Help, the path defaults to the current location, and the appropriate help topic for that location is displayed.
EXAMPLES
Navigating to the RDS: Drive
-------------------------- EXAMPLE 1 --------------------------
Changes the current location to the RDS: drive.
set-location rds:
-------------------------- EXAMPLE 2 --------------------------
Changes the current location to the RemoteApps directory.
set-location -path rds:\remoteapp
Setting the Encryption Level
-------------------------- EXAMPLE 1 --------------------------
Displays the current encryption level.
get-childitem -path RDS:\RDSConfiguration\Connections\RDP-Tcp\SecuritySettings\EncryptionLevel | format-list
-------------------------- EXAMPLE 2 --------------------------
Sets the encryption level to low.
Set-Item -path RDS:\RDSConfiguration\Connections\RDP-Tcp\SecuritySettings\EncryptionLevel 1
Working with License Servers
-------------------------- EXAMPLE 1 --------------------------
Displays the list of license servers that are in use.
dir -path RDS:\RDSConfiguration\LicensingSettings\SpecifiedLicenseServers
-------------------------- EXAMPLE 2 --------------------------
Displays the list of license servers that are registered with the domain controller.
dir -path RDS:\RDSConfiguration\LicensingSettings\RegisteredLicenseServers
-------------------------- EXAMPLE 3 --------------------------
Adds all license servers in the registered license server list to the specified license server list. The RD Session Host server uses the license servers in the SpecifiedLicenseServer item to request licenses.
dir -path RDS:\RDSConfiguration\LicensingSettings\SpecifiedLicenseServers\RegisteredLicenseServers | new-item -force
-------------------------- EXAMPLE 4 --------------------------
Adds one license server to the list of specified license servers.
new-item -path RDS:\RDSConfiguration\LicensingSettings\SpecifiedLicenseServers –name Contoso-Ls
Working with Remote Desktop Session Host Server Farms
-------------------------- EXAMPLE 1 --------------------------
Joins an RD Session Host server to an RD Session Host server farm.
Set-Item -path RDS:\RDSConfiguration\ConnectionBrokerSettings\ServerPurpose -value 3 -ConnectionBroker sb-test -FarmName FARM_2 -CurrentRedirectableAddresses 192.168.255.255
-------------------------- EXAMPLE 2 --------------------------
Removes an RD Session Host server from an RD Session Host server farm.
Set-Item -path RDS:\RDSConfiguration\ConnectionBrokerSettings\ServerPurpose -value 0
Working with RemoteApps
-------------------------- EXAMPLE 1 --------------------------
Publishes a RemoteApp program named calc.
New-Item -path RDS:\RemoteApp\RemoteAppPrograms -Name 'Calc'
When you run this cmdlet, Windows PowerShell queries you for the missing parameters and adds the program to the list of published programs.
Getting Help for a Provider Cmdlet
-------------------------- EXAMPLE 1 --------------------------
Displays help for the New-Item cmdlet that applies to the RDS:\RDSConfiguration\Connections location.
Get-help new-item -path RDS:\RDSConfiguration\Connections