ConfigFromJson

The entire cluster setup — cluster settings, agent connections, workers — can be driven from JSON instead of code, via ConfigFromJson. Useful for environment-specific configuration (e.g. different agent connections per deployment) without recompiling.

Usage

Three overloads cover the common sources:

// From an IConfiguration section (e.g. appsettings.json)
config.ConfigFromJson(builder.Configuration.GetSection("JobMaster:Cluster"));

// From a raw JSON string, or a path to a .json file — detected automatically
config.ConfigFromJson("cluster-config.json");
config.ConfigFromJson("""{ "clusterId": "payroll-cluster", ... }""");

// From a Stream — e.g. an embedded resource
config.ConfigFromJson(embeddedResourceStream);

Property names are matched case-insensitively, so clusterId and ClusterId both work.

Example

{
  "clusterId": "payroll-cluster",
  "default": true,
  "mode": "Active",
  "repoType": "Postgres",
  "connectionString": "Host=db.internal;Database=jobmaster_payroll;...",
  "transientThreshold": "00:20:00",
  "defaultJobTimeout": "00:01:00",
  "defaultMaxRetryCount": 3,
  "maxMessageByteSize": 262144,
  "ianaTimeZoneId": "America/Sao_Paulo",
  "dataRetentionTtl": "30.00:00:00",
  "targetArchivedClusterId": "payroll-archive",
  "disabledPriorities": ["VeryLow", "Low"],
  "agentConnections": [
    {
      "name": "agent-1",
      "repositoryType": "Postgres",
      "connectionString": "Host=db.internal;Database=jobmaster_agent;...",
      "protectConnectionChanges": true
    }
  ],
  "workers": [
    {
      "workerName": "worker-1",
      "agentConnectionName": "agent-1",
      "transferBatchSize": 1000,
      "bucketBufferSize": 250,
      "workerMode": "Full",
      "bucketQtyConfig": { "High": 4, "Medium": 2 }
    }
  ]
}

TimeSpan fields (transientThreshold, defaultJobTimeout, dataRetentionTtl) use the standard .NET TimeSpan string format ("d.hh:mm:ss").

Field reference

Field	Maps to
clusterId	ClusterId(...)
default	SetAsDefault() when true
standalone	Routes through UseStandaloneCluster() — see Standalone below
mode	Mode(ClusterMode) — "Active", "Migrating", or "Archived"
repoType / connectionString	Master DB connection
connectionOptions	Provider-specific master-connection options — see Provider-specific settings below.
transientThreshold, defaultJobTimeout, defaultMaxRetryCount, maxMessageByteSize, ianaTimeZoneId	Same as the fluent selector — see Cluster Configuration
dataRetentionTtl / targetArchivedClusterId	DataRetentionTtl(ttl, targetArchivedClusterId) — see Archiving
targetActiveClusterId	Set automatically when mode is "Migrating" — see Migrating a Cluster. Setting it directly without mode: "Migrating" throws at startup.
disabledPriorities	DisablePriority(...) per entry — "VeryLow", "Low", "High", "Critical" ("Medium" can't be disabled)
agentConnections[]	One AddAgentConnectionConfig(...) per entry
workers[]	One AddWorker(...) per entry

agentConnections[]: name, repositoryType, connectionString, protectConnectionChanges, connectionOptions (see below).

workers[]: workerName, agentConnectionName, workerLane, transferBatchSize, bucketBufferSize, workerMode ("Full", "Coordinator", "Execution", "Drain"), parallelismFactor, skipWarmUpTime, bucketQtyConfig (map of priority name → bucket count).

Provider-specific settings

Some connectionOptions properties are specific to each provider.

For example, the NATS JetStream provider accepts auth keys (username, password, token, credentialsFile, nkey, jwt) and TLS keys (tlsCertBundleFile, tlsCertBundleFilePassword, tlsCaFile, tlsInsecureSkipVerify, tlsMode) on agent connections — see the NATS provider guide for details. NATS JetStream can only be used for agent (transport) connections, not as a cluster's master repository.

The SQL providers (Postgres, MySQL, SQL Server) accept tablePrefix on both master and agent connections — see Table prefix for details. DisableAutoProvisionSqlSchema has no JSON equivalent yet; it's cluster-wide and configured through the fluent API only.

The RavenDB provider accepts certificateFile/certificatePassword (client-certificate auth), requestTimeoutMs/pooledConnectionLifetimeMs/pooledConnectionIdleTimeoutMs (HTTP tuning), and collectionPrefix on both master and agent connections, plus enableDocumentExpiration/documentExpirationFrequencySeconds on master connections only — see the RavenDB provider guide for details. Setting a master-only key on an agent connection throws at startup.

Standalone clusters

When standalone: true, only workerName and transferBatchSize apply per worker — IClusterStandaloneConfigSelector.AddWorker has no standalone equivalent of workerLane, parallelismFactor, skipWarmUpTime, workerMode, bucketQtyConfig, or the cluster-level connectionOptions, so those fields are silently ignored, same as configuring a standalone cluster through the fluent API. See Getting Started for the standalone fluent equivalent.