Class Operation<TResponse, TMetadata> (2.3.0)

public sealed class Operation<TResponse, TMetadata> : object where TResponse : class, IMessage<TResponse>, new()
    where TMetadata : class, IMessage<TMetadata>, new()

A long-running operation with an associated client, and which knows the expected response type.

Inheritance

Object > Operation<TResponse, TMetadata>

Namespace

Google.LongRunning

Assembly

Google.LongRunning.dll

Type Parameters

NameDescription
TResponse

The response message type.

TMetadata

The metata message type.

Remarks

For simplicity, no methods on this type modify the proto message. Instead, to get up-to-date information you can use Refresh to obtain a new instance.

If the operation was created with a different major version of the service API than expected, the metadata and response values may not be of the expected type. There are three approaches to handling this:

  • To fail with an exception if an unexpected type of value is present, use the Result and Metadata properties.
  • To receive a null reference if an unexpected type of value is present, use the GetResultOrNull() and GetMetadataOrNull() methods. You can then check the returned value and ignore nulls.
  • To handle multiple types, use the RpcMessage property and its Response and Metadata properties, of type . You can then use to determine the type of the value to unpack, or with each type you support.

Constructors

Operation(Operation, OperationsClient)

public Operation(Operation rpcMessage, OperationsClient client)

Constructs a new instance from the given RPC message.

Parameters
NameDescription
rpcMessageOperation

The RPC message describing the operation. Must not be null.

clientOperationsClient

The client to use for further calls. Must not be null.

Properties

Client

public OperationsClient Client { get; }

The client to use when making RPCs.

Property Value
TypeDescription
OperationsClient

Exception

public OperationFailedException Exception { get; }

The error associated with the operation, as an OperationFailedException, or null if the operation is not in an error state (either because it completed successfully, or because it has not yet completed).

Property Value
TypeDescription
OperationFailedException
Remarks

Only the in-memory representation of the operation (this object) is consulted for its state.

IsCompleted

public bool IsCompleted { get; }

Whether the operation has completed, where "complete" can include "failed".

Property Value
TypeDescription
Boolean
Remarks

Only the in-memory representation of the operation (this object) is consulted for its state.

IsFaulted

public bool IsFaulted { get; }

Whether the operation has completed with a failure.

Property Value
TypeDescription
Boolean

Metadata

public TMetadata Metadata { get; }

Retrieves the metadata associated with this operation, or null if there is no metadata in the underlying response message.

Property Value
TypeDescription
TMetadata
Remarks

Only the in-memory representation of the operation (this object) is consulted for its state. See the Operation documentation for information about dealing with different metadata type versions.

Name

public string Name { get; }

Returns the name of the operation, which can be persisted and used to poll for the latest results at a later time or in a different program.

Property Value
TypeDescription
String
Remarks

Only the in-memory representation of the operation (this object) is consulted for its state.

Result

public TResponse Result { get; }

Retrieves the result of the operation, throwing an exception if the operation failed, hasn't completed, or has an unexpected result type. Unlike , this does not block. If the operation has completed but the result is not present (for example due to being excluded by a field mask) this returns null.

Property Value
TypeDescription
TResponse
Remarks

Only the in-memory representation of the operation (this object) is consulted for its state. See the Operation documentation for information about dealing with different response type versions.

Exceptions
TypeDescription
OperationFailedException

The operation completed with an error.

RpcMessage

public Operation RpcMessage { get; }

The protobuf message associated with the long-running operation, containing the name (for further retrieval) and any error/result already computed. This should not be mutated.

Property Value
TypeDescription
Operation

Methods

Cancel(CallSettings)

public void Cancel(CallSettings callSettings = null)

Attempts to cancel the long-running operation.

Parameter
NameDescription
callSettingsCallSettings

Any overriding call settings to apply to the RPC.

CancelAsync(CallSettings)

public Task CancelAsync(CallSettings callSettings = null)

Asynchronously attempts to cancel the long-running operation.

Parameter
NameDescription
callSettingsCallSettings

Any overriding call settings to apply to the RPC.

