This is a prerelease version.

View latest

.NET Client

API docs
6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

Overview

This section provides information about the .NET client for Hazelcast, and explains how to install and get started with the client.

To learn how to get started quickly with the Hazelcast .NET client, follow the Get started with .NET tutorial.

The official Hazelcast .NET client allows .NET applications to connect to and interact with Hazelcast clusters. The key features and benefits include:

  • Distributed data structures: the client provides access to Hazelcast’s distributed data structures such as maps, queues, topics, and more.

  • SQL support: the client enables you to run SQL queries over distributed data.

  • Near cache: the client supports near cache for faster read speeds. Eventual consistency is also supported.

  • Security features: the client offers SSL support and mutual authentication for enterprise-level security needs.

  • JSON object support: enables you to use and query JSON objects.

  • Zero downtime upgrades: the client supports blue/green failover for zero downtime during upgrades.

  • Scalability: the Hazelcast .NET Client is designed to handle increasing workloads efficiently, making it suitable for large-scale applications.

These features make the Hazelcast .NET Client ideal for .NET applications requiring high-performance, scalable, and distributed data processing capabilities.

For the latest .NET API documentation, see Hazelcast .NET Client docs.

Install the .NET client

This section explains how to download and install the Hazelcast .NET client using the published Hazelcast.Net package from NuGet.

Requirements

The Hazelcast .NET client is distributed as a NuGet package that targets .NET Standard versions .NET 6 and .NET 8. It can therefore be used in any application targetting .NET versions that support these .NET Standard versions:

  • .NET Framework 4.6.2 and 4.8, on Windows

  • .NET Core, on Windows and Linux

For details about the exact versions supported by the client, see Versions.

Distribution

The .NET client is distributed via NuGet as a package named Hazelcast.Net`. It can be installed like any other NuGet package, either via the Visual Studio GUI, or using the package manager:

PM> Install-Package Hazelcast.Net

Or via the .NET CLI:

> dotnet add package Hazelcast.Net

Or manually added to the project as a package reference:

<PackageReference Include="Hazelcast.Net" Version="4.0.0" />
When including the Hazelcast.Net package in a .NET Framework project, note that some binding redirects may be required. For more information, see Binding Redirects.

Use the client

After installing the Hazelcast .NET client, you can begin using it by creating a new client instance and connecting to your Hazelcast cluster. The following shows a minimal example to get you started:

This example connects to a Hazelcast server running on localhost with default settings. You can further configure the client using the HazelcastOptionsBuilder if needed.

1. Create a .NET console project and add the Hazelcast client:

   dotnet new console -n hazelcast-example
   cd hazelcast-example
   dotnet add package Hazelcast.Net

2. Edit your Program.cs file with the following code:

   using System.Threading.Tasks;
   using Hazelcast;

   class Program
   {
       public static async Task Main()
       {
           // Create default options and connect to a Hazelcast server running on localhost
           var options = new HazelcastOptionsBuilder().Build();
           await using var client = await HazelcastClientFactory.StartNewClientAsync(options);

           // Use the client (e.g., get a distributed map)
           var map = await client.GetMapAsync<string, string>("my-distributed-map");
           await map.SetAsync("key", "value");
           var value = await map.GetAsync("key");
           System.Console.WriteLine($"Value for 'key': {value}");

           // Dispose the client when done
           await client.DisposeAsync();
       }
   }

3. Run your application:

   dotnet run

This will connect your .NET application to a Hazelcast cluster and allow you to interact with distributed data structures like maps. For more advanced configuration (e.g. connecting to Hazelcast Cloud, using SSL, or customizing logging), refer to the Getting Started documentation and the code samples.

Next steps

For more information about using the client, see the Hazelcast .NET client GitHub documentation. You can also find code samples for the client in this repo. For the latest .NET API documentation, see Hazelcast .NET Client docs.

lifebuoy

Help and support