Class Actor

Namespace

CSF.Screenplay

Assembly

CSF.Screenplay.Abstractions.dll

A representation of an autonomous, or at least seemingly-autonomous, person or system which directs the events of a IPerformance.

public class Actor : IHasAbilities, IHasName, IHasPerformanceIdentity, IDisposable, IHasPerformableEvents, ICanPerform, ICanPerformGiven, ICanPerformWhen, ICanPerformThen

Inheritance

object

Actor

Implements

IHasAbilities

IHasName

IHasPerformanceIdentity

IDisposable

IHasPerformableEvents

ICanPerform

ICanPerformGiven

ICanPerformWhen

ICanPerformThen

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ActorExtensions.WasAbleTo(ICanPerformGiven, IGetsPerformable, CancellationToken)

ActorExtensions.WasAbleTo(ICanPerformGiven, IGetsPerformableWithResult, CancellationToken)

ActorExtensions.WasAbleTo<T>(ICanPerformGiven, IGetsPerformableWithResult<T>, CancellationToken)

ActorExtensions.Should(ICanPerformThen, IGetsPerformable, CancellationToken)

ActorExtensions.Should(ICanPerformThen, IGetsPerformableWithResult, CancellationToken)

ActorExtensions.Should<T>(ICanPerformThen, IGetsPerformableWithResult<T>, CancellationToken)

ActorExtensions.AttemptsTo(ICanPerformWhen, IGetsPerformable, CancellationToken)

ActorExtensions.AttemptsTo(ICanPerformWhen, IGetsPerformableWithResult, CancellationToken)

ActorExtensions.AttemptsTo<T>(ICanPerformWhen, IGetsPerformableWithResult<T>, CancellationToken)

ActorExtensions.GetAbility(ICanPerform, Type)

ActorExtensions.GetAbility<T>(ICanPerform)

ActorExtensions.HasAbility(ICanPerform, Type)

ActorExtensions.HasAbility<T>(ICanPerform)

ActorExtensions.IsAbleTo(ICanPerform, object)

ActorExtensions.IsAbleTo<TAbility>(ICanPerform)

ActorExtensions.PerformAsync(ICanPerform, IGetsPerformable, CancellationToken)

ActorExtensions.PerformAsync(ICanPerform, IGetsPerformableWithResult, CancellationToken)

ActorExtensions.PerformAsync<T>(ICanPerform, IGetsPerformableWithResult<T>, CancellationToken)

ActorExtensions.HasAbility(IHasAbilities, Type)

ActorExtensions.HasAbility<T>(IHasAbilities)

Examples

A good example of an actor, aside from a person, could be task scheduling software which executes logic at specific times of day. That is - provided that the task scheduling software itself is not a part of the Screenplay Performance. Within the context of such a performance, the task scheduler executing its logic at the configured time would appear to be an autonomous action because nothing else within the scope of the performance prompted it.

Conversely, a mouse trap would be a poor example of an actor; a mouse trap acts only reactively. The creature entering the trap would be the actor in such a performance.

Remarks

An actor should represent an autonomous or semi-autonomous system. Most commonly is a human being using a piece of software. An actor might also represent an automated system which acts according to policy, so long as configuring/initating that system is not a part of the IPerformance. Within a performance, each performable item is executed in the context of the actor which performed it.

Actors have abilities which provide them the means by which to interact with the software.

A single conceptual actor must be represented by a single instance of this type; two actors of the same name are not considered to be the same actor, nor will they behave as such. Instances of actor should have an object lifetime which lasts for the remainder of the performance in which they were created. Instances of actor must not be shared across performances. In other words, they should be scoped to only a single performance.

A single performance might involve only one actor or it might involve many. If a performance makes use of multiple actors, the developer should consider making use of either or both of the ICast and/or IStage, which assist in the management of multiple actors.

Constructors

Actor(string, Guid)

Initialises a new instance of Actor

public Actor(string name, Guid performanceIdentity)

Parameters

name string

The actor's name

performanceIdentity Guid

A unique identity for the performance

Remarks

In line with IHasName, it is strongly recommended that name is not null.

Properties

Abilities

Gets a collection of the actor's abilities

protected virtual HashSet<object> Abilities { get; }

Property Value

HashSet<object>

Name

Gets the actor's name

public virtual string Name { get; }

Property Value

string

See Also

IHasName

PerformanceIdentity

Gets the unique identity for the performance in which this actor is participating

protected virtual Guid PerformanceIdentity { get; }

Property Value

Guid

Methods

Dispose()

public void Dispose()

Dispose(bool)

Disposes the current instance, via the Dispose Pattern.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

A value indicating wherher or not disposal should occur.

InvokeBeginPerformable(object, PerformancePhase)

Invokes the BeginPerformable event.

protected virtual void InvokeBeginPerformable(object performable, PerformancePhase phase = PerformancePhase.Unspecified)

Parameters

performable object

The performable item

phase PerformancePhase

The performance phase to which this event relates

