Class ScreenplayExtensions

Namespace

CSF.Screenplay

Assembly

CSF.Screenplay.dll

Extension methods for the Screenplay type.

public static class ScreenplayExtensions

Inheritance

object

ScreenplayExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

CreateScopedPerformance(Screenplay, IList<IdentifierAndName>)

Creates a new IPerformance within its own newly-created Dependency Injection scope.

public static ScopeAndPerformance CreateScopedPerformance(this Screenplay screenplay, IList<IdentifierAndName> namingHierarchy = null)

Parameters

screenplay Screenplay

The Screenplay from which to create the performance

namingHierarchy IList<IdentifierAndName>

An optional collection of identifiers and names providing the hierarchical name of this performance; see NamingHierarchy for more information.

Returns

ScopeAndPerformance

A ScopeAndPerformance containing the newly-created performance as well as the newly-started DI scope.

Remarks

This method includes the consequence/side-effect of creating a new dependency injection scope from the ServiceProvider associated with the specified Screenplay. That scope will be associated with the created performance and will be returned as part of the return of this method. Please use the Dispose() method the returned object when you are finished with the performance. This ensures that the DI scope and all associated resources (including the performance) will also be properly disposed-of.

Exceptions

ArgumentNullException

If screenplay is null.

ExecuteAsPerformance(Screenplay, Func<IServiceProvider, bool?>, IList<IdentifierAndName>, int)

Executes the specified logic as a Performance, synchronously.

public static void ExecuteAsPerformance(this Screenplay screenplay, Func<IServiceProvider, bool?> performanceLogic, IList<IdentifierAndName> namingHierarchy = null, int timeoutMiliseconds = 0)

Parameters

screenplay Screenplay

The screenplay with which to execute the logic.

performanceLogic Func<IServiceProvider, bool?>

The logic to be executed by the performance.

namingHierarchy IList<IdentifierAndName>

An optional naming hierarchy used to identify the performance.

timeoutMiliseconds int

If set to a non-zero positive value, then the performance logic will be aborted after the specified timeout in milliseconds.

Remarks

This method is the primary entry point for beginning a Screenplay Performance. This method begins a new Dependency Injection Scope, and within that scope starts the performance, which executes the specified performance logic: performanceLogic. The return value from the performance logic should conform to the semantics of the parameter value passed to FinishPerformance(bool?).

The namingHierarchy may be used to give the performance a name, so that its results (and subsequent report) may be identified. This parameter has the same semantics as NamingHierarchy.

Use this method only if ExecuteAsPerformanceAsync(Func<IServiceProvider, CancellationToken, Task<bool?>>, IList<IdentifierAndName>, CancellationToken) is not viable. This method executes the logic asynchronously, as is the architecture of Screenplay, but then uses Wait(CancellationToken) to convert the asynchronous result into a synchronous one.

If timeoutMiliseconds is not specified, or specified with a zero value then there will be no timeout applied to the performance's logic. If specified with a positive integer then the performance logic will be aborted if the specified timeout (in milliseconds) is exceeded. Please be aware that - as with Wait(CancellationToken) - if the timeout duration is exceded, the synchronous performance logic is not actually aborted. The thread on which this method is executed will stop waiting for the thread on which the performance logic is running, but the performance logic thread will still continue, typically to completion. All this means is that when the performance logic eventually does complete, its results are discarded because the Screenplay 'gave up waiting' for it.

Exceptions

ArgumentNullException

If either screenplay or performanceLogic is null.

ArgumentOutOfRangeException

If timeoutMiliseconds is a negative number.

See Also

ExecuteAsPerformance(Screenplay, Func<IServiceProvider, bool?>, IList<IdentifierAndName>, CancellationToken)

ExecuteAsPerformance(Screenplay, Func<IServiceProvider, bool?>, IList<IdentifierAndName>, CancellationToken)

Executes the specified logic as a Performance, synchronously.

public static void ExecuteAsPerformance(this Screenplay screenplay, Func<IServiceProvider, bool?> performanceLogic, IList<IdentifierAndName> namingHierarchy, CancellationToken cancellationToken)

Parameters

screenplay Screenplay

The screenplay with which to execute the logic.

performanceLogic Func<IServiceProvider, bool?>

The logic to be executed by the performance.

namingHierarchy IList<IdentifierAndName>

A naming hierarchy used to identify the performance; if null then an empty name will be used.

cancellationToken CancellationToken

A cancellation token, which if cancelled will abort waiting for performanceLogic to complete.

Remarks

This method is the primary entry point for beginning a Screenplay Performance. This method begins a new Dependency Injection Scope, and within that scope starts the performance, which executes the specified performance logic: performanceLogic. The return value from the performance logic should conform to the semantics of the parameter value passed to FinishPerformance(bool?).

The namingHierarchy may be used to give the performance a name, so that its results (and subsequent report) may be identified. This parameter has the same semantics as NamingHierarchy.

Use this method only if ExecuteAsPerformanceAsync(Func<IServiceProvider, CancellationToken, Task<bool?>>, IList<IdentifierAndName>, CancellationToken) is not viable. This method executes the logic asynchronously, as is the architecture of Screenplay, but then uses Wait(CancellationToken) to convert the asynchronous result into a synchronous one.

If cancellationToken is not specified then no cancellation/abort logic will be applied. If specified, and the token is cancelled, then the Screenplay will abort waiting for the performance logic to complete. Please be aware that - as with Wait(CancellationToken) - if the token is cancelled, the synchronous performance logic is not actually aborted. The thread on which this method is executed will stop waiting for the thread on which the performance logic is running, but the performance logic thread will still continue, typically to completion. All this means is that when the performance logic eventually does complete, its results are discarded because the Screenplay 'gave up waiting' for it.

Exceptions

ArgumentNullException

If either screenplay or performanceLogic is null.

ExecuteAsPerformanceAsync<T>(Screenplay, IList<IdentifierAndName>, CancellationToken)

Executes the logic with a specified imlpementation of IHostsPerformance as a Performance

public static Task ExecuteAsPerformanceAsync<T>(this Screenplay screenplay, IList<IdentifierAndName> namingHierarchy = null, CancellationToken cancellationToken = default) where T : IHostsPerformance

Parameters

screenplay Screenplay

The screenplay with which to execute the logic.

namingHierarchy IList<IdentifierAndName>

An optional naming hierarchy used to identify the performance.

cancellationToken CancellationToken

An optional cancellation token to abort the performance logic.

Returns

Task

A task which completes when the performance's logic has completed.

Type Parameters

T

The concrete type of an implementation of IHostsPerformance which contains the performance logic.

Remarks

This method is a convenient way to execute performances, where the logic for the performance is contained within a concrete type. This method begins a new Dependency Injection Scope, and within that scope starts the performance. It resolves an instance of the specified T from the DI container, and executes its ExecutePerformanceAsync(CancellationToken) method to get the performance result.

An advantage of using this method is that the performance logic is encapsulated within a class, and that the service provider is used to resolve only a single object instance, thus avoiding the service locator anti-pattern.

The namingHierarchy may be used to give the performance a name, so that its results (and subsequent report) may be identified. This parameter has the same semantics as NamingHierarchy.

Note that if the specified implementation of IHostsPerformance raises a PerformableException then this method will catch that exception and not rethrow. In that case:

• An event will be raised with the event bus: IHasPerformanceEvents, specifically PerformableFailed. This will contain details of the exception which occurred; subscribers to be informed that the performance has failed.
• The performance will be immediately terminated and placed into the Failed state.

Any other exception, which does not derive from PerformableException, will not be caught by this method and will propagate outward. These exceptions will be interpreted as an error within the Screenplay architecture, since the Actor class will always catch and rethrow any exception encountered from any overload of PerformAsync, wrapped as the inner exception of a PerformableException.

Exceptions

ArgumentNullException

If the screenplay is null.

See Also

IHostsPerformance