Class KV
Namespace: Consul
Assembly: Consul.dll
KV is used to manipulate the key/value pair API
public class KV : IKVEndpoint
Inheritance
Implements
Inherited Members
object.Equals(object) , object.Equals(object, object) , object.GetHashCode() , object.GetType() , object.MemberwiseClone() , object.ReferenceEquals(object, object) , object.ToString()
Constructors
KV(ConsulClient)
public KV(ConsulClient c)
Parameters
Methods
Acquire(KVPair, CancellationToken)
Acquire is used for a lock acquisition operation. The Key, Flags, Value and Session are respected.
public Task<WriteResult<bool>> Acquire(KVPair p, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the acquisition attempt succeeded
Acquire(KVPair, WriteOptions, CancellationToken)
Acquire is used for a lock acquisition operation. The Key, Flags, Value and Session are respected.
public Task<WriteResult<bool>> Acquire(KVPair p, WriteOptions q, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the acquisition attempt succeeded
CAS(KVPair, CancellationToken)
CAS is used for a Check-And-Set operation. The Key, ModifyIndex, Flags and Value are respected. Returns true on success or false on failures.
public Task<WriteResult<bool>> CAS(KVPair p, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the write attempt succeeded
CAS(KVPair, WriteOptions, CancellationToken)
CAS is used for a Check-And-Set operation. The Key, ModifyIndex, Flags and Value are respected. Returns true on success or false on failures.
public Task<WriteResult<bool>> CAS(KVPair p, WriteOptions q, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the write attempt succeeded
Delete(string, CancellationToken)
Delete is used to delete a single key.
public Task<WriteResult<bool>> Delete(string key, CancellationToken ct = default)
Parameters
key string
The key name to delete
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the delete attempt succeeded
Delete(string, WriteOptions, CancellationToken)
Delete is used to delete a single key.
public Task<WriteResult<bool>> Delete(string key, WriteOptions q, CancellationToken ct = default)
Parameters
key string
The key name to delete
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the delete attempt succeeded
DeleteCAS(KVPair, CancellationToken)
DeleteCAS is used for a Delete Check-And-Set operation. The Key and ModifyIndex are respected. Returns true on success or false on failures.
public Task<WriteResult<bool>> DeleteCAS(KVPair p, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to delete
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the delete attempt succeeded
DeleteCAS(KVPair, WriteOptions, CancellationToken)
DeleteCAS is used for a Delete Check-And-Set operation. The Key and ModifyIndex are respected. Returns true on success or false on failures.
public Task<WriteResult<bool>> DeleteCAS(KVPair p, WriteOptions q, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to delete
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the delete attempt succeeded
DeleteTree(string, CancellationToken)
DeleteTree is used to delete all keys under a prefix
public Task<WriteResult<bool>> DeleteTree(string prefix, CancellationToken ct = default)
Parameters
prefix string
The key prefix to delete from
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the recursive delete attempt succeeded
DeleteTree(string, WriteOptions, CancellationToken)
DeleteTree is used to delete all keys under a prefix
public Task<WriteResult<bool>> DeleteTree(string prefix, WriteOptions q, CancellationToken ct = default)
Parameters
prefix string
The key prefix to delete from
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the recursiv edelete attempt succeeded
Get(string, CancellationToken)
Get is used to lookup a single key
public Task<QueryResult<KVPair>> Get(string key, CancellationToken ct = default)
Parameters
key string
The key name
The cancellation token
Returns
Task <QueryResult <KVPair >>
A query result containing the requested key/value pair, or a query result with a null response if the key does not exist
Get(string, QueryOptions, CancellationToken)
Get is used to lookup a single key
public Task<QueryResult<KVPair>> Get(string key, QueryOptions q, CancellationToken ct = default)
Parameters
key string
The key name
Customized query options
Cancellation token for long poll request. If set, OperationCanceledException will be thrown if the request is cancelled before completing
Returns
Task <QueryResult <KVPair >>
A query result containing the requested key/value pair, or a query result with a null response if the key does not exist
Keys(string, CancellationToken)
Keys is used to list all the keys under a prefix.
public Task<QueryResult<string[]>> Keys(string prefix, CancellationToken ct = default)
Parameters
prefix string
The key prefix to filter on
The cancellation token
Returns
Task <QueryResult <string []>>
A query result containing a list of key names
Keys(string, string, CancellationToken)
Keys is used to list all the keys under a prefix. Optionally, a separator can be used to limit the responses.
public Task<QueryResult<string[]>> Keys(string prefix, string separator, CancellationToken ct = default)
Parameters
prefix string
The key prefix to filter on
separator string
The terminating suffix of the filter - e.g. a separator of "/" and a prefix of "/web/" will match "/web/foo" and "/web/foo/" but not "/web/foo/baz"
The cancellation token
Returns
Task <QueryResult <string []>>
A query result containing a list of key names
Keys(string, string, QueryOptions, CancellationToken)
Keys is used to list all the keys under a prefix. Optionally, a separator can be used to limit the responses.
public Task<QueryResult<string[]>> Keys(string prefix, string separator, QueryOptions q, CancellationToken ct = default)
Parameters
prefix string
The key prefix to filter on
separator string
The terminating suffix of the filter - e.g. a separator of "/" and a prefix of "/web/" will match "/web/foo" and "/web/foo/" but not "/web/foo/baz"
Customized query options
Cancellation token for long poll request. If set, OperationCanceledException will be thrown if the request is cancelled before completing
Returns
Task <QueryResult <string []>>
A query result containing a list of key names
List(string, CancellationToken)
List is used to lookup all keys under a prefix
public Task<QueryResult<KVPair[]>> List(string prefix, CancellationToken ct = default)
Parameters
prefix string
The prefix to search under. Does not have to be a full path - e.g. a prefix of "ab" will find keys "abcd" and "ab11" but not "acdc"
The cancellation token
Returns
Task <QueryResult <KVPair []>>
A query result containing the keys matching the prefix
List(string, QueryOptions, CancellationToken)
List is used to lookup all keys under a prefix
public Task<QueryResult<KVPair[]>> List(string prefix, QueryOptions q, CancellationToken ct = default)
Parameters
prefix string
The prefix to search under. Does not have to be a full path - e.g. a prefix of "ab" will find keys "abcd" and "ab11" but not "acdc"
Customized query options
Cancellation token for long poll request. If set, OperationCanceledException will be thrown if the request is cancelled before completing
Returns
Task <QueryResult <KVPair []>>
Put(KVPair, CancellationToken)
Put is used to write a new value. Only the Key, Flags and Value properties are respected.
public Task<WriteResult<bool>> Put(KVPair p, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the write attempt succeeded
Put(KVPair, WriteOptions, CancellationToken)
Put is used to write a new value. Only the Key, Flags and Value is respected.
public Task<WriteResult<bool>> Put(KVPair p, WriteOptions q, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the write attempt succeeded
Release(KVPair, CancellationToken)
Release is used for a lock release operation. The Key, Flags, Value and Session are respected.
public Task<WriteResult<bool>> Release(KVPair p, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the release attempt succeeded
Release(KVPair, WriteOptions, CancellationToken)
Release is used for a lock release operation. The Key, Flags, Value and Session are respected.
public Task<WriteResult<bool>> Release(KVPair p, WriteOptions q, CancellationToken ct = default)
Parameters
p KVPair
The key/value pair to store in Consul
Customized write options
The cancellation token
Returns
Task <WriteResult <bool >>
A write result indicating if the release attempt succeeded
Txn(List<KVTxnOp>, CancellationToken)
Txn is used to apply multiple KV operations in a single, atomic transaction.
public Task<WriteResult<KVTxnResponse>> Txn(List<KVTxnOp> txn, CancellationToken ct = default)
Parameters
The constructed transaction
A CancellationToken to prematurely end the request
Returns
Task <WriteResult <KVTxnResponse >>
The transaction response
Remarks
Transactions are defined as a list of operations to perform, using the KVOp constants and KVTxnOp structure to define operations. If any operation fails, none of the changes are applied to the state store. Note that this hides the internal raw transaction interface and munges the input and output types into KV-specific ones for ease of use. If there are more non-KV operations in the future we may break out a new transaction API client, but it will be easy to keep this KV-specific variant supported.
Even though this is generally a write operation, we take a QueryOptions input and return a QueryMeta output. If the transaction contains only read ops, then Consul will fast-path it to a different endpoint internally which supports consistency controls, but not blocking. If there are write operations then the request will always be routed through raft and any consistency settings will be ignored.
// If there is a problem making the transaction request then an error will be returned. Otherwise, the ok value will be true if the transaction succeeded or false if it was rolled back. The response is a structured return value which will have the outcome of the transaction. Its Results member will have entries for each operation. Deleted keys will have a nil entry in the, and to save space, the Value of each key in the Results will be nil unless the operation is a KVGet. If the transaction was rolled back, the Errors member will have entries referencing the index of the operation that failed along with an error message.
Txn(List<KVTxnOp>, WriteOptions, CancellationToken)
Txn is used to apply multiple KV operations in a single, atomic transaction.
public Task<WriteResult<KVTxnResponse>> Txn(List<KVTxnOp> txn, WriteOptions q, CancellationToken ct = default)
Parameters
The constructed transaction
Customized write options
A CancellationToken to prematurely end the request
Returns
Task <WriteResult <KVTxnResponse >>
The transaction response
Remarks
Transactions are defined as a list of operations to perform, using the KVOp constants and KVTxnOp structure to define operations. If any operation fails, none of the changes are applied to the state store. Note that this hides the internal raw transaction interface and munges the input and output types into KV-specific ones for ease of use. If there are more non-KV operations in the future we may break out a new transaction API client, but it will be easy to keep this KV-specific variant supported.
Even though this is generally a write operation, we take a QueryOptions input and return a QueryMeta output. If the transaction contains only read ops, then Consul will fast-path it to a different endpoint internally which supports consistency controls, but not blocking. If there are write operations then the request will always be routed through raft and any consistency settings will be ignored.
// If there is a problem making the transaction request then an error will be returned. Otherwise, the ok value will be true if the transaction succeeded or false if it was rolled back. The response is a structured return value which will have the outcome of the transaction. Its Results member will have entries for each operation. Deleted keys will have a nil entry in the, and to save space, the Value of each key in the Results will be nil unless the operation is a KVGet. If the transaction was rolled back, the Errors member will have entries referencing the index of the operation that failed along with an error message.