Class Operation<TResponse, TMetadata> (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 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

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.

Class Operation<TResponse, TMetadata> (2.2.0)

Inheritance

Inherited Members

Namespace

Assembly

Type Parameters

Remarks

Constructors

Operation(Operation, OperationsClient)

Properties

Client

Exception

IsCompleted

IsFaulted

Metadata

Name

Result

RpcMessage

Methods

Cancel(CallSettings)

CancelAsync(CallSettings)

CancelAsync(CancellationToken)

Delete(CallSettings)

DeleteAsync(CallSettings)

DeleteAsync(CancellationToken)

GetMetadataOrNull()

GetResultOrNull()

PollOnce(CallSettings)

PollOnceAsync(CallSettings)

PollOnceAsync(CancellationToken)

PollOnceFromName(String, OperationsClient, CallSettings)

PollOnceFromNameAsync(String, OperationsClient, CallSettings)

PollOnceFromNameAsync(String, OperationsClient, CancellationToken)

PollUntilCompleted(PollSettings, CallSettings, Action<TMetadata>)

PollUntilCompletedAsync(PollSettings, CallSettings, Action<TMetadata>)