DocumentDBBuilderExtensions Methods
Hosting.IDistributedApplicationBuilder. AddDatabase(IResourceBuilder<DocumentDBServerResource>, string, string?)Section titled AddDatabase(IResourceBuilder<DocumentDBServerResource>, string, string?)extensionIResourceBuilder<DocumentDBDatabaseResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBDatabaseResource> AddDatabase( this IResourceBuilder<DocumentDBServerResource> builder, string name, string? databaseName = null) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The DocumentDB server resource builder.namestringThe name of the resource. This name will be used as the connection string name when referenced in a dependency.databaseNamestring?optionalThe name of the database. If not provided, this defaults to the same value as name.Returns
IResourceBuilder<DocumentDBDatabaseResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
.WithReference(db). This resource includes a built-in health check. When this resource is referenced as a dependency using the ResourceBuilderExtensions.WaitFor extension method then the dependent resource will wait until the DocumentDB database responds to ping. Examples
var server = builder.AddDocumentDB("documentdb");var ordersDb = server.AddDatabase("orders");var usersDb = server.AddDatabase("users");AddDocumentDB(IDistributedApplicationBuilder, string, int?)Section titled AddDocumentDB(IDistributedApplicationBuilder, string, int?)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> AddDocumentDB( this IDistributedApplicationBuilder builder, string name, int? port) { // ... }}Parameters
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder.namestringThe name of the resource. This name will be used as the connection string name when referenced in a dependency.portint?The host port for DocumentDB.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
ResourceBuilderExtensions.WaitFor extension method then the dependent resource will wait until the DocumentDB server responds to ping. This version of the package defaults to the tag of the container image. Examples
var server = builder.AddDocumentDB("documentdb", port: 10260);AddDocumentDB(IDistributedApplicationBuilder, string, int?, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>)Section titled AddDocumentDB(IDistributedApplicationBuilder, string, int?, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> AddDocumentDB( this IDistributedApplicationBuilder builder, string name, int? port = null, IResourceBuilder<ParameterResource>? userName = null, IResourceBuilder<ParameterResource>? password = null) { // ... }}Parameters
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder.namestringThe name of the resource. This name will be used as the connection string name when referenced in a dependency.portint?optionalThe host port for DocumentDB.userNameIResourceBuilder<ParameterResource>optionalA parameter that contains the DocumentDB server user name, or null to use a default value.passwordIResourceBuilder<ParameterResource>optionalA parameter that contains the DocumentDB server password, or null to use a generated password.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Examples
// Minimal usage with generated credentials:var server = builder.AddDocumentDB("documentdb");var database = server.AddDatabase("mydb");
// With custom credentials:var user = builder.AddParameter("db-user");var pass = builder.AddParameter("db-pass", secret: true);var securedServer = builder.AddDocumentDB("documentdb", userName: user, password: pass);AllowInsecureTls(IResourceBuilder<DocumentDBServerResource>, bool)Section titled AllowInsecureTls(IResourceBuilder<DocumentDBServerResource>, bool)extensionIResourceBuilder<DocumentDBServerResource>tlsInsecure=true to the connection string. This is enabled by default so the .NET MongoDB driver can connect to the self-signed certificate used by the DocumentDB Local container. Call AllowInsecureTls(false) to require valid certificates. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> AllowInsecureTls( this IResourceBuilder<DocumentDBServerResource> builder, bool allowInsecureTls = true) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.allowInsecureTlsbooloptionalWhether to allow insecure TLS. Defaults to true.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
tlsInsecure=true rather than tlsAllowInvalidCertificates=true because the .NET MongoDB driver does not fully honor tlsAllowInvalidCertificates for self-signed certificates and raises UntrustedRoot errors. Examples
// Require valid certificates (for example, production with real certs):var server = builder.AddDocumentDB("documentdb") .AllowInsecureTls(false);UseTls(IResourceBuilder<DocumentDBServerResource>, bool)Section titled UseTls(IResourceBuilder<DocumentDBServerResource>, bool)extensionIResourceBuilder<DocumentDBServerResource>UseTls(false) to disable TLS if connecting to a non-TLS endpoint. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> UseTls( this IResourceBuilder<DocumentDBServerResource> builder, bool useTls = true) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.useTlsbooloptionalWhether to enable TLS. Defaults to true.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
0.114.0 the container's default TLS_MODE=allowTLS accepts both plain and TLS connections, so UseTls(false) works against the default image. Container images up to and including 0.113.0 rejected plain connections regardless of that setting. Set .WithEnvironment("TLS_MODE", "requireTLS") to make the container reject plain connections; combining that with UseTls(false) is self-contradictory and connections will fail. Examples
// Disable TLS for a non-TLS endpoint:var server = builder.AddDocumentDB("documentdb") .UseTls(false);WithDataBindMount(IResourceBuilder<DocumentDBServerResource>, string, bool)Section titled WithDataBindMount(IResourceBuilder<DocumentDBServerResource>, string, bool)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithDataBindMount( this IResourceBuilder<DocumentDBServerResource> builder, string source, bool isReadOnly = false) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder.sourcestringThe source directory on the host to mount into the container.isReadOnlybooloptionalUnsupported. DocumentDB requires a writable data directory; passing true throws.Returns
IResourceBuilder<DocumentDBServerResource>The ApplicationModel.IResourceBuilder`1.Exceptions
ArgumentExceptionisReadOnly is true.Remarks
Prefer DocumentDBBuilderExtensions.WithDataVolume for most cases. Bind mounts are useful when you need direct access to the data files on the host filesystem, but the host directory has to be writable by the container's documentdb runtime user, which the entrypoint enforces by taking ownership of the directory's contents.
The bare DocumentDB container defaults DATA_PATH to /data. This helper mounts the directory at /data — the container default, and the path DocumentDB v0.116-0 and later declare as an image volume, so no anonymous volume is created — and sets DATA_PATH to the same value so DocumentDB writes to the mounted directory. On those images the directory is also claimed with an exclusive flock and can back only one running container at a time.
Point the mount at a directory that is empty or holds an existing DocumentDB cluster. A directory that contains anything else (a stray .gitkeep or .DS_Store is enough) is refused, not cleaned: the container logs Directory /data exists but doesn't
appear to contain a valid PostgreSQL data directory, never starts PostgreSQL, and exits non-zero a minute later behind the "PostgreSQL failed to start within 60 seconds" banner.
isReadOnly is rejected: PostgreSQL cannot initialise or run against a read-only data directory, and the container would otherwise spend a minute failing with a misleading "PostgreSQL failed to start within 60 seconds" banner.
A bind mount only carries a PostgreSQL data directory on a container runtime that applies ownership changes to the mounted host path immediately. PostgreSQL refuses to start unless the data directory is already owned by the user starting the postmaster, and the container entrypoint establishes that by running chown on DATA_PATH milliseconds before starting it. Docker Desktop applies that chown asynchronously — measured on macOS with VirtioFS, and expected on its Windows and Linux hosts, which share the same file-sharing design — so the postmaster reads the previous owner and aborts with data directory "/data" has wrong ownership. A first run hides this behind the seconds initdb spends between the two steps, so the container comes up once and then fails every restart, with the data intact on the host but unreadable. Nothing in the application model can order that runtime's chown; use DocumentDBBuilderExtensions.WithDataVolume there, whose storage lives inside the runtime's own filesystem and is unaffected. A bind mount on a native container engine is an ordinary mount and restarts normally.
Examples
var server = builder.AddDocumentDB("documentdb") .WithDataBindMount("./data/documentdb");WithDataVolume(IResourceBuilder<DocumentDBServerResource>, string?, bool, string?)Section titled WithDataVolume(IResourceBuilder<DocumentDBServerResource>, string?, bool, string?)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithDataVolume( this IResourceBuilder<DocumentDBServerResource> builder, string? name = null, bool isReadOnly = false, string? targetPath = null) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder.namestring?optionalThe name of the volume. Defaults to an auto-generated name based on the application and resource names.isReadOnlybooloptionalUnsupported. DocumentDB requires a writable data directory; passing true throws.targetPathstring?optionalThe target path inside the container. Defaults to /data to match the container default (and the path the image declares as a volume) when this helper is used. Canonicalized the way the container runtime resolves a path, so repeated separators and . / .. segments are collapsed before the mount is created.Returns
IResourceBuilder<DocumentDBServerResource>The ApplicationModel.IResourceBuilder`1.Exceptions
ArgumentExceptionisReadOnly is true, or targetPath is not an absolute container path below the root — including one that only resolves to the root, such as /data/.., and one that reaches above it, such as /../data, which the container runtime silently clamps onto /data.Remarks
The bare DocumentDB container defaults DATA_PATH to /data. Up to and including DocumentDB v0.114-0 an unmounted /data is an ordinary directory in the container's writable layer, discarded when the container is removed. From v0.116-0 the image declares that path as a container VOLUME, so a run that mounts nothing there instead gets a fresh anonymous volume whose lifetime the container runtime controls (and which container removal can strand). On those images, mounting at the default targetPath is what suppresses the anonymous volume: neither Docker nor Aspire can un-declare an image volume, so a non-default targetPath leaves an unused anonymous volume behind at /data and the resource logs a warning at start.
This helper mounts the volume at targetPath and sets DATA_PATH to the same value so DocumentDB writes to the mounted directory. From v0.116-0 the container claims the directory with an exclusive flock, so a persisted data directory may back only one running container at a time; a second container that mounts it exits immediately with an explicit refusal instead of corrupting the directory. Earlier images have no such interlock, so concurrent use has to be avoided by construction.
The data directory must be writable. The entrypoint takes ownership of it (the container's documentdb runtime user) and PostgreSQL initialises and writes WAL there, so isReadOnly is rejected rather than being allowed to fail a minute into startup behind a misleading "PostgreSQL failed to start within 60 seconds" banner.
Examples
var server = builder.AddDocumentDB("documentdb") .WithDataVolume();WithDocumentDBVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBVersion)Section titled WithDocumentDBVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBVersion)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithDocumentDBVersion( this IResourceBuilder<DocumentDBServerResource> builder, DocumentDBVersion version) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.versionDocumentDBVersionThe DocumentDB version to use.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
The selected version is combined with the currently selected DocumentDBPostgresVersion (default DocumentDBPostgresVersion.Pg17) to produce the container image tag pgN-X.Y.Z.
Precedence: for the image tag, the most recent of DocumentDBBuilderExtensions.WithDocumentDBVersion, DocumentDBBuilderExtensions.WithPostgresVersion, ContainerResourceBuilderExtensions.WithImage, and ContainerResourceBuilderExtensions.WithImageTag wins. They all converge on the same single ApplicationModel.ContainerImageAnnotation.
This method updates only the image tag. A custom image name or registry configured with ContainerResourceBuilderExtensions.WithImage or ContainerResourceBuilderExtensions.WithImageRegistry is preserved.
To pin to a version not in DocumentDBVersion (for example, a brand-new upstream release this package has not yet been updated to know about), use ContainerResourceBuilderExtensions.WithImageTag directly with a tag like "pg17-0.999.0".
Examples
var server = builder.AddDocumentDB("documentdb") .WithDocumentDBVersion(DocumentDBVersion.V0_110_0);WithHostPort(IResourceBuilder<DocumentDBServerResource>, int?)Section titled WithHostPort(IResourceBuilder<DocumentDBServerResource>, int?)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithHostPort( this IResourceBuilder<DocumentDBServerResource> builder, int? port) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.portint?The port to bind on the host. If null is used random port will be assigned.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Examples
var server = builder.AddDocumentDB("documentdb") .WithHostPort(10260);WithInitData(IResourceBuilder<DocumentDBServerResource>, string)Section titled WithInitData(IResourceBuilder<DocumentDBServerResource>, string)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithInitData( this IResourceBuilder<DocumentDBServerResource> builder, string source) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.sourcestringThe source directory on the host to mount into the container.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
/init_doc_db.d, and the built-in sample data initialization is implicitly disabled so the mounted scripts are the only initialization source. DocumentDB v0.116-0 records initialization attempts in the data directory. Scripts run once for a new volume and are not reapplied when their contents change. A failed partial attempt is also not automatically retried; use a fresh or reset volume after correcting the scripts. WithLogLevel(IResourceBuilder<DocumentDBServerResource>, DocumentDBLogLevel)Section titled WithLogLevel(IResourceBuilder<DocumentDBServerResource>, DocumentDBLogLevel)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithLogLevel( this IResourceBuilder<DocumentDBServerResource> builder, DocumentDBLogLevel logLevel) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.logLevelDocumentDBLogLevelThe log level to configure.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
0.114.0, the gateway reads DOCUMENTDB_LOG_LEVEL as a tracing filter. This makes the API observably effective on the current default image. The legacy LOG_LEVEL variable is also set because the Local image entrypoint validates that contract, although no Local image uses it to select gateway verbosity. Images through 0.113.0 therefore treat this API as a verbosity no-op. DocumentDBLogLevel.Quiet remains mapped to quiet for API compatibility. It is not a tracing level: on 0.114.0 and later it becomes newly effective because the gateway parses it as an unmatched target directive, which suppresses gateway output but depends on upstream filter semantics. WithOpenTelemetryMetrics(IResourceBuilder<DocumentDBServerResource>, string?, bool, TimeSpan?, TimeSpan?, string?, string?)Section titled WithOpenTelemetryMetrics(IResourceBuilder<DocumentDBServerResource>, string?, bool, TimeSpan?, TimeSpan?, string?, string?)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithOpenTelemetryMetrics( this IResourceBuilder<DocumentDBServerResource> builder, string? endpoint = null, bool enabled = true, TimeSpan? exportInterval = null, TimeSpan? timeout = null, string? serviceName = null, string? serviceVersion = null) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.endpointstring?optional OTLP/gRPC endpoint of the collector that should receive metrics. When provided, sets OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (which takes precedence over the generic OTEL_EXPORTER_OTLP_ENDPOINT per the OpenTelemetry specification). Defaults to null (leave the environment variable unset; gateway falls back to its own default). enabledbooloptional Whether metrics export is enabled. Sets OTEL_METRICS_ENABLED. Defaults to true: opting into this method clearly indicates the caller wants metrics on. exportIntervalTimeSpan?optional How often the gateway flushes accumulated metrics to the collector. When provided, sets OTEL_METRIC_EXPORT_INTERVAL (milliseconds, integer). Must be non-negative. timeoutTimeSpan?optional Per-export request timeout. When provided, sets OTEL_EXPORTER_OTLP_METRICS_TIMEOUT (milliseconds, integer). Must be non-negative. serviceNamestring?optional Logical service name attached to the telemetry. When provided, sets OTEL_SERVICE_NAME and, on affected images, removes the shared TelemetryOptions.ServiceName so this value wins for every signal. serviceVersionstring?optional Logical service version attached to the telemetry. When provided, sets OTEL_SERVICE_VERSION and, on affected images, removes the shared TelemetryOptions.ServiceVersion so this value wins for every signal. Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Exceptions
ArgumentNullExceptionbuilder is null.ArgumentExceptionendpoint, serviceName, or serviceVersion is provided but is empty or whitespace. ArgumentOutOfRangeExceptionexportInterval or timeout is negative. Remarks
Requires container image v0.112-0 or later. This API configures metrics only. The gateway also supports tracing in v0.116-0 and later, but this package does not yet expose a typed tracing API.
The container default for OTEL_METRICS_ENABLED is false; calling this method flips it to true unless enabled is explicitly set to false.
Starting with DocumentDB v0.116-0, the gateway resolves telemetry settings as JSON > environment variable > default, reading them from SetupConfiguration.json, and the shipped file pins metrics off. Whenever this method is called against an official documentdb-local image of that version or later, it therefore wraps the container entrypoint so the container starts from a copy of that configuration with the shadowing keys removed. The copy is derived from the same directory the image's own entrypoint would read: an explicit CONFIG_DIR, else the packaged /etc/documentdb/gateway layout when present, else $GATEWAY_HOME/pg_documentdb_gw.
The wrapper is applied for enabled: false as well, because a caller-supplied configuration file can turn metrics on from JSON and an explicit enabled: false has to win. The TelemetryOptions.Metrics object is removed whole, since this API owns that signal and any surviving key - including one a later gateway release adds - would re-pin a setting ahead of the environment precedence documented below, such as the OTEL_EXPORTER_OTLP_ENDPOINT fallback. The shared identity keys are removed only when the corresponding parameter was explicitly supplied on some call, and TelemetryOptions.Tracing is never touched, so the stock image keeps its shipped service identity and its disabled tracing.
Because the gateway builds one OpenTelemetry Resource for all signals, supplying serviceName or serviceVersion removes the shared JSON identity and therefore changes the identity of exported traces too, not only metrics. Omit them to keep the identity the configuration file specifies.
The wrapper is expressed purely as the container entrypoint and args, both of which round-trip through the Aspire manifest, so publish mode, azd and direct run mode all execute the same thing. Custom images, tags outside the pg{NN}-X.Y.Z grammar and resources built from your own Dockerfile are left completely untouched — the last of those even when the resource's image annotation names the official image and a recognised tag, because what runs is the build output; private mirrors of the official image are not, because only the registry differs. Pinning the official image by digest throws, because the digest makes the version opaque and both applying and skipping the wrapper on a guess are silently wrong. Supplying your own container entrypoint on the same resource also throws, because the two cannot both own the container command. The wrapper needs bash and jq, which the official image provides; it fails the container start with a diagnostic rather than starting without the override if either is missing.
Merge semantics across multiple calls on the same builder: enabled is non-nullable and is therefore written on every call. The last call's value wins (defaulting to true when omitted), even if a previous call set it to false. null.
When endpoint is omitted, the gateway falls back to the standard OTLP/gRPC default ( http://localhost:4317). In an Aspire container scenario, that fallback is rarely reachable, so an explicit endpoint pointing to your collector is recommended.
exportInterval and timeout are written as integer milliseconds via CultureInfo.InvariantCulture. Values smaller than one millisecond (sub-ms ticks) truncate to 0; callers should pass whole-millisecond or larger granularities.
Examples
var server = builder.AddDocumentDB("documentdb") .WithOpenTelemetryMetrics( endpoint: "http://otel-collector:4317", exportInterval: TimeSpan.FromSeconds(30));WithoutExtendedRum(IResourceBuilder<DocumentDBServerResource>)Section titled WithoutExtendedRum(IResourceBuilder<DocumentDBServerResource>)extensionIResourceBuilder<DocumentDBServerResource>extended_rum index access method in the DocumentDB Local container by setting DISABLE_EXTENDED_RUM=true. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithoutExtendedRum( this IResourceBuilder<DocumentDBServerResource> builder) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
v0.111-0 and later. On older container images the environment variable is ignored. WithoutSampleData(IResourceBuilder<DocumentDBServerResource>)Section titled WithoutSampleData(IResourceBuilder<DocumentDBServerResource>)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithoutSampleData( this IResourceBuilder<DocumentDBServerResource> builder) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
DocumentDBBuilderExtensions.WithInitData are unaffected and still run for a new data volume. WithoutUserCreation(IResourceBuilder<DocumentDBServerResource>)Section titled WithoutUserCreation(IResourceBuilder<DocumentDBServerResource>)extensionIResourceBuilder<DocumentDBServerResource>CREATE_USER=false environment variable. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithoutUserCreation( this IResourceBuilder<DocumentDBServerResource> builder) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
0.112.0 and older, built-in sample initialization is enabled by default. On a fresh container, this method must be paired with DocumentDBBuilderExtensions.WithoutSampleData so the default initialization does not require the skipped credentials. For images from 0.113.0 onward, including 0.116.0, built-in sample initialization does not run unless requested. A fresh container can therefore remain running with user creation disabled when no initialization requiring those credentials is requested. The generated connection strings still will not authenticate unless the user already exists, typically in persisted storage created through DocumentDBBuilderExtensions.WithDataVolume or DocumentDBBuilderExtensions.WithDataBindMount.
On every version, requested built-in sample initialization and custom scripts mounted through DocumentDBBuilderExtensions.WithInitData authenticate using the configured credentials. If the skipped user does not already exist, that initialization can fail and cause the container to exit. DocumentDBBuilderExtensions.WithoutSampleData disables only the built-in sample data; it does not disable custom initialization scripts.
WithOwner(IResourceBuilder<DocumentDBServerResource>, string)Section titled WithOwner(IResourceBuilder<DocumentDBServerResource>, string)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithOwner( this IResourceBuilder<DocumentDBServerResource> builder, string owner) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.ownerstringThe existing PostgreSQL role used for DocumentDB database operations.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
documentdb role. A custom value must name a role that already exists, such as the owner of an externally managed PostgreSQL instance. DocumentDB 0.116.0 aborts explicitly while creating the DocumentDB admin user when the configured role does not exist. Earlier images also fail startup, but only later while waiting for the gateway to start. WithPostgresEndpoint(IResourceBuilder<DocumentDBServerResource>, int?)Section titled WithPostgresEndpoint(IResourceBuilder<DocumentDBServerResource>, int?)extensionIResourceBuilder<DocumentDBServerResource>9712) as a second endpoint on the resource. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithPostgresEndpoint( this IResourceBuilder<DocumentDBServerResource> builder, int? port = null) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.portint?optional The host port to bind to. If null a random port is assigned. Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
The documentdb-local container bundles a MongoDB-compatible gateway and a PostgreSQL coordinator listening on separate ports. By default this integration only publishes the gateway port ( 10260) and surfaces a mongodb:// connection string. Calling DocumentDBBuilderExtensions.WithPostgresEndpoint additionally publishes the PostgreSQL port so consumers can use psql/Npgsql/etc. directly, and enables DocumentDBServerResource.PostgresConnectionStringExpression.
The endpoint uses the same userName / password parameters as the gateway because the container provisions a single admin user shared by both surfaces. The default database in the resulting URI is postgres, matching the upstream entrypoint, which connects with -d postgres.
Examples
var documentDB = builder.AddDocumentDB("documentdb") .WithPostgresEndpoint();
builder.AddProject<Projects.Worker>("worker") .WithEnvironment("ConnectionStrings__pg", documentDB.Resource.PostgresConnectionStringExpression);WithPostgresVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBPostgresVersion)Section titled WithPostgresVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBPostgresVersion)extensionIResourceBuilder<DocumentDBServerResource>documentdb-local container image. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithPostgresVersion( this IResourceBuilder<DocumentDBServerResource> builder, DocumentDBPostgresVersion pgVersion) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.pgVersionDocumentDBPostgresVersionThe PostgreSQL backend variant to use.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Exceptions
ArgumentNullExceptionThrown when builder is null.ArgumentOutOfRangeException Thrown when pgVersion is not a defined member of DocumentDBPostgresVersion. Use a free-form ContainerResourceBuilderExtensions.WithImageTag call to target an unsupported PG variant. Remarks
The selected variant is combined with the currently selected DocumentDBVersion (or DocumentDBVersions.Latest by default) to produce the container image tag pgN-X.Y.Z.
Precedence: see DocumentDBBuilderExtensions.WithDocumentDBVersion — last call wins.
Examples
var server = builder.AddDocumentDB("documentdb") .WithPostgresVersion(DocumentDBPostgresVersion.Pg16) .WithDocumentDBVersion(DocumentDBVersion.V0_110_0);// -> image tag "pg16-0.110.0"WithTelemetry(IResourceBuilder<DocumentDBServerResource>, bool)Section titled WithTelemetry(IResourceBuilder<DocumentDBServerResource>, bool)extensionIResourceBuilder<DocumentDBServerResource>ENABLE_TELEMETRY environment variable. public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithTelemetry( this IResourceBuilder<DocumentDBServerResource> builder, bool enabled = true) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.enabledbooloptionalWhether telemetry should be enabled.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
ENABLE_TELEMETRY environment variable is not consumed by the DocumentDB gateway in container image v0.112-0 or later. On those images this method has no observable effect on the running container. Use DocumentDBBuilderExtensions.WithOpenTelemetryMetrics to configure OTLP metrics export. WithTlsCertificate(IResourceBuilder<DocumentDBServerResource>, string, string)Section titled WithTlsCertificate(IResourceBuilder<DocumentDBServerResource>, string, string)extensionIResourceBuilder<DocumentDBServerResource>public static class DocumentDBBuilderExtensions{ public static IResourceBuilder<DocumentDBServerResource> WithTlsCertificate( this IResourceBuilder<DocumentDBServerResource> builder, string certPath, string keyPath) { // ... }}Parameters
builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.certPathstringThe certificate file to mount into the container.keyPathstringThe private key file to mount into the container.Returns
IResourceBuilder<DocumentDBServerResource>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
Aspire