PowerShell client module

The Orleans PowerShell client module is a set of PowerShell Cmdlets wrapping the GrainClient. It provides convenient commands allowing interaction not just with the ManagementGrain but with any IGrain, just as a regular Orleans application can, by using PowerShell scripts.

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

Install the module

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

Import-Module .\projectOutputDir\Orleans.psd1

Although you can do that, a much easier and more interesting way is to install it from the 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:

Save-Module -Name OrleansPSUtils -Path <path>

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

Install-Module -Name OrleansPSUtils

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

Use the module

Regardless of how you install it, you need to import the module into the current PowerShell session to make the cmdlets available. Run this command:

Import-Module OrleansPSUtils

After importing the module (loading it into the PowerShell session), the following cmdlets become available:

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

Start the GrainClient

This module wraps GrainClient.Initialize() and its overloads.

Start-GrainClient

This is the same as calling GrainClient.Initialize(), which looks for known Orleans client configuration file names:

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

The preceding command uses the provided file path, similar to GrainClient.Initialize(filePath).

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

The preceding command uses an instance of the FileInfo class representing the config file, just like GrainClient.Initialize(fileInfo).

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

The preceding command uses an instance of ClientConfiguration, similar to GrainClient.Initialize(config).

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

The preceding command takes an Orleans cluster gateway address endpoint.

Stop the GrainClient

To stop the GrainClient, call the following command:

Stop-GrainClient

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

Get a Grain

To get a Grain, this cmdlet wraps GrainClient.GrainFactory.GetGrain<T>() and its overloads. The mandatory parameter is -GrainType. You also need the -XXXKey parameter corresponding to the grain key type supported by Orleans (string, Guid, long), and optionally the -KeyExtension parameter for grains with compound keys.

This cmdlet returns a grain reference of the type passed via the -GrainType parameter. Here's an example of calling the MyInterfacesNamespace.IMyGrain.SayHelloTo grain method:

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 here, but support exists for Observers, Streams, and other Orleans core features more natively in PowerShell.