InvokeEndPerformable(object, PerformancePhase)

Invokes the EndPerformable event.

protected virtual void InvokeEndPerformable(object performable, PerformancePhase phase = PerformancePhase.Unspecified)

Parameters

performable object

The performable item

phase PerformancePhase

The performance phase to which this event relates

InvokeGainedAbility(object)

Invokes the GainedAbility event.

protected virtual void InvokeGainedAbility(object ability)

Parameters

ability object

The ability which this actor gained

InvokePerformableFailed(object, Exception, PerformancePhase)

Invokes the PerformableFailed event.

protected virtual void InvokePerformableFailed(object performable, Exception exception, PerformancePhase phase = PerformancePhase.Unspecified)

Parameters

performable object

The performable item

exception Exception

The exception which halted the performable

phase PerformancePhase

The performance phase to which this event relates

InvokePerformableResult(object, object, PerformancePhase)

Invokes the PerformableResult event.

protected virtual void InvokePerformableResult(object performable, object result, PerformancePhase phase = PerformancePhase.Unspecified)

Parameters

performable object

The performable item

result object

The result value from the performable

phase PerformancePhase

The performance phase to which this event relates

InvokeRecordsAsset(object, string, string, PerformancePhase)

Invokes the RecordsAsset event.

protected virtual void InvokeRecordsAsset(object performable, string filePath, string fileSummary = null, PerformancePhase phase = PerformancePhase.Unspecified)

Parameters

performable object

The performable item

filePath string

The full absolute path to the asset file

fileSummary string

An optional human-readable summary of the asset file

phase PerformancePhase

The performance phase to which this event relates

IsAbleTo(object)

Adds a new ability to the actor

protected virtual void IsAbleTo(object ability)

Parameters

ability object

The ability to add

Exceptions

ArgumentNullException

If the ability is null

InvalidOperationException

If the actor already has an ability of this type or a derived type

PerformAsync(IPerformable, PerformancePhase, CancellationToken)

Performs an action or task which returns no result.

protected virtual ValueTask PerformAsync(IPerformable performable, PerformancePhase phase = PerformancePhase.Unspecified, CancellationToken cancellationToken = default)

Parameters

performable IPerformable

The performable item

phase PerformancePhase

The performance phase to which the performable belongs

cancellationToken CancellationToken

An optional token to cancel the performable

Returns

ValueTask

A task which completes when the performable is complete

Exceptions

ArgumentNullException

If the performable is null

PerformAsync(IPerformableWithResult, PerformancePhase, CancellationToken)

Performs a question or question-like task which returns an untyped result.

protected virtual ValueTask<object> PerformAsync(IPerformableWithResult performable, PerformancePhase phase = PerformancePhase.Unspecified, CancellationToken cancellationToken = default)

Parameters

performable IPerformableWithResult

The performable item

phase PerformancePhase

The performance phase to which the performable belongs

cancellationToken CancellationToken

An optional token to cancel the performable

Returns

ValueTask<object>

A task which completes when the performable is complete

Exceptions

ArgumentNullException

If the performable is null

PerformAsync<T>(IPerformableWithResult<T>, PerformancePhase, CancellationToken)

Performs a question or question-like task which returns a strongly typed result.

protected virtual ValueTask<T> PerformAsync<T>(IPerformableWithResult<T> performable, PerformancePhase phase = PerformancePhase.Unspecified, CancellationToken cancellationToken = default)

Parameters

performable IPerformableWithResult<T>

The performable item

phase PerformancePhase

The performance phase to which the performable belongs

cancellationToken CancellationToken

An optional token to cancel the performable

Returns

ValueTask<T>

A task which completes when the performable is complete

Type Parameters

T

Exceptions

ArgumentNullException

If the performable is null

Events

BeginPerformable

Occurs when the actor begins the execution of a performable object.

public event EventHandler<PerformableEventArgs> BeginPerformable

Event Type

EventHandler<PerformableEventArgs>

EndPerformable

Occurs when an actor ends the execution of a performable object.

public event EventHandler<PerformableEventArgs> EndPerformable

Event Type

EventHandler<PerformableEventArgs>

GainedAbility

Occurs when an actor gains a new ability.

public event EventHandler<GainAbilityEventArgs> GainedAbility

Event Type

EventHandler<GainAbilityEventArgs>

PerformableFailed

Occurs when a performable object fails with an exception.

public event EventHandler<PerformableFailureEventArgs> PerformableFailed

Event Type

EventHandler<PerformableFailureEventArgs>

PerformableResult

Occurs when an actor receives a result from a perfperformable objectrmance.

public event EventHandler<PerformableResultEventArgs> PerformableResult

Event Type

EventHandler<PerformableResultEventArgs>

RecordsAsset

Occurs when an actor records the presence of a new file asset.

public event EventHandler<PerformableAssetEventArgs> RecordsAsset

Event Type

EventHandler<PerformableAssetEventArgs>

See Also

IPerformance

ICast

IStage