SFKV

A fast and reliable remote key-value store for Microsoft Service Fabric via service remoting.

• SFKV is designed as a standalone application / service that can run on a Service Fabric cluster along with your applications / services.
• SFKV is able to reliably store your state as key-value pair.
• SFKV supports sharding up to 10 partitions.
• SFKV is using native service fabric state manager and it is strong-consistent.
• SFKV supports read on secondary replicas.

Getting Started

• Deploy SFKV to your Service Fabric cluster.
• Add SFKV.Contracts NuGet package to your service from https://www.nuget.org/packages/SFKV.Contracts.
• Use SFKV by creating a client proxy instance of SFKV.Contracts.IStore. Please read through for more details.

Usage

You can create the client proxy of SFKV.Contracts.IStore instance by using the ServiceProxy class.

var storePrimary = ServiceProxy.Create<IStore>(
    new Uri("fabric:/SFKV/SFKV.Store"), 
    new ServicePartitionKey(0), 
    TargetReplicaSelector.PrimaryReplica);
    
await storePrimary.StringSetAsync("key", "value");
var val = await storePrimary.StringGetAsync("key");

The ServiceProxy.Create method takes 3 arguments, and also 1 optional argument that we did not use for now.

Argument Name	Type	Description
serviceUri	Uri	This is the Service Fabric namespace for SFKV that is registered to the naming service when the service is started. If you didn't make any changes to the service manifest. the name of the service should be fabric:/SFKV/SFKV.Store. Behind the scenes, The ServiceProxy class will ask the naming service for the actual service endpoint.
partitionKey	ServicePartitionKey	This is the partition key which the data will be set or get. You can use up to 10 partitions by using 0 to 9 keys. How the data is sharded is the client's responsibility, so you should plan your data partitioning strategy before hand. For example you can use some kind of hashing algorithm that is uniformed and deterministic and modulo it by 10.
targetReplicaSelector	TargetReplicaSelector	This is an enum which you can use to select which replica that the service proxy client will target. For more information please refer to the following documentation.

Data Types

String

TODO

Int

TODO

Hash

TODO

List

TODO

Set

TODO

Service Interface #

• IStore
  • HashDeleteAsync(key)
  • HashExistsAsync(key)
  • HashGetAllAsync(key)
  • HashGetAsync(key,field)
  • HashMultipleGetAsync(key,fields)
  • HashMultipleSetAsync(key,keyValuePairs)
  • HashSetAsync(key,keyValuePair)
  • IntDeleteAsync(key)
  • IntExistsAsync(key)
  • IntGetAsync(key)
  • IntIncrAsync(key)
  • IntIncrByAsync(key,incrBy)
  • IntMultipleSetAsync(keyValuePairs)
  • IntSetAsync(key,value)
  • ListAddFirstAsync(key,value)
  • ListAddLastAsync(key,value)
  • ListAddMultipleFirstAsync(key,values)
  • ListAddMultipleLastAsync(key,values)
  • ListDeleteAsync(key)
  • ListExistsAsync(key)
  • ListPopFirstAsync(key)
  • ListPopLastAsync(key)
  • ListRangeAsync(key,firstIndex,lastIndex)
  • SetAddAsync(key,value)
  • SetAddMultipleAsync(key,values)
  • SetContainsAsync(key,value)
  • SetCountAsync(key)
  • SetDeleteAsync(key)
  • SetExistsAsync(key)
  • SetGetAllAsync(key)
  • SetGetAsync(key,count)
  • SetRemoveAsync(key,value)
  • SetRemoveMultipleAsync(key,values)
  • StringAppendAsync(key,value)
  • StringDeleteAsync(key)
  • StringExistsAsync(key)
  • StringGetAsync(key)
  • StringMultipleSetAsync(keyValuePairs)
  • StringSetAsync(key,value)

SFKV.Contracts # =

IStore # =

Namespace

SFKV.Contracts

Summary

The service remoting interface for SFKV storage service.

HashDeleteAsync(key) method # =

Summary

Delete the specified key and its value from the store.

Returns

Returns a boolean indicating the key value pair is removed from the store.

Parameters

Name	Type	Description
key	System.String	The key.

HashExistsAsync(key) method # =

Summary

Check whether the specified key exists on the store.

