Configuration Sources

Configuration follows the Microsoft.Extensions.Configuration patterns. The Hazelcast client configuration is represented by the HazelcastOptions class. When simply instantiated, this class contains the default options (i.e. it does not even read the options file):

var options = new HazelcastOptions();

For failover client, please see the failover documentation.

For anything more realistic though, different approaches are available, as detailed below.

This page does not document the options themselves. Options that can be configured are fully documented on the Options page.

Simple Environment

In a simple, non-hosted environment without dependency injection, options need to be built using the HazelcastOptionsBuilder:

public class Program
{
    public static void Main(string[] args)
    {
        var options = new HazelcastOptionsBuilder.With(args).Build();
    }
}

This will determine the application environment (<env>) from the DOTNET_ENVIRONMENT and ASPNETCORE_ENVIRONMENT variables (or, if not specified, default to Production), and then gather configuration keys from the following ordered sources:

  • Optional default in-memory key/values
  • appsettings.json file
  • appsettings.<env>.json file
  • Environment variables (using double-underscore separator, e.g. hazelcast__clientName)
  • Command line arguments (using colon separator, e.g. hazelcast:clientName)
  • hazelcast.json file
  • hazelcast.<env>.json file
  • Hazelcast-specific environment variables (using dot separator, e.g. hazelcast.clientName)
  • Hazelcast-specific command line arguments (using dot separator, e.g. hazelcast.clientName)
  • Optional in-memory key/values

The Hazelcast-specific sources for environment variables and command line arguments only exist to support the non-standard dot separator, and complement the original sources.

The HazelcastOptionsBuilder provides ways to override the name and location of the hazelcast.json and hazelcast.<env>.json files, the <env> environment name, and accepts optional in-memory key/values.

Every Hazelcast option can therefore be specified via the traditional .NET Core methods. For instance, specifying one cluster server address can be done via the following Json fragment in any of the Json files:

{
    "hazelcast": {
        "networking": {
            "addresses": [ "server:port" ]
        }
    }
}

It can alternatively be specified by setting an environment variable (note that the dotted format may not be supported on every platform):

hazelcast__networking__addresses__0=server:port   ## supported on all platforms
hazelcast:networking:addresses:0=server:port      ## not supported on all platforms
hazelcast.networking.addresses.0=server:port

It can alternatively be specified with command line arguments:

$ myApp hazelcast:networking:addresses:0=server:port
$ myApp hazelcast.networking.addresses.0=server:port

All the .NET Core supported formats are supported (i.e. /arg value, /arg=value, --arg value, etc.). See the documentation for details.

The HazelcastOptionsBuilder supports direct, in-memory key/values (with keys using either the dot or colon separator). There are two types of direct key/values. Default key/values are applied before everything else, and therefore can be overriden by, for instance, the command line, whereas normal key/values are applied after everything else, thus overriding other sources.

var options = new HazelcastOptionsBuilder
    .WithDefault("hazelcast.networking.something", "true")
    .With("hazelcast.networking.addresses.0", "server:port")
    .Build();

The HazelcastOptionsBuilder also supports providing actions that can modify the options via code. These actions will run before, and after, everything that has been described until now:

var options = new HazelcastOptionsBuilder
    .WithDefault(o => o.Networking.Addresses.Clear())
    .With(o => o.Networking.Addresses.Add("127.0.0.1"))
    .Build();

Container Environment

In a container environment, one can rely on dependency injection to manage configuration. An IConfiguration must be created, in order to add Hazelcast to the services:

var configuration = new ConfigurationBuilder()
    // add default configuration (appsettings.json, etc)
    .AddDefaults(args)
    // add Hazelcast-specific configuration
    .AddHazelcast(args)
    .Build();

// create the service collection
var services = new ServiceCollection();

// add Hazelcast-specific services
services.AddHazelcast(configuration);

Configuration keys will be gathered from the same sources and in the same order as before, and options will be registered in the service container, and available via dependency injection:

public class MyService
{
    private readonly HazelcastOptions _options;

    public MyService(IOptions<HazelcastOptions> ioptions)
    {
        _options = ioptions.Value;
    }

    public async Task DoSomethingAsync()
    {
        await using var client = HazelcastClientFactory.StartNewClientAsync(_options);
        // ...
    }
}

Also, the traditional Microsoft Dependency Injection patterns are supported:

services.Configure<HazelcastOptions>(options => 
{
    options.Networking.Addresses.Add("server:port");
});

Note: The required extension methods are not part of the Hazelcast.Net NuGet packages, but are provided as part of the Hazelcast.Net.DependencyInjection project (on NuGet).

Hosted Environment

In a .NET Core hosted environment (see .NET Generic Host), the host supplies the IConfiguration instance, and manages dependency injection. All that is needed is to tell the host how to handle the Hazelcast-specific configuration (e.g. hazelcast.json), and to add Hazelcast to services.

For example:

Host.CreateDefaultBuilder(args)
    .ConfigureHazelcast(args) // configure Hazelcast services
    .ConfigureServices((hostingContext, services) =>
    {
        services.AddHazelcast(hostingContext.Configuration); // register Hazelcast services
    });

Just as with the previous container environment, configuration keys will be gathered from the same sources and in the same order as before, and options will be registered in the service container, and available via dependency injection.

In a typical WebAPI application, this means that the Program class would probably contain code similar to:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureHazelcast(args) // configure Hazelcast services
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>(); 
        });

And the Startup class would probably contain code similar to:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddHazelcast(Configuration); // register Hazelcast services

    // ... add more services ...
}

Note: The required extension methods are not part of the Hazelcast.Net NuGet packages, but are provided as part of the Hazelcast.Net.DependencyInjection project (on NuGet).