Aspire.Hosting.DocumentDB

An Aspire hosting integration for DocumentDB, the open-source MongoDB-compatible document database built on PostgreSQL.

This package lets you add a DocumentDB container to your Aspire AppHost with a single line of code. Connection strings, credentials, TLS, and container lifecycle are managed automatically.

Quick start

Prerequisites

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

Install the package

In your Aspire AppHost project:

dotnet add package Aspire.Hosting.DocumentDB

Add DocumentDB to your AppHost

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Use MongoDB client in your service

In your service project, install and register the MongoDB driver:

dotnet add package Aspire.MongoDB.Driver

builder.AddMongoDBClient("mydb");

Then inject IMongoClient wherever you need it. The connection string is resolved automatically.

Configuration methods

Method	Description
AddDocumentDB(name, port?, userName?, password?)	Add a DocumentDB server resource
.AddDatabase(name, databaseName?)	Add a database on the server
.WithHostPort(port)	Bind to a specific host port
.WithDataVolume(name?, isReadOnly?, targetPath?)	Persist data with a Docker volume (isReadOnly: true is rejected)
.WithDataBindMount(source, isReadOnly?)	Persist data with a host directory mount (isReadOnly: true is rejected; does not reliably survive a restart on Docker Desktop — see troubleshooting)
.UseTls(useTls?)	Enable/disable TLS (default: enabled)
.AllowInsecureTls(allowInsecureTls?)	Allow self-signed certificates (default: enabled)
.WithDocumentDBVersion(version)	Pin a curated DocumentDB version (default: latest known to this build)
.WithPostgresVersion(pgVersion)	Choose PG15/16/17/18 backend variant (default: Pg17)
.WithPostgresEndpoint(port?)	Also expose the PostgreSQL backend port (9712) and enable PostgresConnectionStringExpression
.WithoutUsageTelemetry()	Turn off the DocumentDB 1.0.0+ image's usage telemetry, which is on by default (details)

See the Configuration Reference for details, code examples, and default values.

Documentation

Document	Description
Getting Started	Step-by-step guide to set up DocumentDB in an Aspire app
Configuration Reference	All methods, parameters, defaults, and connection string format
Troubleshooting	Common issues and solutions
Changelog	Release history
NuGet Package README	Package overview shown on nuget.org

About DocumentDB

DocumentDB is an open-source document database that provides MongoDB compatibility on top of PostgreSQL. It supports:

• Full MongoDB CRUD API via the MongoDB wire protocol
• BSON document storage
• Rich query support including aggregation pipelines
• Full-text, geospatial, and vector search
• SCRAM-SHA-256 authentication with TLS

The Aspire integration runs the documentdb-local container image, which bundles the DocumentDB gateway and PostgreSQL backend in a single container.

Contributing

Contributions are welcome. Please open an issue first to discuss the change you'd like to make.

To build and test locally:

dotnet build azure-databases-aspire.sln
dotnet test azure-databases-aspire.sln

End-to-end tests require a running Docker daemon.

License

This project is licensed under the MIT License.