TestCluster Methods

A host class for local testing with Orleans using in-process silos. Runs a Primary and optionally secondary silos in separate app domains, and client in the main app domain. Additional silos can also be started in-process on demand if required for particular test cases.

ContainsSilo(SiloAddress)

public bool ContainsSilo(SiloAddress siloAddress)

Returns whether the address belongs to this cluster.

Parameters

siloAddressSiloAddress: The silo address.

Returns

true when the address belongs to this cluster.

DeactivateAsync(GrainId)

public Task DeactivateAsync(GrainId grainId)

Deactivates the current activation of the specified grain and waits for deactivation to complete.

Parameters

grainIdGrainId: The ID of the grain to deactivate.

Returns

A task that completes when the grain has been deactivated.

Examples

            await cluster.DeactivateAsync(grain.GetGrainId());

DeactivateAsync(IAddressable)

public Task DeactivateAsync(IAddressable grain)

Deactivates the current activation of the specified grain and waits for deactivation to complete.

Parameters

grainIAddressable: The grain to deactivate.

Returns

A task that completes when the grain has been deactivated.

Examples

            await cluster.DeactivateAsync(grain.GetGrainId());

DefaultCreateSiloAsync(string, IConfiguration)

public Task<SiloHandle> DefaultCreateSiloAsync(string siloName, IConfiguration configuration)

Default value for TestCluster, which creates a new silo handle.

Parameters

siloNamestring: Name of the silo.
configurationIConfiguration: The configuration.

Returns

The silo handle.

DefaultCreateSiloAsync(string, IConfiguration, CancellationToken)

public Task<SiloHandle> DefaultCreateSiloAsync(string siloName, IConfiguration configuration, CancellationToken cancellationToken)

Creates a new silo handle.

Parameters

siloNamestring: Name of the silo.
configurationIConfiguration: The configuration.
cancellationTokenCancellationToken: The token used to cancel silo startup.

Returns

The silo handle.

Deploy

public void Deploy()

Deploys the cluster using the specified configuration and starts the client in-process. It will start the number of silos defined in TestClusterOptions.

DeployAsync

public Task DeployAsync()

Deploys the cluster using the specified configuration and starts the client in-process.

DeployAsync(CancellationToken)

public Task DeployAsync(CancellationToken cancellationToken)

Deploys the cluster using the specified configuration and starts the client in-process.

Parameters

cancellationTokenCancellationToken: The token used to cancel deployment.

Dispose

public void Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

DisposeAsync

public ValueTask DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Returns

A task that represents the asynchronous dispose operation.

GetActiveSilos

public IEnumerable<SiloHandle> GetActiveSilos()

Get the list of current active silos.

Returns

List of current silos.

GetLivenessStabilizationTime(ClusterMembershipOptions, bool)

static

public static TimeSpan GetLivenessStabilizationTime(ClusterMembershipOptions clusterMembershipOptions, bool didKill = false)

Get the timeout value to use to wait for the silo liveness sub-system to detect and act on any recent cluster membership changes.

Parameters

clusterMembershipOptionsClusterMembershipOptions
didKillbool

GetLog

public string GetLog()

Gets the log.

Returns

The log contents.

GetSiloForAddress(SiloAddress)

public SiloHandle? GetSiloForAddress(SiloAddress siloAddress)

Find the silo handle for the specified silo address.

Parameters

siloAddressSiloAddress: Silo address to be found.

Returns

SiloHandle of the appropriate silo, or null if not found.

GetSiloServiceProvider(SiloAddress?)

public IServiceProvider GetSiloServiceProvider(SiloAddress? silo = null)

Returns the System.IServiceProvider associated with the given silo.

Parameters

siloSiloAddress?: The silo process to the the service provider for.

InitializeClientAsync

public Task InitializeClientAsync()

Initialize the grain client. This should be already done by TestCluster or TestCluster

InitializeClientAsync(CancellationToken)

public Task InitializeClientAsync(CancellationToken cancellationToken)

Initialize the grain client.

Parameters

cancellationTokenCancellationToken: The token used to cancel initialization.

KillClientAsync

public Task KillClientAsync()

Performs a hard kill on client. Client will not cleanup resources.

KillSiloAsync(SiloHandle)

public Task KillSiloAsync(SiloHandle instance)

Do an immediate Kill of the specified silo.

Parameters

instanceSiloHandle: Silo to be killed.

KillSiloAsync(SiloHandle, CancellationToken)

public Task KillSiloAsync(SiloHandle instance, CancellationToken cancellationToken)

Do an immediate Kill of the specified silo.

Parameters

instanceSiloHandle: Silo to be killed.
cancellationTokenCancellationToken: The token used to cancel the operation.

MigrateAsync(GrainId, SiloAddress?)

public Task MigrateAsync(GrainId grainId, SiloAddress? targetSilo = null)

