Customize Server Selection

Overview

All MongoDB drivers follow a defined algorithm when selecting a server to read or write from. By using the ClusterConfigurator property of a MongoClient object, you can customize this algorithm to choose the server that works best for your application.

Default Algorithm

When the .NET/C# Driver executes a read operation, it performs the following steps, in order, to select a MongoDB deployment:

1. Selects all servers that match the active read preference from the list of known servers.

2. If at least one readable server exists, the driver calls the user-defined server-selector function and passes in the list from the previous step.

3. Applies the LocalThreshold connection setting to the list of servers returned from the function.

4. Selects a server at random from the servers still on the list and executes the operation against this server.

When the .NET/C# Driver executes a write operation, it begins by selecting all writeable servers, not just those that match the active read preference. The remaining steps are identical.

To learn more about the default server selection algorithm, which the driver follows when you don't specify any custom server selection logic, see Server Selection Algorithm in the MongoDB Server manual.

Specifying Other Server Selection Algorithms

You can specify different server selection logic by passing an instance of a server selector class to the PreServerSelector or PostServerSelector property of the ClusterConfigurator. The PreServerSelector property specifies a server selector that runs before the standard server selection logic runs, while the PostServerSelector property specifies a server selector that runs after standard server selection logic runs. You can then pass your ClusterConfigurator instance to the MongoClientSettings object when you create a MongoClient instance to apply your custom server selection logic.

The following table lists the different types of server selectors you can pass to the ClusterConfigurator property:

The following example instructs a MongoClient to use the RandomServerSelector class to select a server at random before the standard server selection logic runs:

var settings = MongoClientSettings.FromConnectionString("<connection string>");
var clusterConfigurator = builder =>
{
    builder.ConfigureCluster(c =>
        c.With(PreServerSelector: new RandomServerSelector()));
};
settings.ClusterConfigurator = clusterConfigurator;
var client = new MongoClient(settings);

To learn more about the different server selector classes, see the ServerSelectors API documentation.

Implementing Custom Server Selection Logic

You can implement your own custom server selection logic by creating a class that inherits from the IServerSelector interface and overrides the SelectServers() method. The following example shows a simple custom server selection class that selects servers with a ServerType of ServerType.ReplicaSetSecondary:

public class CustomServerSelector : IServerSelector
{
    public IEnumerable<ServerDescription> SelectServers(ClusterDescription cluster,
        IEnumerable<ServerDescription> servers)
    {
        return servers.Where(server => server.Type == ServerType.ReplicaSetSecondary);
    }
}

You can then pass an instance of this class to the PreServerSelector or PostServerSelector property of a ClusterConfigurator instance, as shown in the Specifying Other Server Selection Algorithms section.

Using Settings to Configure Server Selection

You can specify the following server selection settings in your MongoClient object or in your connection URI:

readPreference=primaryPreferred
&maxStalenessSeconds=90
&readPreferenceTags=dc:ny,rack:1

Troubleshooting

A timeout occurred after 30000ms selecting a server using CompositeServerSelector{ Selectors = MongoDB.Driver.MongoClient+AreSessionsSupportedServerSelector, LatencyLimitingServerSelector{ AllowedLatencyRange = 00:00:00.0150000 }, OperationsCountServerSelector }.
Client view of cluster state is
{
    ClusterId : "1",
    Type : "Unknown",
    State : "Disconnected",
    Servers :
    [{
        ServerId: "{ ClusterId : 1, EndPoint : "Unspecified/localhost:27017" }",
        EndPoint: "Unspecified/localhost:27017",
        ReasonChanged: "Heartbeat",
        State: "Disconnected",
        ServerVersion: ,
        TopologyVersion: ,
        Type: "Unknown",
        HeartbeatException: "<exception details>"
    }]
}.

API Documentation

To learn more about the classes and methods used in this guide, see the following API documentation:

• MongoClient

• MongoClientSettings

• ClusterConfigurator

• ServerSelectors

• IServerSelector

• SelectServer()