Class Operation<TResponse, TMetadata> (3.0.0)

Version 3.0.0

• 3.3.0 (latest)
• 3.2.0
• 3.1.0
• 3.0.0
• 2.3.0
• 2.2.0

public sealed class Operation<TResponse, TMetadata>
    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>

Inherited Members

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ToString()

Namespace

Google.LongRunning

Assembly

Google.LongRunning.dll

Type Parameters
Name	Description
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 Any. You can then use TypeUrl to determine the type of the value to unpack, or TryUnpack<T>(out T) 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
Name	Description
rpcMessage	Operation The RPC message describing the operation. Must not be null.
client	OperationsClient 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
Type	Description
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
Type	Description
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
Type	Description
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
Type	Description
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
Type	Description
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.

Exceptions
Type	Description
InvalidOperationException	Metadata is present, but is not of the expected type.

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
Type	Description
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 Result, 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
Type	Description
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
Type	Description
OperationFailedException	The operation completed with an error.
InvalidOperationException	The operation has not completed yet, or the result is present but not of the expected result type.

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
Type	Description
Operation

Methods

Cancel(CallSettings)

public void Cancel(CallSettings callSettings = null)

Attempts to cancel the long-running operation.

Parameter
Name	Description
callSettings	CallSettings 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
Name	Description
callSettings	CallSettings Any overriding call settings to apply to the RPC.

Returns
Type	Description
Task	A task representing the asynchronous cancel operation.

CancelAsync(CancellationToken)

public Task CancelAsync(CancellationToken cancellationToken)

Asynchronously attempts to cancel the long-running operation.

Parameter
Name	Description
cancellationToken	CancellationToken A cancellation token for the cancel RPC. Note that this is not a cancellation token for the long-running operation itself.

Returns
Type	Description
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
Name	Description
callSettings	CallSettings 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
Name	Description
callSettings	CallSettings Any overriding call settings to apply to the RPC.

Returns
Type	Description
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
Name	Description
cancellationToken	CancellationToken A cancellation token for the cancel RPC. Note that this is not a cancellation token for the long-running operation itself.

Returns
Type	Description
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
Type	Description
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
Type	Description
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
Name	Description
callSettings	CallSettings Any overriding call settings to apply to the RPC.

Returns
Type	Description
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
Name	Description
callSettings	CallSettings Any overriding call settings to apply to the RPC.

Returns
Type	Description
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
Name	Description
cancellationToken	CancellationToken A cancellation token for the poll operation.

Returns
Type	Description
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
Name	Description
name	String The name of the operation, as returned when it was created. Must not be null.
client	OperationsClient The client to make the RPC call.
callSettings	CallSettings Any overriding call settings to apply to the RPC. May be null, in which case the default settings are used.

Returns
Type	Description
Operation<TResponse, TMetadata>	The current state of the operation identified by name.

PollOnceFromNameAsync(String, OperationsClient, CallSettings)

public static async 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
Name	Description
name	String The name of the operation, as returned when it was created. Must not be null.
client	OperationsClient The client to make the RPC call.
callSettings	CallSettings Any overriding call settings to apply to the RPC. May be null, in which case the default settings are used.

Returns
Type	Description
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
Name	Description
name	String The name of the operation, as returned when it was created. Must not be null.
client	OperationsClient The client to make the RPC call.
cancellationToken	CancellationToken A cancellation token for the "fetch" operation.

Returns
Type	Description
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
Name	Description
pollSettings	PollSettings The settings to use for repeated polling, or null to use the default poll settings (poll once every 10 seconds, forever).
callSettings	CallSettings The call settings to apply on each call, or null for default settings.
metadataCallback	Action<TMetadata> The callback to invoke with the metadata from each poll operation, even if the metadata is null.

Returns
Type	Description
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
Name	Description
pollSettings	PollSettings The settings to use for repeated polling, or null to use the default poll settings (poll once every 10 seconds, forever).
callSettings	CallSettings The call settings to apply on each call, or null for default settings.
metadataCallback	Action<TMetadata> The callback to invoke with the metadata from each poll operation, even if the metadata is null.

Returns
Type	Description
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.