Migrates the current activation of the specified grain to a different silo and waits for migration to complete. If targetSilo is specified, a placement hint is set to guide migration to that silo.

Parameters

grainIdGrainId: The ID of the grain to migrate.
targetSiloSiloAddress?: The target silo address, or null to let the placement director choose.

Returns

A task that completes when the grain has been migrated (deactivated on the source silo).

Examples

            var targetSilo = cluster.GetActiveSilos().First(s => s.SiloAddress != originalHost).SiloAddress;
            await cluster.MigrateAsync(grain.GetGrainId(), targetSilo);

MigrateAsync(IAddressable, SiloAddress?)

public Task MigrateAsync(IAddressable grain, SiloAddress? targetSilo = null)

Migrates the current activation of the specified grain to a different silo and waits for migration to complete. If targetSilo is specified, a placement hint is set to guide migration to that silo.

Parameters

grainIAddressable: The grain to migrate.
targetSiloSiloAddress?: The target silo address, or null to let the placement director choose.

Returns

A task that completes when the grain has been migrated (deactivated on the source silo).

Examples

            var targetSilo = cluster.GetActiveSilos().First(s => s.SiloAddress != originalHost).SiloAddress;
            await cluster.MigrateAsync(grain.GetGrainId(), targetSilo);

RestartSiloAsync(SiloHandle)

public Task<SiloHandle?> RestartSiloAsync(SiloHandle instance)

Do a Stop or Kill of the specified silo, followed by a restart.

Parameters

instanceSiloHandle: Silo to be restarted.

RestartStoppedSecondarySiloAsync(string)

public Task<SiloHandle> RestartStoppedSecondarySiloAsync(string siloName)

Restart a previously stopped.

Parameters

siloNamestring: Silo to be restarted.

StartAdditionalSilo(bool)

public SiloHandle StartAdditionalSilo(bool startAdditionalSiloOnNewPort = false)

Start an additional silo, so that it joins the existing cluster.

Parameters

startAdditionalSiloOnNewPortbool

Returns

SiloHandle for the newly started silo.

StartAdditionalSiloAsync(bool)

public Task<SiloHandle> StartAdditionalSiloAsync(bool startAdditionalSiloOnNewPort = false)

Start an additional silo, so that it joins the existing cluster.

Parameters

startAdditionalSiloOnNewPortbool

Returns

SiloHandle for the newly started silo.

StartAdditionalSilosAsync(int, bool)

public Task<List<SiloHandle>> StartAdditionalSilosAsync(int silosToStart, bool startAdditionalSiloOnNewPort = false)

Start a number of additional silo, so that they join the existing cluster.

Parameters

silosToStartint: Number of silos to start.
startAdditionalSiloOnNewPortbool

Returns

List of SiloHandles for the newly started silos.

StartAdditionalSilosAsync(int, bool, CancellationToken)

public Task<List<SiloHandle>> StartAdditionalSilosAsync(int silosToStart, bool startAdditionalSiloOnNewPort, CancellationToken cancellationToken)

Start a number of additional silos, so that they join the existing cluster.

Parameters

silosToStartint: Number of silos to start.
startAdditionalSiloOnNewPortbool: Whether to start each silo on a new port.
cancellationTokenCancellationToken: The token used to cancel silo startup.

Returns

List of silo handles for the newly started silos.

StartSiloAsync(int, TestClusterOptions, IReadOnlyList<IConfigurationSource>, bool)

public Task<SiloHandle> StartSiloAsync(int instanceNumber, TestClusterOptions clusterOptions, IReadOnlyList<IConfigurationSource>? configurationOverrides = null, bool startSiloOnNewPort = false)

Starts a new silo.

Parameters

instanceNumberint: The instance number to deploy
clusterOptionsTestClusterOptions: The options to use.
configurationOverridesIReadOnlyList<IConfigurationSource>: Configuration overrides.
startSiloOnNewPortbool: Whether we start this silo on a new port, instead of the default one

Returns

A handle to the deployed silo.

StartSiloAsync(int, TestClusterOptions, IReadOnlyList<IConfigurationSource>, bool, CancellationToken)

public Task<SiloHandle> StartSiloAsync(int instanceNumber, TestClusterOptions clusterOptions, IReadOnlyList<IConfigurationSource>? configurationOverrides, bool startSiloOnNewPort, CancellationToken cancellationToken)

Starts a new silo.

Parameters

instanceNumberint: The instance number to deploy.
clusterOptionsTestClusterOptions: The options to use.
configurationOverridesIReadOnlyList<IConfigurationSource>: Configuration overrides.
startSiloOnNewPortbool: Whether to start this silo on a new port.
cancellationTokenCancellationToken: The token used to cancel silo startup.

Returns

A handle to the deployed silo.

StartSiloAsync(TestCluster, int, TestClusterOptions, IReadOnlyList<IConfigurationSource>, bool)

static