Returns
TypeDescription
Task

A task representing the asynchronous cancel operation.

CancelAsync(CancellationToken)

public Task CancelAsync(CancellationToken cancellationToken)

Asynchronously attempts to cancel the long-running operation.

Parameter
NameDescription
cancellationTokenCancellationToken

A cancellation token for the cancel RPC. Note that this is not a cancellation token for the long-running operation itself.

Returns
TypeDescription
Task

A task representing the asynchronous cancel operation.

Delete(CallSettings)

public void Delete(CallSettings callSettings = null)

Deletes the long-running operation. This does not cancel it; it only indicates that the client is no longer interested in the result.

Parameter
NameDescription
callSettingsCallSettings

Any overriding call settings to apply to the RPC.

DeleteAsync(CallSettings)

public Task DeleteAsync(CallSettings callSettings = null)

Asynchronously deletes the long-running operation. This does not cancel it; it only indicates that the client is no longer interested in the result.

Parameter
NameDescription
callSettingsCallSettings

Any overriding call settings to apply to the RPC.

Returns
TypeDescription
Task

A task representing the asynchronous deletion operation.

DeleteAsync(CancellationToken)

public Task DeleteAsync(CancellationToken cancellationToken)

Asynchronously deletes the long-running operation. This does not cancel it; it only indicates that the client is no longer interested in the result.

Parameter
NameDescription
cancellationTokenCancellationToken

A cancellation token for the cancel RPC. Note that this is not a cancellation token for the long-running operation itself.

Returns
TypeDescription
Task

A task representing the asynchronous deletion operation.

GetMetadataOrNull()

public TMetadata GetMetadataOrNull()

Retrieves the metadata associated with this operation, or null if either there is no metadata in the underlying response message, or it does not have the expected type.

Returns
TypeDescription
TMetadata

The metadata of the operation if possible, or null otherwise.

Remarks

Only the in-memory representation of the operation (this object) is consulted for its state. See the Operation documentation for information about dealing with different metadata type versions.

GetResultOrNull()

public TResponse GetResultOrNull()

Retrieves the result of the operation, or null if the operation failed, hasn't completed, has an unexpected result type, or didn't contain a result at all.

Returns
TypeDescription
TResponse

The result of the operation if possible, or null otherwise.

Remarks

Only the in-memory representation of the operation (this object) is consulted for its state. See the Operation documentation for information about dealing with different response type versions.

PollOnce(CallSettings)

public Operation<TResponse, TMetadata> PollOnce(CallSettings callSettings = null)

Returns a new instance reflecting the most recent state of the operation.

Parameter
NameDescription
callSettingsCallSettings

Any overriding call settings to apply to the RPC.

Returns
TypeDescription
Operation<TResponse, TMetadata>

The most recent state of the operation, or a reference to the same object if the operation has already completed.

PollOnceAsync(CallSettings)

public Task<Operation<TResponse, TMetadata>> PollOnceAsync(CallSettings callSettings = null)

Asynchronously returns a new instance reflecting the most recent state of the operation.

Parameter
NameDescription
callSettingsCallSettings

Any overriding call settings to apply to the RPC.

Returns
TypeDescription
Task<Operation<TResponse, TMetadata>>

A task representing the asynchronous poll operation. The result of the task is the most recent state of the operation, or a reference to the same object if the operation has already completed.

PollOnceAsync(CancellationToken)

public Task<Operation<TResponse, TMetadata>> PollOnceAsync(CancellationToken cancellationToken)

Asynchronously returns a new instance reflecting the most recent state of the operation.

Parameter
NameDescription
cancellationTokenCancellationToken

A cancellation token for the poll operation.

Returns
TypeDescription
Task<Operation<TResponse, TMetadata>>

A task representing the asynchronous poll operation. The result of the task is the most recent state of the operation, or a reference to the same object if the operation has already completed.

PollOnceFromName(String, OperationsClient, CallSettings)

public static Operation<TResponse, TMetadata> PollOnceFromName(string name, OperationsClient client, CallSettings callSettings = null)

Creates a new instance reflecting the most recent state of the operation with the specified name.

