Aspire.Hosting.DocumentDB 1.0.0

Aspire.Hosting.DocumentDB

DocumentDB is an open-source, MongoDB-compatible document database built on PostgreSQL. This package provides Aspire hosting integration to configure and run a DocumentDB container as part of your distributed application.

Getting started

Prerequisites

• .NET 10 SDK or later
• Aspire CLI
• Docker (DocumentDB runs as a Linux container)

Install the package

In your AppHost project:

dotnet add package Aspire.Hosting.DocumentDB

Add a DocumentDB resource

In the AppHost Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddDocumentDB("documentdb")
                .AddDatabase("mydb");

builder.AddProject<Projects.MyService>("myservice")
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();

Connect from your service

In your service project, install the Aspire MongoDB driver integration:

dotnet add package Aspire.MongoDB.Driver

Register the client in Program.cs:

builder.AddMongoDBClient("mydb");

Inject and use the MongoDB client:

public class MyService(IMongoClient mongoClient)
{
    private readonly IMongoDatabase _database = mongoClient.GetDatabase("mydb");

    public async Task<List<BsonDocument>> GetDocumentsAsync()
    {
        var collection = _database.GetCollection<BsonDocument>("mycollection");
        return await collection.Find(FilterDefinition<BsonDocument>.Empty).ToListAsync();
    }
}

The Aspire integration handles connection string resolution, TLS configuration, and credential management automatically.

Configuration

Additional container configuration

For closer-to-production local setups, debugging, or custom data seeding, the hosting integration exposes additional DocumentDB Local container options:

var documentdb = builder.AddDocumentDB("documentdb")
    .WithLogLevel(DocumentDBLogLevel.Debug)
    .WithInitData("../seed")
    .WithTlsCertificate("../certs/documentdb.pem", "../certs/documentdb.key")
    .WithOpenTelemetryMetrics(endpoint: "http://otel-collector:4317")
    .WithOwner("documentdb")
    .WithoutUsageTelemetry();

var db = documentdb.AddDatabase("mydb");

WithLogLevel(...) becomes observably effective on DocumentDB 0.114.0 and later through DOCUMENTDB_LOG_LEVEL, including the current default image. On images through 0.113.0, neither variable controls gateway verbosity; LOG_LEVEL is retained because the Local entrypoint validates its six-value contract, not because a Local image uses it to select gateway verbosity. Quiet remains mapped to quiet for API compatibility and becomes newly effective on 0.114.0 and later. Because upstream tracing has no quiet level, current gateways suppress output by parsing it as an unmatched tracing target; that behavior depends on upstream filter semantics.

WithInitData(...) mounts a host directory into /init_doc_db.d and also disables the built-in sample data so your custom scripts are the only initialization source. Use WithoutSampleData() when you want to disable the built-in sample collections. It does not disable custom initialization scripts configured through WithInitData(...).

For curated images 0.112.0 and older, built-in sample initialization is enabled by default, so WithoutUserCreation() must be paired with WithoutSampleData() on a fresh container. From 0.113.0 onward, including 1.0.0, built-in sample initialization is opt-in and a fresh container can remain running without creating the user when no initialization requiring those credentials is requested. Generated connection strings still will not authenticate unless that user already exists, typically in persisted storage from an earlier run. On every version, requested built-in or custom initialization can fail if the skipped user does not already exist. WithoutSampleData() does not disable custom initialization.

WithTlsCertificate(...) mounts the certificate and key files at distinct container paths, so they can be supplied even when their host file names are identical.

Usage telemetry

From DocumentDB 1.0.0, the default image sends usage telemetry: its version, platform and CPU architecture at startup and then hourly. The receiving service also sees your network address, so don't treat it as anonymous. This package leaves the image default on. Turn it off with .WithoutUsageTelemetry(), or set DO_NOT_TRACK=1 or NO_ANALYTICS=1 on the resource with .WithEnvironment(...). Variables set in your shell or CI job don't reach the container. See the upstream privacy statement.

Connection strings

The extension generates MongoDB connection strings automatically:

mongodb://admin:<password>@<host>:<port>[/<database>]?authSource=admin&authMechanism=SCRAM-SHA-256&tls=true&tlsInsecure=true

TLS and insecure TLS are enabled by default so the .NET MongoDB driver can connect to the self-signed certificate used by the DocumentDB Local container.

Data persistence

Use WithDataVolume() when data must persist predictably across container replacement:

builder.AddDocumentDB("documentdb")
       .WithDataVolume()
       .AddDatabase("mydb");

Up to and including 0.114.0 an unmounted /data is a directory in the container's writable layer, discarded with the container. From 0.116.0 the image declares /data as a container volume, so a run that mounts nothing there instead gets an anonymous volume whose lifetime the container runtime controls and which container removal can strand. WithDataVolume() and WithDataBindMount(...) mount on that same path, which both makes persistence intentional and, on those images, suppresses the anonymous volume. Pair either with stable credential parameters.

The data directory must be writable, and must be empty or hold an existing DocumentDB cluster: isReadOnly: true is rejected, and a directory holding anything else is refused (not cleaned) by the container. From 0.116.0 it is also exclusive — only one running container at a time may use a given volume or host directory — and initialization (sample data or WithInitData(...)) runs once per data directory and is not retried after a failed attempt. On 0.114.0 and earlier there is no such marker: the requested initialization runs on every container start, so seed scripts used with persisted storage must be idempotent. See the configuration reference for the full rules.

WithDataBindMount() is not an equivalent choice on Docker Desktop. Its host file sharing does not apply ownership changes to the mounted path in time for PostgreSQL's data-directory check, so the first run works and every later run fails to start with FATAL: data directory "/data" has wrong ownership, leaving the data on the host but unreadable. This was measured on macOS (VirtioFS) and is expected on Docker Desktop's other hosts, which share that design. See Bind-mounted data fails to restart on Docker Desktop.

More information

• Getting started guide — detailed step-by-step setup
• Configuration reference — all methods, parameters, defaults, and connection string details
• Troubleshooting — TLS errors, Docker issues, connection failures, debugging
• Changelog — release history
• License — package license
• DocumentDB project — the database itself
• Aspire documentation — Aspire framework docs