Important: Starting with Royal TS 5.00.61707.0 we outsourced the PowerShell module to the PowerShellGallery over at https://www.powershellgallery.com/packages/RoyalDocument.PowerShell. This allows us independently updating the PowerShell module much easier and quickier. Furthermore the PowerShell module does now also work with PowerShell core, being able to run it under supported Linux and macOS platforms as well.

Royal TS V4 (for Windows) includes a PowerShell module that can be used to create and edit Royal TS files (.rtsx and .rtsz files). This enables quite flexible scenarios like

  • create Remote Desktop Connections for all AD computer accounts in a specific OU
  • create Remote Desktop Connections for your VMs in the Amazon EC2 cloud
  • create connections based on information from a Configuration DB or a CSV file
  • and many more...

Getting started

The PowerShell module is located in the same directory as the Royal TS binary (RoyalTS.exe) and named RoyalDocument.Powershell.dll. Import this DLL as usually by using the Import-Module commandlet. 

Import-Module "${env:ProgramFiles(x86)}\code4ward.net\Royal TS V4\RoyalDocument.PowerShell.dll" 

 If you want to work on a frequent basis with this module, you might consider copying the dll to the users PSModulePath for PowerShell: 

Copy-Item "${env:ProgramFiles(x86)}\code4ward.net\Royal TS V4\RoyalDocument.PowerShell.dll" $env:PSModulePath.split(";")[0]  

 Note: This copies the RoyalDocument.Powershell.dll to the first path that is specified in the $env:PSModulePath variable.

Let's have a look on the exported commands:

All commandlets are deployed with integrated help - so you can display additional help by using the Get-Help commandlet:

Additionally extended help is also provided in the Royal TS Help file named RoyalTS4.chm that is located in the installation directory of Royal TS.

Creating a Document

Before you can work with documents, you need to create a RoyalStore. This holds references to 1 or more RoyalDocuments. After creating a new RoyalDocument by using the New-RoyalDocument you can use the Out-RoyalDocument to actually save it disc. 

#create a RoyalStore in memory
$royalStore = New-RoyalStore -UserName ($env:USERDOMAIN + '\' + $env:USERNAME)

#create a RoyalDocument in memory
$documentName = "testdocument"
$documentPath = Join-Path -Path $env:USERPROFILE -ChildPath ('Documents' + '\' + $documentName + '.rtsz')
$royalDocument = New-RoyalDocument -Store $royalStore -Name $documentName -FileName $documentPath

#so far, this document exists only in memory
#you need to save it to disc if you want to use it later
Out-RoyalDocument -Document $royalDocument
Close-RoyalDocument -Document $royalDocument

 Creating Remote Desktop Connections

After you have created a RoyalDocument, its easy to add objects to it using the New-RoyalObject commandlet: 

#create a RoyalStore in memory
$royalStore = New-RoyalStore -UserName ($env:USERDOMAIN + '\' + $env:USERNAME)

#create a RoyalDocument in memory
$documentName = "testdocument"
$documentPath = Join-Path -Path $env:USERPROFILE -ChildPath ('Documents' + '\' + $documentName + '.rtsz')
$royalDocument = New-RoyalDocument -Store $royalStore -Name $documentName -FileName $documentPath

#create folders and remote desktop connections
$folder = New-RoyalObject -Type RoyalFolder -Folder $royalDocument -Name "DMZ" -Description "dmz zone"
$rds = New-RoyalObject -Type RoyalRDSConnection -Folder $folder -Name Demo-Server1 -Description "used for demos"

Out-RoyalDocument -Document $royalDocument
Close-RoyalDocument -Document $royalDocument$royalTSApp = Join-Path ${env:ProgramFiles(x86)} -ChildPath "code4ward.net\Royal TS V3\rts3app.exe"Start-Process -FilePath $royalTSApp

 Now you can see in the opened document that we have indeed created a new RoyalDocument with one Folder and one Remote Desktop Connection inside.

the New-RoyalObject command only provides a very basic set of properties to specify. For anything more specific, you can directly set the property or use the Set-RoyalObjectValue commandlet: 

$rds.CustomField1 = "http://192.168.1.105/login.htm"
Set-RoyalObjectValue -Object $rds -Property "CustomField1" -Value "http://192.168.1.105/login.htm" 

 Extended Help

The Royal TS object model is providing a rich set of objects and properties. We have included an additional commandlet for showing more detailed help about properties: Get-RoyalPropertyHelp:

Real world use case

A more detailed example shows how you can create a Royal TS document based on a CSV file. This example can be found here: https://support.royalapplications.com/support/solutions/articles/17000027866