Some time ago, we released a new PowerShell module together with Royal TS that enables you to manage Royal TS documents via PowerShell (check out the awesome PowerShell Magazine introduction article about this module by Jan Egil Ring). Now we follow up with commandlets to work with Royal Server.

What can I do with Royal Server commandlets?

In general, the Royal Server cmdlets let you work with Royal Server without having Royal TS running. All Management Connections of Royal Server can be used directly,  e.g. you can achieve these scenarios easily in a PowerShell console:

• Reboot your Webserver Farm via Royal Server
• Start the Windows Service “World Wide Web Publishing Service” on all machines from your Webserver Farm where it is currently stopped
• Send a message to running Terminal Sessions
• and many other use cases…

Benefits of using Royal Server with PowerShell

While it’s cool to work with Royal Server from Royal TS in some scenarios (think scripting and automation), you can achieve most of the functionality with built-in PowerShell modules – so why should you go to for the Royal Server PowerShell commandlets?

1. No running Royal TS is needed to talk to Royal Server (Windows Events, Windows Processes, Windows Services, Terminal Services and Hyper-V is currently available)
2. Royal Server adds an additional security layer if Authentication is configured
3. Royal Server adds centralized logging that can not be disabled by the client
4. Royal Server with its current feature set is just the beginning. You can expect more exciting stuff in the future – and some new functionality you will not be able to find in other PowerShell modules
5. TerminalServices can not be managed by PowerShell (unless you deploy and load additional Modules)

First Steps

If you install Royal Server, you will find a RoyalServer.PowerShell.dll in the installation directory. Import this module as you would usually do:

$rsmodule = Join-Path -Path ${env:ProgramFiles(x86)} -ChildPath 'RoyalServer\RoyalServer.PowerShell.dll'
Import-Module $rsmodule

Before we begin, we have to specify the Royal Server to which we want to talk:

$cred = Get-Credential $config = New-RoyalServerConfig -Credential $cred -Host 127.0.0.1 -UseSSL $true -Port 54899

Now we are ready to issue our first command: lets fetch the last 10 EventLog entries:

Invoke-RoyalServerCommand -ModuleID EventLog -Command "GetEntries" -RoyalServerConfig $config -DestinationHost "127.0.0.1" -MaxRecords 10 | Format-Table

Now, we can get a bit more sophisticated with our query. The next examples is using query arguments (and specifies only Log entries from the Application log):

$p =  @{"WQLWhereClause" = "LogFile='Application'"}

Invoke-RoyalServerCommand -ModuleID EventLog -Command "GetEntries" -Arguments $p -RoyalServerConfig $config -DestinationHost "127.0.0.1" -MaxRecords 10 | Format-Table

Querying Metadata about Module Commands and Parameters

The Module-Parameter is using the Enum “ModuleNames” which can be specified like this:

$module = [RoyalServer.PowerShell.ModuleNames]::TerminalServices

This enables the PowerShell console to offer tab-completion in your console. But how can we find out which values are allowed for the parameters -Command and even -Arguments?

Get-RoyalServerModule shows available modules:

Get-RoyalServerModule -RoyalServerConfig $config

Get-RoyalServerModuleCommand shows the available commands:

Get-RoyalServerModuleCommand -RoyalServerConfig $config -ModuleID EventLog

Get-RoyalServerModuleCommandParameter shows available parameters:

Get-RoyalServerModuleCommandParameter -RoyalServerConfig $config -ModuleID EventLog -Command "GetEntries" | Format-List

Working with Credentials

The commandlets New-RoyalServerConfig and Invoke-RoyalServerCommand need (if Royal Server is properly configured) some credentials to work. There are two ways to provide this information:

1. The -Credential parameter and Get-Credential This is the standard way to work with credentials in PowerShell – though its limited to be provided at runtime form a human.
2. The -Credential parameter hardcoded in the PowerShell script This approach can be used for automated scripts:

   $secpasswd = ConvertTo-SecureString "<your-secure-password>" -AsPlainText -Force
   $cred = New-Object System.Management.Automation.PSCredential ("<username", $secpasswd)