Class Command

Namespace

WebDriverBiDi.Protocol

Assembly

WebDriverBiDi.dll

Object containing data about a WebDriver BiDi command.

[JsonConverter(typeof(CommandJsonConverter))]
public class Command

Inheritance

object

Command

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

Command(long, CommandParameters)

Initializes a new instance of the Command class whose completion timeout is measured by System.

public Command(long commandId, CommandParameters commandData)

Parameters

commandId long

The ID of the command.

commandData CommandParameters

The settings for the command, including parameters.

Exceptions

ArgumentNullException

Thrown when the command parameters are null.

Command(long, CommandParameters, TimeProvider)

Initializes a new instance of the Command class.

public Command(long commandId, CommandParameters commandData, TimeProvider timeProvider)

Parameters

commandId long

The ID of the command.

commandData CommandParameters

The settings for the command, including parameters.

timeProvider TimeProvider

The System.TimeProvider whose clock measures the timeout passed to WaitForCompletionAsync(TimeSpan, CancellationToken). A Transport passes its own provider, so a transport whose waits run on virtual time (in a test, say) times its commands out on that same clock. ElapsedMilliseconds is a diagnostic measured against real time regardless.

Exceptions

ArgumentNullException

Thrown when the command parameters or the time provider are null.

Properties

AdditionalCommandProperties

Gets additional properties to be serialized with this command envelope. Note carefully this serializes these additional properties at the top level of the command; additional properties to be serialized with the command parameters should use the AdditionalData property.

[JsonExtensionData]
public Dictionary<string, object?> AdditionalCommandProperties { get; }

Property Value

Dictionary<string, object>

Remarks

An entry may not use id, method or params as its name: the envelope writes those itself, so the message would carry the name twice, and a JSON object with a duplicate name has no defined meaning. Sending such a command throws WebDriverBiDiSerializationException rather than emitting the ambiguous payload.

CommandId

Gets the ID of the command.

[JsonPropertyName("id")]
public long CommandId { get; }

Property Value

long

CommandName

Gets the method name of the command.

[JsonPropertyName("method")]
public string CommandName { get; }

Property Value

string

CommandParameters

Gets the parameters of the command.

[JsonPropertyName("params")]
public CommandParameters CommandParameters { get; }

Property Value

CommandParameters

ElapsedMilliseconds

Gets the elapsed time in milliseconds since the command was sent by a Transport.

[JsonIgnore]
public long ElapsedMilliseconds { get; }

Property Value

long

Remarks

This is zero until the command is sent, runs while the command is in flight, and freezes at the point a response, an error or a send failure stopped it.

IsCanceled

Gets a value indicating whether this command has been canceled.

[JsonIgnore]
public bool IsCanceled { get; }

Property Value

bool

ResponseType

Gets the type of the response for this command.

[JsonIgnore]
public Type ResponseType { get; }

Property Value

Type

ThrownException

Gets the exception thrown during execution of the command, or null if the command has not faulted.

[JsonIgnore]
public virtual Exception? ThrownException { get; }

Property Value

Exception

Methods

Cancel()

Cancels the task used to wait for completion of this command, reporting whether the cancellation took effect.

public virtual bool Cancel()

Returns

bool

true if this call transitioned the command to the canceled state; false if the command had already completed with a result, faulted, or been canceled, in which case the existing outcome stands and this call has no effect.

SetException(Exception)

Faults the command with the specified exception, completing the underlying task. If the command has already been completed, faulted, or canceled, this method is a safe no-op.

public virtual void SetException(Exception exception)

Parameters

exception Exception

The exception that caused the command to fail.

SetResult(CommandResult)

Sets the result of the command, completing the underlying task. If the command has already been completed, faulted, or canceled, this method is a safe no-op.

public virtual void SetResult(CommandResult result)

Parameters

result CommandResult

The result of the command.

TryGetResult(out CommandResult?)

Attempts to get the result of the command if it has completed successfully.

public virtual bool TryGetResult(out CommandResult? commandResult)

Parameters

commandResult CommandResult

When this method returns, contains the result of the command, or null if the command has not completed successfully.

Returns

bool

true if the result was retrieved successfully; otherwise, false.

WaitForCompletionAsync(TimeSpan, CancellationToken)

Waits for the command to complete or until the specified timeout elapses.

public virtual Task<bool> WaitForCompletionAsync(TimeSpan timeout, CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan

The timeout to wait for the command to complete. Must be non-negative and no greater than the maximum timer duration supported by the runtime, or InfiniteTimeSpan to wait indefinitely.

cancellationToken CancellationToken

A cancellation token used to propagate notification that the operation should be canceled.

Returns

Task<bool>

true if the command completes before the timeout; otherwise false.

Exceptions

ArgumentOutOfRangeException

Thrown when timeout is negative (other than InfiniteTimeSpan) or exceeds the maximum supported timer duration.

OperationCanceledException

Thrown when cancellationToken is canceled.

WaitForOutcomeAsync(TimeSpan, CancellationToken)

Asynchronously waits for this command's outcome, for the timeout to elapse, or for the token to be canceled, whichever happens first.

protected virtual Task WaitForOutcomeAsync(TimeSpan timeout, CancellationToken cancellationToken)

Parameters

timeout TimeSpan

The timeout, measured by this command's System.TimeProvider, or InfiniteTimeSpan to wait until the command completes or the token is canceled.

cancellationToken CancellationToken

A cancellation token used to propagate notification that the wait should be canceled.

Returns

Task

A task that completes as the command does if the command finishes first, rethrowing a fault or cancellation of the command itself; faults with a TimeoutException if the timeout elapses first; or is canceled if the token is canceled first.

Remarks

WaitForCompletionAsync(TimeSpan, CancellationToken) calls this method only for a command that has not yet completed, and interprets how the returned task ends. A task that ends in any way at all, once the command has completed, is reported as completion: the command may complete in the moment between the timeout elapsing, or the token being canceled, and that outcome being examined, and the completed command is the outcome the caller can act on.

This method is protected virtual to allow test doubles to fix the order in which the command completes and the wait ends, which in normal operation is decided by the thread pool.