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.databaseName string?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
builderIDistributedApplicationBuilder The 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
builderIDistributedApplicationBuilder The 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.userName IResourceBuilder<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.allowInsecureTls booloptionalWhether 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.useTls booloptionalWhether 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.isReadOnly booloptionalUnsupported. DocumentDB requires a writable data directory; passing true throws.Returns
IResourceBuilder<DocumentDBServerResource> The ApplicationModel.IResourceBuilder`1 .Exceptions
ArgumentExceptionisReadOnly is true.Remarks
Prefer Document 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_ 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_ 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_ is enough) is refused, not cleaned: the container logs Directory /data exists but doesn't
appear to contain a valid Postgre, never starts PostgreSQL, and exits non-zero a minute later behind the "PostgreSQL failed to start within 60 seconds" banner.
is 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_ 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 Document 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.isReadOnly booloptionalUnsupported. DocumentDB requires a writable data directory; passing true throws.targetPath string?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_ 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 target is what suppresses the anonymous volume: neither Docker nor Aspire can un-declare an image volume, so a non-default target leaves an unused anonymous volume behind at /data and the resource logs a warning at start.
This helper mounts the volume at target and sets DATA_ 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 is 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.versionDocumentReturns
IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
The selected version is combined with the currently selected Document (default Document) to produce the container image tag pg.
Precedence: for the image tag, the most recent of Document, Document, Container, and Container wins. They all converge on the same single Application.
This method updates only the image tag. A custom image name or registry configured with Container or Container is preserved.
To pin to a version not in Document (for example, a brand-new upstream release this package has not yet been updated to know about), use Container directly with a tag like "pg17-.
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.logLevel DocumentReturns
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. exportInterval TimeSpan? 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. serviceName string?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. serviceVersion string?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_ 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 Setup, and the shipped file pins metrics off. Whenever this method is called against an official documentdb- 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_, else the packaged /etc/ layout when present, else $GATEWAY_.
The wrapper is applied for enabled: as well, because a caller-supplied configuration file can turn metrics on from JSON and an explicit enabled: has to win. The Telemetry 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_ fallback. The shared identity keys are removed only when the corresponding parameter was explicitly supplied on some call, and Telemetry 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 service or service 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}- 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:). In an Aspire container scenario, that fallback is rarely reachable, so an explicit endpoint pointing to your collector is recommended.
export and timeout are written as integer milliseconds via Culture. 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 Document or Document.
On every version, requested built-in sample initialization and custom scripts mounted through Document authenticate using the configured credentials. If the skipped user does not already exist, that initialization can fail and cause the container to exit. Document 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- 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 Document additionally publishes the PostgreSQL port so consumers can use psql/Npgsql/etc. directly, and enables Document.
The endpoint uses the same user / 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 -.
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.pgVersion DocumentReturns
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 Document (or Document by default) to produce the container image tag pg.
Precedence: see Document — 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.certPath stringThe certificate file to mount into the container.keyPath stringThe private key file to mount into the container.Returns
IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
Aspire