Connection strings
Experimental. This project is an experiment: the public API, defaults and packaging can change between prereleases, and there is no production support guarantee.
Every container implements IConnectionStringProvider, so you can ask any container for its connection
string without knowing the module type:
IContainer container = new PostgreSqlBuilder().Build();await container.StartAsync();
string connectionString = container.GetConnectionString(); // ConnectionMode.Hoststring same = container.GetConnectionString(ConnectionMode.Host); // explicitConnection modes
Section titled “Connection modes”ConnectionMode describes how the connection string targets the container:
| Mode | Meaning | Support |
|---|---|---|
Host |
Test host → container, using the mapped host port (127.0.0.1:{port}). |
✅ both backends |
Container |
Container → container, using the container network. | ❌ not supported yet |
ConnectionMode.Container throws ConnectionStringModeNotSupportedException in the built-in providers.
Managed networks and aliases are available on both backends, but do not automatically supply a
module-specific container connection string. Construct it from an explicit alias and internal service
port, or provide a custom connection-string provider. Bridge IPs also remain available through
IContainer.NetworkIp — see Networking.
How it works
Section titled “How it works”A module’s builder registers a connection string provider that delegates to the module’s own
GetConnectionString():
sealed class PostgreSqlConnectionStringProvider : ContainerConnectionStringProvider<PostgreSqlContainer, PostgreSqlConfiguration>{ protected override string GetHostConnectionString() => Container.GetConnectionString();}ContainerConnectionStringProvider<TContainer, TConfiguration> is the base class: Configure runs once,
after the container has started (so runtime-assigned ports are available), and dispatches
GetConnectionString(ConnectionMode) to GetHostConnectionString() /
GetContainerConnectionString(). The named overload (GetConnectionString(name, mode)) exists for modules
with several endpoints; the base throws ConnectionStringNameNotSupportedException unless a provider
overrides it.
Custom provider
Section titled “Custom provider”Override the connection string a container exposes with WithConnectionStringProvider:
sealed class ReadOnlyPostgreSql : ContainerConnectionStringProvider<PostgreSqlContainer, PostgreSqlConfiguration>{ protected override string GetHostConnectionString() => $"{Container.GetConnectionString()};ApplicationName=readonly";}
var postgres = new PostgreSqlBuilder() .WithConnectionStringProvider(new ReadOnlyPostgreSql()) .Build();Providers that produce an empty connection string throw ConnectionStringNotAvailableException, and a
provider used before Configure throws ConnectionStringProviderNotConfiguredException.
Module reference
Section titled “Module reference”See Modules for each module’s default connection string and any extra endpoint accessors.