Connection string provider

The connection string provider API provides a standardized way to access and manage connection information for Testcontainers (modules). It allows developers to customize module-provided connection strings or add their own, and to access module-specific connection strings or endpoints (e.g., database connection strings, HTTP API base addresses) in a uniform way.

Note

Testcontainers modules do not yet implement this feature. Developers can use the provider to define and manage their own connection strings or endpoints. Providers will be integrated by modules in future releases.

Example

Register a custom connection string provider via the container builder:

IContainer container = new ContainerBuilder("alpine:3.20.0")
  .WithConnectionStringProvider(() => new MyProvider1())
  .Build();

// Implicit host connection string (default)
var hostConnectionStringImplicit = container.GetConnectionString();

// Explicit host connection string
var hostConnectionStringExplicit = container.GetConnectionString(ConnectionMode.Host);

// Container-to-container connection string
var containerConnectionString = container.GetConnectionString(ConnectionMode.Container);

Implementing a custom provider

To create a custom provider, implement the generic interface: IConnectionStringProvider<TContainer, TConfiguration>. The Configure(TContainer, TConfiguration) method is invoked after the container has successfully started, ensuring that all runtime-assigned values are available.

The builder takes a factory that creates a provider each time a container starts. Pass a delegate, as shown in the example above, or implement the generic interface: IConnectionStringProviderFactory<TContainer, TConfiguration>. Return a new provider on each call. Otherwise, containers built from the same builder share the provider.

Generic BuilderModule Builder

public sealed class MyProvider1 : IConnectionStringProvider<IContainer, IContainerConfiguration>
{
  public void Configure(IContainer container, IContainerConfiguration configuration)
  {
    // Initialize provider with container information.
  }

  public string GetConnectionString(ConnectionMode connectionMode = ConnectionMode.Host)
  {
    // This method returns a default connection string. The connection mode argument
    // lets you choose between a host connection or a container-to-container connection.
    return "...";
  }

  public string GetConnectionString(string name, ConnectionMode connectionMode = ConnectionMode.Host)
  {
    // This method returns a connection string for the given name. Useful for modules
    // with multiple endpoints (e.g., Azurite blob, queue, or table).
    return "...";
  }
}

public sealed class MyProvider2 : IConnectionStringProvider<PostgreSqlContainer, PostgreSqlConfiguration>
{
  private string _host;

  private ushort _port;

  public void Configure(PostgreSqlContainer container, PostgreSqlConfiguration configuration)
  {
    // Initialize provider with container information.
    _host = container.Hostname;
    _port = container.GetMappedPublicPort(PostgreSqlBuilder.PostgreSqlPort);
  }

  public string GetConnectionString(ConnectionMode connectionMode = ConnectionMode.Host)
  {
    return $"Host={_host};Port={_port};...";
  }

  public string GetConnectionString(string name, ConnectionMode connectionMode = ConnectionMode.Host)
  {
    return $"Host={_host};Port={_port};...;SSL Mode=Require";
  }
}