Introducing the Royal TS PowerShell module

Royal TS is one of many applications on the market for managing Remote Desktop connections. There are also many other features in Royal TS and you can read more about them on their website.

In this article, we are going to focus on the new PowerShell module for managing Royal TS Documents.

The PowerShell module, introduced in the beta version of Royal TS 3.0, is available here.

Getting started

If you install the MSI file available on the website for the beta version, you can import the module as follows:

If you download the ZIP file, you will need to specify the path to the location where the extracted RoyalDocument.PowerShell.dll resides. In the final version of Royal TS 3.0, the module will hopefully be installed to a proper path specified in $env:PSModulePath variable, so that we don’t need to specify the path manually.

After the module is successfully imported, we can explore the available cmdlets:

There are 17 cmdlets in the initial version of this module.

There aren’t any help available yet, so we can’t use Get-Help to get more information about the cmdlets. However, there are some information in the RoyalTS3.chm file in the Royal TS program folder to help us getting started:

Next step is to create a Royal Document where we can store connections. As described in the Getting Started section of the help file, we first need to create a new RoyalStore in memory before we can use New-RoyalDocument.

In order to store the in-memory document to disk we need to use the Out-RoyalDocument cmdlet:

Creating Remote Desktop connections

Before we go further, you might want to see how the UI looks like. Here is a screenshot of Royal TS 3.0 beta connected to a Server Core instance using Remote Desktop:

What we are going to create next is the Servers folder and Remote Desktop connections on the left side.

The inline comments should describe what is happening. When the code is executed, Royal TS opens up, and we can see the new folder and Remote Desktop connection is present:

If we right click the Remote Desktop connection we created and go into Properties, we can also see that the Computer Name is configured with the value we supplied as the URI:

In the Properties dialog, we can see that there are many options available to configure, such as Remote Desktop Gateway, Window Mode and so on. All of these properties are available on the object we created; a subset of them is visible in the screenshot below:

An object of the type RoyalRDSConnection is returned when we call the New-RoyalObject and the Set-RoyalObjectValue cmdlets.

Next, let’s see how we can configure a couple of these properties as an example:

We’ll configure the Credential Configuration to “Use credentials from the parent folder” and the Resize mode to “Smart Sizing”:

When the code has been executed, the changes should be reflected in the UI:

The code shown in the examples in this article is available in this Gist.

Practical example

The ability to automate Royal TS documents using PowerShell opens up many interesting scenarios.

I have created a script which demonstrates a practical example. The following is copied from the script’s comment-based help:

Syntax

1

.\Update-RoyalFolder.ps1 [-RootOUPath] <String> [[-RoyalDocumentPath] <String>] [-RemoveInactiveComputerObjects ] [[-InactiveComputerObjectThresholdInDays] <String>] [-UpdateRoyalComputerProperties ] [-UpdateRoyalFolderProperties ]  [[-RTSPSModulePath] <String>] [<CommonParameters>]

Description

_    This script will mirror the OU structure from the specified root OU to a top level folder in the specified Royal TS document and create Remote Desktop Connection objects for all AD computer accounts meeting specific criteria._

_       The criteria are the following:_

_       -The computer object is registered with a Server operating system (the object’s “Operatingsystem” LDAP property meets the filter “Windows Server*”)_

_       -The computer object is not a Cluster Name Object (the object’s “ServicePrincipalName” LDAP property does not contain the word MSClusterVirtualServer)_

_       -The computer account has logged on to the domain in the past X number of days (X is 60 days if the parameter InactiveComputerObjectThresholdInDays is not specified)_

_       The purpose of this script is to show how the Royal TS PowerShell module available in Royal TS 3.0 beta can be used to manage a Royal TS document. Thus it must be customized to meet specific needs, the script shows how to configure a couple of Remote Desktop connection properties as an example._

_       The script is meant to be scheduled, for example by using PowerShell jobs or scheduled tasks, in order to have an updated Royal TS document based on active computer accounts in one or more specified Active Directory OU(s)._

_       For smaller environments, it may be appropriate to specify the domain DN as the root OU, but this is not recommended for larger environments. Instead the script may be run multiple times with different OUs specified as the root OU._

Examples

_    ————————– EXAMPLE 1 ————————–_

_    C:\PS>& C:\MyScripts\Update-RoyalFolder.ps1 -RootOUPath ‘OU=Servers,DC=lab,DC=local’ -RoyalDocumentPath C:\temp\Servers.rtsz_

_    Mirrors the OU structure in the C:\temp\Servers.rtsz Royal TS document based on computer accounts from the root OU OU=Servers,DC=lab,DC=local_

_    ————————– EXAMPLE 2 ————————–_

_    C:\PS>& C:\MyScripts\Update-RoyalFolder.ps1 -RootOUPath ‘OU=Servers,DC=lab,DC=local’ -RoyalDocumentPath C:\temp\Servers.rtsz -RemoveInactiveComputerObjects –UpdateRoyalComputerProperties -UpdateRoyalFolderProperties -InactiveComputerObjectThresholdInDays 30_

_    Mirrors the OU structure in the C:\temp\Servers.rtsz Royal TS document based on computer accounts from the root OU OU=Servers,DC=lab,DC=local_

_   Removes computer accounts already present in the Royal TS document folder, which have not logged on to the domain for the last 10 days._

_   Enables Smart sizing and inheritance of credentials from the parent folder for existing objects if not already enabled._

This is a screenshot of an OU structure from a test environment where I ran the demo script:

Here is the same OU structure mirrored in Royal TS, created using script:

The PowerShell script is available on GitHub.

Suggestions for improvements

If you have suggestions for improvements to the Royal TS PowerShell module, feel free to submit them in the comments section. I’ve already sent the following suggestions to the authors:

  • Make it easier to import the module, for example, by adding the path to $env:PSModulePath.
  • Add IntelliSense for parameters with predefined values, for example, for New-RoyalObject’s Type parameter.
  • Add updatable help for the Royal TS PowerShell module.
  • Add the Royal TS installation package to OneGet/Chocolatey
  • Add the Royal TS PowerShell Module to the PowerShell Gallery.

Usage scenarios

There are many possible ways to leverage the PowerShell module in order to automate the configuration of Royal TS documents, for example:

  • Create a DSC Resource for managing the configuration document, and apply a DSC configuration to an IT Pro’s desktop computer
  • Create an SMA runbook to create a central Royal TS document
  • Create a regular PowerShell script and run it on a regular basis using a PowerShell scheduled job or a scheduled task to create a central Royal TS document

Feel free to share your views on how to leverage the module in a real world scenario.

Share on: