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.