PowerShell client module

The Orleans PowerShell client module is a set of PowerShell Cmdlets that wraps the GrainClient. It provides a set of convenient commands, that make it possible to interact with not just the ManagementGrain but any IGrain just as a regular Orleans application can by using PowerShell scripts.

These cmdlets enable a series of scenarios from start maintenance tasks, tests, monitoring, or any other kind of automation by leveraging PowerShell scripts.

Install the module

To install this module from the source, you can build using the OrleansPSUtils project and just import it with:

PowerShell

Import-Module .\projectOutputDir\Orleans.psd1

Although you can do that, there is a much easier and more interesting way by installing it from PowerShell Gallery. PowerShell modules are easily shared, much like Nuget packages, but instead of nuget.org, they are hosted on the PowerShell Gallery.

To install this module from the PowerShell gallery, run the following command in the desired folder:

PowerShell

Save-Module -Name OrleansPSUtils -Path <path>

To install it on your PowerShell modules path (the recommended way), run:

PowerShell

Install-Module -Name OrleansPSUtils

If you plan to use this module on an Azure Automation, use this link.

Use the module

Regardless of the way you decide to install it, you need to import the module on the current PowerShell session so the cmdlets get available by running this:

PowerShell

Import-Module OrleansPSUtils

Important

In case of building from source, you must import it as suggested on the Install the module section by using the path to the .psd1 instead of using the module name since it will not be on the $env:PSModulePath PowerShell runtime variable. It is highly recommended that you install from PowerShell Gallery instead.

After the module is imported (which means it is loaded on PowerShell session), you will have the following cmdlets available:

• Start-GrainClient
• Stop-GrainClient
• Get-Grain

Start the GrainClient

This module is a wrapper around GrainClient.Initialize() and its overloads.

Start-GrainClient

The same as a call to GrainClient.Initialize(), which will look for the known Orleans client configuration file names:

PowerShell

Start-GrainClient [-ConfigFilePath] <string> [[-Timeout] <timespan>]

The preceding command will use the provided file path as in GrainClient.Initialize(filePath).

PowerShell

Start-GrainClient [-ConfigFile] <FileInfo> [[-Timeout] <timespan>]

The preceding command will use an instance of the FileInfo class representing the config file just as GrainClient.Initialize(fileInfo).

PowerShell

Start-GrainClient [-Config] <ClientConfiguration> [[-Timeout] <timespan>]

The preceding command will use an instance of a ClientConfiguration like in GrainClient.Initialize(config).

PowerShell

Start-GrainClient [-GatewayAddress] <IPEndPoint> [[-OverrideConfig] <bool>] [[-Timeout] <timespan>]

The preceding command takes an Orleans cluster gateway address endpoint.

Tip

The Timeout parameter is optional and if it is informed and greater than TimeSpan.Zero, it will call GrainClient.SetResponseTimeout(TimeSpan) internally.

Stop the GrainClient

To stop the GrainClient, call the following command:

PowerShell

Stop-GrainClient

The preceding command takes no parameters and when called, if the GrainClient is initialized will be gracefully uninitialized.

Get a Grain

To get a Grain, this cmdlet is a wrapper around GrainClient.GrainFactory.GetGrain<T>() and its overloads. The mandatory parameter is -GrainType and the -XXXKey for the current Grain key types supported by Orleans (string, Guid, long) and also the -KeyExtension that can be used on Grains with compound keys.

This cmdlet returns a grain reference of the type passed by as a parameter on -GrainType. As an example on calling MyInterfacesNamespace.IMyGrain.SayHelloTo grain method:

PowerShell

Import-Module OrleansPSUtils
$configFilePath = Resolve-Path(".\ClientConfig.xml").Path
Start-GrainClient -ConfigFilePath $configFilePath
Add-Type -Path .\MyGrainInterfaceAssembly.dll
$grainInterfaceType = [MyInterfacesNamespace.IMyGrain]
$grainId = [System.Guid]::Parse("A4CF7B5D-9606-446D-ACE9-C900AC6BA3AD")
$grain = Get-Grain -GrainType $grainInterfaceType -GuidKey $grainId
$message = $grain.SayHelloTo("Gutemberg").Result
Write-Output $message
Hello Gutemberg!
Stop-GrainClient

There are additional cmdlets not discussed, but there is support for Observers, Streams and other Orleans core features more natively on PowerShell.

Note

The intent is not to reimplement the whole client on PowerShell but instead, give IT and DevOps teams a way to interact with the grains without needing to implement a .NET application.