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)

Note: Right now, the Royal Server commandlets are in beta and the interface of the commandlets might change in the future. But we would be very interested in your thoughts on this way to use Royal Server. Please use our support portal for features suggestions or reporting bugs.

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

2015-03-02 11_29_34-Windows PowerShell

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

2015-03-02 11_30_15-Windows PowerShell

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

2015-03-02 11_30_38-Windows PowerShell

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

2015-03-02 11_31_09-Windows PowerShell

Get-RoyalServerModuleCommand shows the available commands:

Get-RoyalServerModuleCommand -RoyalServerConfig $config -ModuleID EventLog

2015-03-02 11_31_27-Windows PowerShell

Get-RoyalServerModuleCommandParameter shows available parameters:

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

Remark: Note the ” | Format-List” at the end, which produces an output that is better readable 😉

2015-03-02 11_31_50-Windows PowerShell

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)

Note: We do not recommend this for production usage.

PS: It is not required that you have the same color configuration in your PowerShell console as I have 😉

Previous Post Next Post