Returns

Returns a boolean indicating the key existence.

Parameters

Name	Type	Description
key	System.String	The key.

HashGetAllAsync(key) method # =

Summary

Get the hash.

Returns

Returns the hash.

Parameters

Name	Type	Description
key	System.String	The hash key.

HashGetAsync(key,field) method # =

Summary

Get the value of a hash field.

Returns

Returns the value of the hash field.

Parameters

Name	Type	Description
key	System.String	The hash key.
field	System.String	The hash field.

HashMultipleGetAsync(key,fields) method # =

Summary

Get the values of multiple hash fields.

Returns

Returns the values of the multiple hash fields. Returns empty value if the field is not found.

Parameters

Name	Type	Description
key	System.String	The hash key.
fields	System.String[]	The hash fields.

HashMultipleSetAsync(key,keyValuePairs) method # =

Summary

Set multiple hash field and value pairs.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The hash key.
keyValuePairs	System.Collections.Generic.KeyValuePair{System.String,System.String}[]	Multiple hash field and value pairs.

HashSetAsync(key,keyValuePair) method # =

Summary

Set the hash field and value pair.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The hash key.
keyValuePair	System.Collections.Generic.KeyValuePair{System.String,System.String}	The hash field and value pair.

IntDeleteAsync(key) method # =

Summary

Delete the specified key and its value from the store.

Returns

Returns a boolean indicating the key value pair is removed from the store.

Parameters

Name	Type	Description
key	System.String	The key.

IntExistsAsync(key) method # =

Summary

Check whether the specified key exists on the store.

Returns

Returns a boolean indicating the key existence.

Parameters

Name	Type	Description
key	System.String	The key.

IntGetAsync(key) method # =

Summary

Get the integer value based on the key from the store.

Returns

Returns the integer value for the key.

Parameters

Name	Type	Description
key	System.String	The key.

IntIncrAsync(key) method # =

Summary

Increment the integer value by 1.

Returns

Returns the incremented value.

Parameters

Name	Type	Description
key	System.String	The key.

IntIncrByAsync(key,incrBy) method # =

Summary

Increment the integer value with specified number.

Returns

Returns the incremented value.

Parameters

Name	Type	Description
key	System.String	The key.
incrBy	System.Int32	The number which will be incremented to value.

IntMultipleSetAsync(keyValuePairs) method # =

Summary

Add or update multiple key and integer value pairs to the store.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
keyValuePairs	System.Collections.Generic.KeyValuePair{System.String,System.Int32}[]	The key and integer value pairs.

IntSetAsync(key,value) method # =

Summary

Add or update a key and integer value pair to the store.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.Int32	The integer value.

ListAddFirstAsync(key,value) method # =

Summary

Add the value at the first position of the list.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value.

ListAddLastAsync(key,value) method # =

Summary

Add the value at the last position of the list.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value.

ListAddMultipleFirstAsync(key,values) method # =

Summary

Add multiple values at the first position of the list.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
values	System.String[]	The values.

ListAddMultipleLastAsync(key,values) method # =

Summary

Add multiple values at the last position of the list.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
values	System.String[]	The values.

ListDeleteAsync(key) method # =

Summary

Delete the specified key and its value from the store.

Returns

Returns a boolean indicating the key value pair is removed from the store.

Parameters

Name	Type	Description
key	System.String	The key.

ListExistsAsync(key) method # =

Summary

Check whether the specified key exists on the store.

Returns

Returns a boolean indicating the key existence.

Parameters

Name	Type	Description
key	System.String	The key.

ListPopFirstAsync(key) method # =

Summary

Remove and return the first value of the list.

Returns

Returns the first value of the list.

Parameters

Name	Type	Description
key	System.String	The key.

ListPopLastAsync(key) method # =

Summary

Remove and return the last value of the list.

Returns

Returns the last value of the list.

Parameters

Name	Type	Description
key	System.String	The key.

ListRangeAsync(key,firstIndex,lastIndex) method # =

Summary

List the values by its index position.

Returns

Returns the list of values.

Parameters

Name	Type	Description
key	System.String	The key.
firstIndex	System.Int32	The first index of the value range.
lastIndex	System.Int32	The last index of the value range. If less than 0 is specified, will return the values until the end of the list.

