17 Introduction to Coherence .NET Clients

This chapter describes Coherence for .NET and provides instructions for setting up .NET application to use Coherence for .NET.

This chapter includes the following sections:

17.1 Overview of Coherence for .NET

Coherence for .NET allows .NET applications to access Coherence clustered services, including data, data events, and data processing from outside the Coherence cluster. Typical uses of Coherence for .NET include desktop and web applications that require access to Coherence caches. For details about installing the .NET client distribution, see Installing Oracle Coherence.

Coherence for .NET consists of a lightweight .NET library that connects to a Coherence*Extend clustered service instance running within the Coherence cluster using a high performance TCP/IP-based communication layer. This library sends all client requests to the Coherence*Extend clustered service which, in turn, responds to client requests by delegating to an actual Coherence clustered service (for example, a Partitioned or Replicated cache service).

An INamedCache instance is retrieved by using the CacheFactory.GetCache(...) API call. After it is obtained, a client accesses the INamedCache in the same way as it would if it were part of the Coherence cluster. The fact that INamedCache operations are being sent to a remote cluster node (over TCP/IP) is completely transparent to the client application.

17.2 Configuration and Usage for .NET Clients

This section includes instructions for setting up .NET applications to use Coherence. This section includes the following topics:

17.2.1 General Instructions

Configuring and using Coherence for .NET requires the following steps:

  1. Configuring Coherence*Extend for .NET

  2. Building Integration Objects (.NET) (See also Developing Applications with Oracle Coherence)

  3. Using the Coherence .NET APIs

  4. Starting a Proxy Server

  5. Launching the .NET client application

17.2.2 Configuring Coherence*Extend for .NET

For details on configuring Coherence*Extend, refer to:

Coherence for .NET clients must use a specific XML schema for the Coherence cache configuration file. Make sure the cache configuration file uses the following schema:

<cache-config xmlns="http://schemas.tangosol.com/cache"

17.2.3 Obtaining a Cache Reference with .NET

A reference to a configured cache can be obtained by name by using the CacheFactory class:

INamedCache cache = CacheFactory.GetCache("example-local-cache");

17.2.4 Cleaning Up Resources Associated with a Cache

Instances of all INamedCache implementations, including LocalCache, should be explicitly released by calling the INamedCache.Release() method when they are no longer needed, to free up any resources they might hold.

If the particular INamedCache is used for the duration of the application, then the resources are cleaned up when the application is shut down or otherwise stops. However, if it is only used for a period, the application should call its Release() method when finished using it.

Alternatively, you can leverage the fact that INamedCache extends IDisposable and that all cache implementations delegate a call to IDisposable.Dispose() to INamedCache.Release(). If you want to obtain and release a cache instance within a single method, you can do so with a using block:

using (INamedCache cache = CacheFactory.GetCache("my-cache"))
   // use cache as usual

After the using block terminates, IDisposable.Dispose() is called on the INamedCache instance, and all resources associated with it are released.

17.2.5 Using Network Filters

A network filter is a mechanism that allows transformation of data sent through TCP/IP sockets to be performed in a pluggable, layered fashion. Coherence for .NET supports custom filters, thus enabling users to modify the contents of the network traffic and is commonly used to add compression and encryption to data.

This section includes the following topics: Custom Filters

To create a filter, create a .NET class that implements the Tangosol.IO.IWrapperStreamFactory interface and optionally implements the Tangosol.Util.IXmlConfigurable interface. The IWrapperStreamFactory interface defines two methods:

Stream GetInputStream(Stream stream);
Stream GetOutputStream(Stream stream);

that provide the I/O stream to be wrapped ("filtered") (on input—received message, or output—sending message) and expects a stream back that wraps the original stream. This method is called for each incoming and outgoing message. Configuring Filters

There are two steps to configuring a filter. The first is to declare the filter in the <filters> XML element in an operational override file. For more information on configuring filters, see the Developing Applications with Oracle Coherence.

         <filter-class>Tangosol.Net.CompressionFilter, Coherence</filter-class>


GZip compression filter is supported in .NET framework version 2.0 or higher.

The second step is to attach the filter to one or more specific services. To specify the filter for a specific service, for example the ExtendTcpCacheService service, add a <filter-name> element to the <use-filters> element of the service declaration in the cache configuration file.


If the filter implements IXmlConfigurable, after instantiating the filter, Coherence sets the Config property with the following XML element: