API Concepts

ScaleOut Software NamedCache API

ScaleOut StateServer® is a distributed software service that runs on multiple servers in a farm to store data objects in memory. Once objects are stored in the ScaleOut StateServer service, they are globally accessible across the farm and to remote client applications. This reference guide covers the .NET APIs that can be used to work with objects in a distributed ScaleOut StateServer object store.

This API guide assumes that you have successfully installed and configured ScaleOut StateServer on one or more host machines or remote clients. For more information on the ScaleOut StateServer service, consult the main SOSS Help file that is installed with the product or visit the Product Documentation page on the ScaleOut Software web site.

This topic contains the following sections:

This topic covers the initial steps of configuring your .NET projects to use the ScaleOut APIs and offers guidance to help you select which API to use.

Configuring and Deploying Your .NET Project

To use ScaleOut StateServer's Named Cache API in your application, your project will need to reference the soss_namedcache and soss_svcdotnet assemblies that are shipped with the product. Multiple versions of these assemblies are installed on your system in order to support different versions of the .NET runtime; use the following table to determine which versions of the assemblies to reference (the indicated DOTNETx.x directories can be found under the product's installation directory, which is typically located at C:\Program Files\ScaleOut_Software\StateServer\):

Targeted .NET runtime

soss_namedcache reference

soss_svcdotnet reference



















Copies of these assemblies are also installed in your system's Global Assembly Cache (GAC), so it is not necessary (nor is it recommended) for you to manually deploy copies the ScaleOut assemblies when deploying your application. For example, you should avoid deploying soss_namedcache.dll and soss_svcdotnet.dll to the bin directory of a web application. Allowing your project to load these assemblies from the GAC at runtime will make future upgrades of these ScaleOut components more straightforward and reliable.

Selecting an API

ScaleOut StateServer offers the choice of two .NET APIs to access objects in your distributed data grid. The NamedCache API is feature-rich and allows you to work with your objects using typical .NET collection syntax. The NamedMap API is optimized to efficiently store very large numbers of objects that will be subjected to frequent analysis.


The NamedCache class provides a collection-based API suitable for caching a group of objects within a single, named cache. The class represents a collection of objects in the distributed data grid, and it allows you to work with your objects using familiar .NET collection syntax. A number of advanced caching features are also available to your application, both at the cache level using the NamedCache class and at the individual object level using the CreatePolicy class, including:

  • Timeouts and expirations

  • Optimistic or pessimistic locking

  • Object dependencies

  • Queries

  • Parallel Method Invocation (PMI)

  • Invocation Grid

  • Custom Serialization

  • Backing Store Integration

  • GeoServer Replication

  • Lightweight Authorization

  • Local Client-Side Caching

  • Low-Memory Eviction


Introduced in version 5.2, the NamedMap API's purpose is to efficiently store large numbers of objects (typically millions) in the distributed data grid in such a way that they can be analyzed in bulk very efficiently.

Objects that are in a NamedMap are stored with minimal overhead and at much higher densities in the ScaleOut StateServer service than objects that are stored using the traditional NamedCache API. This allows much higher numbers of objects to be stored in memory and enables faster parallel access in your application. Since internal object metadata is minimized for NamedMap objects, individual objects do not have the same rich features that are available in the NamedCache API (for example, objects stored in a NamedMap may not use timeouts, dependencies, backing store integration, or GeoServer replication).

The NamedMap semantics closely follow that of the ConcurrentDictionary collection class in Microsoft's System.Collections.Concurrent namespace, so it is intended to be used by multiple threads that are performing concurrent analysis of objects in the map.

Most applications that need to perform traditional caching operations will want to use the NamedCache with its extensive feature set. However, if your workload requires frequent analysis of large numbers of small objects then the NamedMap can provide faster and more efficient storage of your object data.