Class Operation<TResponse, TMetadata>

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

Inheritance

System.Object

Operation<TResponse, TMetadata>

Inherited Members

System.Object.ToString()

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: Google.LongRunning

Assembly: Google.LongRunning.dll

Syntax

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

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)

Constructs a new instance from the given RPC message.

Declaration

public Operation(Operation rpcMessage, OperationsClient client)

Parameters

Type	Name	Description
Operation	rpcMessage	The RPC message describing the operation. Must not be null.
OperationsClient	client	The client to use for further calls. Must not be null.

Properties

Client

The client to use when making RPCs.

Declaration

public OperationsClient Client { get; }

Property Value

Type	Description
OperationsClient

Exception

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).

Declaration

public OperationFailedException Exception { get; }

Property Value

Type	Description
OperationFailedException

Remarks

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

IsCompleted

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

Declaration

public bool IsCompleted { get; }

Property Value

Type	Description
System.Boolean

Remarks

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

IsFaulted

Whether the operation has completed with a failure.

Declaration

public bool IsFaulted { get; }

Property Value

Type	Description
System.Boolean

Metadata

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

Declaration

public TMetadata Metadata { get; }

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	Condition
System.InvalidOperationException	Metadata is present, but is not of the expected type.

Name

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.

Declaration

public string Name { get; }

Property Value

Type	Description
System.String

Remarks

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

Result

Retrieves the result of the operation, throwing an exception if the operation failed, hasn't completed, or has an unexpected result type. Unlike System.Threading.Tasks.Task`1.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.

Declaration

public TResponse Result { get; }

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

RpcMessage

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.

Declaration

public Operation RpcMessage { get; }

Property Value

Type	Description
Operation

Methods

Cancel(CallSettings)

Attempts to cancel the long-running operation.

Declaration

public void Cancel(CallSettings callSettings = null)

Parameters

Type	Name	Description
CallSettings	callSettings	Any overriding call settings to apply to the RPC.

CancelAsync(CallSettings)

Asynchronously attempts to cancel the long-running operation.

Declaration

public Task CancelAsync(CallSettings callSettings = null)

Parameters

Type	Name	Description
CallSettings	callSettings	Any overriding call settings to apply to the RPC.

Returns

Type	Description
System.Threading.Tasks.Task	A task representing the asynchronous cancel operation.

CancelAsync(CancellationToken)

Asynchronously attempts to cancel the long-running operation.

Declaration

public Task CancelAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.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
System.Threading.Tasks.Task	A task representing the asynchronous cancel operation.

Delete(CallSettings)

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

Declaration

public void Delete(CallSettings callSettings = null)

Parameters

Type	Name	Description
CallSettings	callSettings	Any overriding call settings to apply to the RPC.

DeleteAsync(CallSettings)

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

Declaration

public Task DeleteAsync(CallSettings callSettings = null)

Parameters

Type	Name	Description
CallSettings	callSettings	Any overriding call settings to apply to the RPC.

Returns

Type	Description
System.Threading.Tasks.Task	A task representing the asynchronous deletion operation.

DeleteAsync(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.

Declaration

public Task DeleteAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.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
System.Threading.Tasks.Task	A task representing the asynchronous deletion operation.

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.

Declaration

public TMetadata GetMetadataOrNull()

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()

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.

Declaration

public TResponse GetResultOrNull()

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)

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

Declaration

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

Parameters

Type	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)

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

Declaration

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

Parameters

Type	Name	Description
CallSettings	callSettings	Any overriding call settings to apply to the RPC.

Returns

Type	Description
System.Threading.Tasks.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)

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

Declaration

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

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	A cancellation token for the poll operation.

Returns

Type	Description
System.Threading.Tasks.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)

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

Declaration

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

Parameters

Type	Name	Description
System.String	name	The name of the operation, as returned when it was created. Must not be null.
OperationsClient	client	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)

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

Declaration

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

Parameters

Type	Name	Description
System.String	name	The name of the operation, as returned when it was created. Must not be null.
OperationsClient	client	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
System.Threading.Tasks.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)

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

Declaration

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

Parameters

Type	Name	Description
System.String	name	The name of the operation, as returned when it was created. Must not be null.
OperationsClient	client	The client to make the RPC call.
System.Threading.CancellationToken	cancellationToken	A cancellation token for the "fetch" operation.

Returns

Type	Description
System.Threading.Tasks.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>)

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

Declaration

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

Parameters

Type	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.
System.Action<TMetadata>	metadataCallback	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>)

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

Declaration

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

Parameters

Type	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.
System.Action<TMetadata>	metadataCallback	The callback to invoke with the metadata from each poll operation, even if the metadata is null.

Returns

Type	Description
System.Threading.Tasks.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.