public sealed class Operation<TResponse, TMetadata> where TResponse : class, IMessage<TResponse>, new() where TMetadata : class, IMessage<TMetadata>, new()
Reference documentation and code samples for the Google.LongRunning class Operation
A long-running operation with an associated client, and which knows the expected response type.
Namespace
Google.LongRunningAssembly
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 |
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 |
bool |
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 |
bool |
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 |
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 |
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 |
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. |
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. |
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 |
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 |
TaskOperation |
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 |
TaskOperation |
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 |
The current state of the operation identified by |
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 |
TaskOperation |
A task representing the asynchronous "fetch" operation. The result of the task is
the current state of the operation identified by |
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 |
TaskOperation |
A task representing the asynchronous "fetch" operation. The result of the task is
the current state of the operation identified by |
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 The callback to invoke with the metadata from each poll operation, even if the metadata is null. |
Returns | |
---|---|
Type | Description |
Operation |
The completed operation, which can then be checked for errors or a result. |
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 The callback to invoke with the metadata from each poll operation, even if the metadata is null. |
Returns | |
---|---|
Type | Description |
TaskOperation |
The completed operation, which can then be checked for errors or a result. |
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.