public static Task<SiloHandle> StartSiloAsync(TestCluster cluster, int instanceNumber, TestClusterOptions clusterOptions, IReadOnlyList<IConfigurationSource>? configurationOverrides = null, bool startSiloOnNewPort = false)

Start a new silo in the target cluster

Parameters

clusterTestCluster: The TestCluster in which the silo should be deployed
instanceNumberint: The instance number to deploy
clusterOptionsTestClusterOptions: The options to use.
configurationOverridesIReadOnlyList<IConfigurationSource>: Configuration overrides.
startSiloOnNewPortbool: Whether we start this silo on a new port, instead of the default one

Returns

A handle to the silo deployed

StopAllSilos

public void StopAllSilos()

Stop all current silos.

StopAllSilosAsync

public Task StopAllSilosAsync()

Stop all current silos.

StopAllSilosAsync(CancellationToken)

public Task StopAllSilosAsync(CancellationToken cancellationToken)

Stop all current silos.

Parameters

cancellationTokenCancellationToken: The token used to cancel shutdown.

StopClusterClientAsync

public Task StopClusterClientAsync()

Stop cluster client as an asynchronous operation.

Returns

A System.Threading.Tasks.Task representing the asynchronous operation.

StopClusterClientAsync(CancellationToken)

public Task StopClusterClientAsync(CancellationToken cancellationToken)

Stop cluster client as an asynchronous operation.

Parameters

cancellationTokenCancellationToken: The token used to cancel shutdown.

Returns

A System.Threading.Tasks.Task representing the asynchronous operation.

StopPrimarySiloAsync

public Task StopPrimarySiloAsync()

Stops the default Primary silo.

StopPrimarySiloAsync(CancellationToken)

public Task StopPrimarySiloAsync(CancellationToken cancellationToken)

Stops the default Primary silo.

Parameters

cancellationTokenCancellationToken: The token used to cancel shutdown.

StopSecondarySilosAsync

public Task StopSecondarySilosAsync()

Stop any additional silos, not including the default Primary silo.

StopSecondarySilosAsync(CancellationToken)

public Task StopSecondarySilosAsync(CancellationToken cancellationToken)

Stop any additional silos, not including the default Primary silo.

Parameters

cancellationTokenCancellationToken: The token used to cancel shutdown.

StopSiloAsync(SiloHandle)

public Task StopSiloAsync(SiloHandle instance)

Do a semi-graceful Stop of the specified silo.

Parameters

instanceSiloHandle: Silo to be stopped.

StopSiloAsync(SiloHandle, CancellationToken)

public Task StopSiloAsync(SiloHandle instance, CancellationToken cancellationToken)

Do a semi-graceful Stop of the specified silo.

Parameters

instanceSiloHandle: Silo to be stopped.
cancellationTokenCancellationToken: The token used to cancel shutdown.

TryGetGrainContext(GrainId, IGrainContext?)

public bool TryGetGrainContext(GrainId grainId, out IGrainContext? grainContext)

Attempts to find the IGrainContext for the grain with the specified grainId by searching all silos in the cluster.

Parameters

grainIdGrainId: The ID of the grain to find.
grainContextIGrainContext?: When this method returns, contains the grain context if found; otherwise, null.

Returns

true if the grain was found in one of the silos; otherwise, false.

WaitForClusterManifestToStabilizeAsync(bool)

public Task WaitForClusterManifestToStabilizeAsync(bool didKill = false)

Wait for active silos to observe cluster manifest updates for all active silos.

Parameters

didKillbool: Whether recent membership changes were done by graceful Stop.

WaitForDeactivationAsync(GrainId)

public Task WaitForDeactivationAsync(GrainId grainId)

Gets a System.Threading.Tasks.Task that completes when the current activation of the specified grain finishes deactivating. If the grain is not currently activated, returns System.Threading.Tasks.Task.CompletedTask.

Parameters

grainIdGrainId: The ID of the grain to observe.

Returns

A task that completes when the grain's current activation has deactivated.

Examples

            var deactivated = cluster.WaitForDeactivationAsync(grain.GetGrainId());
            await grain.DoDeactivate();
            await deactivated;

WaitForDeactivationAsync(IAddressable)

public Task WaitForDeactivationAsync(IAddressable grain)

Gets a System.Threading.Tasks.Task that completes when the current activation of the specified grain finishes deactivating. If the grain is not currently activated, returns System.Threading.Tasks.Task.CompletedTask.

Parameters

grainIAddressable: The grain to observe.

Returns

A task that completes when the grain's current activation has deactivated.

Examples

            var deactivated = cluster.WaitForDeactivationAsync(grain.GetGrainId());
            await grain.DoDeactivate();
            await deactivated;

WaitForLivenessToStabilizeAsync(bool)

public Task WaitForLivenessToStabilizeAsync(bool didKill = false)

Wait for the silo liveness sub-system to detect and act on any recent cluster membership changes.

Parameters

didKillbool: Whether recent membership changes we done by graceful Stop.