Parameters
NameDescription
nameString

The name of the operation, as returned when it was created. Must not be null.

clientOperationsClient

The client to make the RPC call.

callSettingsCallSettings

Any overriding call settings to apply to the RPC. May be null, in which case the default settings are used.

Returns
TypeDescription
Operation<TResponse, TMetadata>

The current state of the operation identified by name.

PollOnceFromNameAsync(String, OperationsClient, CallSettings)

public static Task<Operation<TResponse, TMetadata>> PollOnceFromNameAsync(string name, OperationsClient client, CallSettings callSettings = null)

Asynchronously creates a new instance reflecting the most recent state of the operation with the specified name.

Parameters
NameDescription
nameString

The name of the operation, as returned when it was created. Must not be null.

clientOperationsClient

The client to make the RPC call.

callSettingsCallSettings

Any overriding call settings to apply to the RPC. May be null, in which case the default settings are used.

Returns
TypeDescription
Task<Operation<TResponse, TMetadata>>

A task representing the asynchronous "fetch" operation. The result of the task is the current state of the operation identified by name.

PollOnceFromNameAsync(String, OperationsClient, CancellationToken)

public static Task<Operation<TResponse, TMetadata>> PollOnceFromNameAsync(string name, OperationsClient client, CancellationToken cancellationToken)

Asynchronously creates a new instance reflecting the most recent state of the operation with the specified name.

Parameters
NameDescription
nameString

The name of the operation, as returned when it was created. Must not be null.

clientOperationsClient

The client to make the RPC call.

cancellationTokenCancellationToken

A cancellation token for the "fetch" operation.

Returns
TypeDescription
Task<Operation<TResponse, TMetadata>>

A task representing the asynchronous "fetch" operation. The result of the task is the current state of the operation identified by name.

PollUntilCompleted(PollSettings, CallSettings, Action<TMetadata>)

public Operation<TResponse, TMetadata> PollUntilCompleted(PollSettings pollSettings = null, CallSettings callSettings = null, Action<TMetadata> metadataCallback = null)

Polls the operation until it is complete, returning the completed operation.

Parameters
NameDescription
pollSettingsPollSettings

The settings to use for repeated polling, or null to use the default poll settings (poll once every 10 seconds, forever).

callSettingsCallSettings

The call settings to apply on each call, or null for default settings.

metadataCallbackAction<TMetadata>

The callback to invoke with the metadata from each poll operation, even if the metadata is null.

Returns
TypeDescription
Operation<TResponse, TMetadata>

The completed operation, which can then be checked for errors or a result.

Remarks

If this object already represents a completed operation, it is returned with no further RPCs. If metadataCallback is non-null, the callback will be called with any metadata present before the result is returned.

Each callback is performed synchronously: this method waits for the callback to complete before the operation is next polled. This guarantees that for a single call, metadata callbacks will never occur in parallel.

PollUntilCompletedAsync(PollSettings, CallSettings, Action<TMetadata>)

public Task<Operation<TResponse, TMetadata>> PollUntilCompletedAsync(PollSettings pollSettings = null, CallSettings callSettings = null, Action<TMetadata> metadataCallback = null)

Asynchronously polls the operation until it is complete, returning the completed operation.

Parameters
NameDescription
pollSettingsPollSettings

The settings to use for repeated polling, or null to use the default poll settings (poll once every 10 seconds, forever).

callSettingsCallSettings

The call settings to apply on each call, or null for default settings.

metadataCallbackAction<TMetadata>

The callback to invoke with the metadata from each poll operation, even if the metadata is null.

Returns
TypeDescription
Task<Operation<TResponse, TMetadata>>

The completed operation, which can then be checked for errors or a result.

Remarks

If this object already represents a completed operation, it is returned with no further RPCs. If metadataCallback is non-null, the callback will be called with any metadata present before the result is returned.

No guarantee is made as to which thread is used for metadata callbacks. However, each callback is performed synchronously: this method waits for the callback to complete before the operation is next polled. This guarantees that for a single call, metadata callbacks will never occur in parallel.