SetAddAsync(key,value) method # =

Summary

Add a value into the set.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value.

SetAddMultipleAsync(key,values) method # =

Summary

Add multiple values into the set.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
values	System.String[]	The value.

SetContainsAsync(key,value) method # =

Summary

Check whether the value is a member of the set.

Returns

Returns a boolean indicating whether the value is a member of the set.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value.

SetCountAsync(key) method # =

Summary

Get the number of elements in a set.

Returns

Returns the number of elements in a set.

Parameters

Name	Type	Description
key	System.String	The key.

SetDeleteAsync(key) method # =

Summary

Delete the specified key and its value from the store.

Returns

Returns a boolean indicating the key value pair is removed from the store.

Parameters

Name	Type	Description
key	System.String	The key.

SetExistsAsync(key) method # =

Summary

Check whether the specified key exists on the store.

Returns

Returns a boolean indicating the key existence.

Parameters

Name	Type	Description
key	System.String	The key.

SetGetAllAsync(key) method # =

Summary

Get all values in a set.

Returns

Returns all values in a set.

Parameters

Name	Type	Description
key	System.String	The key.

SetGetAsync(key,count) method # =

Summary

Get specified number of values in a set.

Returns

Returns the values in the specified set.

Parameters

Name	Type	Description
key	System.String	The key.
count	System.Int32	The number of values to be retrieved.

SetRemoveAsync(key,value) method # =

Summary

Remove a value from the set.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value.

SetRemoveMultipleAsync(key,values) method # =

Summary

Remove multiple values from the set.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
values	System.String[]	The values.

StringAppendAsync(key,value) method # =

Summary

Append the value at the end of existing string if exists. Otherwise the string will be created.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value which will be appended.

StringDeleteAsync(key) method # =

Summary

Delete the specified key and its value from the store.

Returns

Returns a boolean indicating the key value pair is removed from the store.

Parameters

Name	Type	Description
key	System.String	The key.

StringExistsAsync(key) method # =

Summary

Check whether the specified key exists on the store.

Returns

Returns a boolean indicating the key existence.

Parameters

Name	Type	Description
key	System.String	The key.

StringGetAsync(key) method # =

Summary

Get the value based on the key from the store.

Returns

Returns the value for the key.

Parameters

Name	Type	Description
key	System.String	The key.

StringMultipleSetAsync(keyValuePairs) method # =

Summary

Add or update multiple key value pairs to the store.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
keyValuePairs	System.Collections.Generic.KeyValuePair{System.String,System.String}[]	The key value pairs.

StringSetAsync(key,value) method # =

Summary

Add or update a key value pair to the store.

Returns

Returns awaitable task.

Parameters

Name	Type	Description
key	System.String	The key.
value	System.String	The value.

Releases

TODO

Deployment

You can deploy SFKV to your Service Fabric Cluster using powershell like usual. Below is the example of deploying SFKV to Service Fabric using a Client Certificate.

$ErrorActionPreference = "STOP";

# Variables
$endpoint = 'your.cluster.endpoint:19000'
$thumbprint = 'YOURCERTTHUMBPRINT'
$packagepath = 'C:\Your\ApplicationPackagePath'
$applicationTypeVersion = 'Application.Type.Version';

# Connect to the cluster using a client certificate.
Connect-ServiceFabricCluster -ConnectionEndpoint $endpoint `
          -KeepAliveIntervalInSec 10 `
          -X509Credential -ServerCertThumbprint $thumbprint `
          -FindType FindByThumbprint -FindValue $thumbprint `
          -StoreLocation CurrentUser -StoreName My

# Copy the application package to the cluster image store.
Copy-ServiceFabricApplicationPackage $packagepath -ImageStoreConnectionString fabric:ImageStore -ApplicationPackagePathInImageStore SFKV

# Register the application type.
Register-ServiceFabricApplicationType -ApplicationPathInImageStore SFKV

# Remove the application package to free system resources.
Remove-ServiceFabricApplicationPackage -ImageStoreConnectionString fabric:ImageStore -ApplicationPackagePathInImageStore SFKV

# Create the application instance.
New-ServiceFabricApplication -ApplicationName fabric:/SFKV -ApplicationTypeName SFKVType -ApplicationTypeVersion $applicationTypeVersion