# DocumentDBBuilderExtensions Methods - Package: [Aspire.Hosting.DocumentDB](/reference/api/csharp/aspire.hosting.documentdb.md) - Type: [DocumentDBBuilderExtensions](/reference/api/csharp/aspire.hosting.documentdb/documentdbbuilderextensions.md) - Kind: `Methods` - Members: `16` Provides extension methods for adding DocumentDB resources to an `Hosting.IDistributedApplicationBuilder`. ## AddDatabase(IResourceBuilder, string, string?) - Name: `AddDatabase(IResourceBuilder, string, string?)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L143-L172) Adds a DocumentDB database to the application model. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder AddDatabase( this IResourceBuilder builder, string name, string? databaseName = null) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The DocumentDB server resource builder. - `name` (`string`) The name of the resource. This name will be used as the connection string name when referenced in a dependency. - `databaseName` (`string?`) `optional` The name of the database. If not provided, this defaults to the same value as `name`. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks The database resource inherits the parent server's connection string and appends the database name. Services should reference the database resource (not the server) via `.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 ```csharp var server = builder.AddDocumentDB("documentdb"); var ordersDb = server.AddDatabase("orders"); var usersDb = server.AddDatabase("users"); ``` ## AddDocumentDB(IDistributedApplicationBuilder, string, int?) - Name: `AddDocumentDB(IDistributedApplicationBuilder, string, int?)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L53) Adds a DocumentDB resource to the application model. A container is used for local development. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder AddDocumentDB( this IDistributedApplicationBuilder builder, string name, int? port) { // ... } } ``` ## Parameters - `builder` (`IDistributedApplicationBuilder`) The `Hosting.IDistributedApplicationBuilder`. - `name` (`string`) The name of the resource. This name will be used as the connection string name when referenced in a dependency. - `port` (`int?`) The host port for DocumentDB. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks 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 server responds to ping. This version of the package defaults to the tag of the container image. ## Examples ```csharp var server = builder.AddDocumentDB("documentdb", port: 10260); ``` ## AddDocumentDB(IDistributedApplicationBuilder, string, int?, IResourceBuilder, IResourceBuilder) - Name: `AddDocumentDB(IDistributedApplicationBuilder, string, int?, IResourceBuilder, IResourceBuilder)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L82-L117) ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder AddDocumentDB( this IDistributedApplicationBuilder builder, string name, int? port = null, IResourceBuilder? userName = null, IResourceBuilder? password = null) { // ... } } ``` ## Parameters - `builder` (`IDistributedApplicationBuilder`) The `Hosting.IDistributedApplicationBuilder`. - `name` (`string`) The name of the resource. This name will be used as the connection string name when referenced in a dependency. - `port` (`int?`) `optional` The host port for DocumentDB. - `userName` (`IResourceBuilder`) `optional` A parameter that contains the DocumentDB server user name, or `null` to use a default value. - `password` (`IResourceBuilder`) `optional` A parameter that contains the DocumentDB server password, or `null` to use a generated password. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Examples ```csharp // 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, bool) - Name: `AllowInsecureTls(IResourceBuilder, bool)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L435-L438) Allows insecure TLS connections by adding `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. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder AllowInsecureTls( this IResourceBuilder builder, bool allowInsecureTls = true) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `allowInsecureTls` (`bool`) `optional` Whether to allow insecure TLS. Defaults to `true`. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks The extension uses `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 ```csharp // Require valid certificates (for example, production with real certs): var server = builder.AddDocumentDB("documentdb") .AllowInsecureTls(false); ``` ## UseTls(IResourceBuilder, bool) - Name: `UseTls(IResourceBuilder, bool)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L406-L409) Enables TLS for the DocumentDB connection string. TLS is enabled by default because the DocumentDB Local container requires TLS connections. Call `UseTls(false)` to disable TLS if connecting to a non-TLS endpoint. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder UseTls( this IResourceBuilder builder, bool useTls = true) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `useTls` (`bool`) `optional` Whether to enable TLS. Defaults to `true`. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Examples ```csharp // Disable TLS for a non-TLS endpoint: var server = builder.AddDocumentDB("documentdb") .UseTls(false); ``` ## WithDataBindMount(IResourceBuilder, string, bool) - Name: `WithDataBindMount(IResourceBuilder, string, bool)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L257-L267) Adds a bind mount for the data folder to a DocumentDB container resource. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithDataBindMount( this IResourceBuilder builder, string source, bool isReadOnly = false) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder. - `source` (`string`) The source directory on the host to mount into the container. - `isReadOnly` (`bool`) `optional` A flag that indicates if this is a read-only mount. ## Returns `IResourceBuilder` -- The `ApplicationModel.IResourceBuilder`1`. ## Remarks Prefer [DocumentDBBuilderExtensions.WithDataVolume(IResourceBuilder, string?, bool, string?)](/reference/api/csharp/aspire.hosting.documentdb/documentdbbuilderextensions/methods.md#withdatavolume-iresourcebuilder-documentdbserverresource-string-bool-string) for most cases. Bind mounts are useful when you need direct access to the data files on the host filesystem. The bare DocumentDB container defaults `DATA_PATH` to `/data`. This helper mounts the directory at `/data` (the container default) and sets `DATA_PATH` to the same value so DocumentDB writes to the mounted directory. ## Examples ```csharp var server = builder.AddDocumentDB("documentdb") .WithDataBindMount("./data/documentdb"); ``` ## WithDataVolume(IResourceBuilder, string?, bool, string?) - Name: `WithDataVolume(IResourceBuilder, string?, bool, string?)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L223-L232) Adds a named volume for the data folder to a DocumentDB container resource. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithDataVolume( this IResourceBuilder builder, string? name = null, bool isReadOnly = false, string? targetPath = null) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder. - `name` (`string?`) `optional` The name of the volume. Defaults to an auto-generated name based on the application and resource names. - `isReadOnly` (`bool`) `optional` A flag that indicates if this is a read-only volume. - `targetPath` (`string?`) `optional` The target path inside the container. Defaults to /data to match the container default when this helper is used. ## Returns `IResourceBuilder` -- The `ApplicationModel.IResourceBuilder`1`. ## Remarks Without a volume, all data is stored inside the container and lost when it stops. The bare DocumentDB container defaults `DATA_PATH` to `/data`. This helper mounts the volume at `targetPath` and sets `DATA_PATH` to the same value so DocumentDB writes to the mounted directory. ## Examples ```csharp var server = builder.AddDocumentDB("documentdb") .WithDataVolume(); ``` ## WithDocumentDBVersion(IResourceBuilder, DocumentDBVersion) - Name: `WithDocumentDBVersion(IResourceBuilder, DocumentDBVersion)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L483-L486) Pins the DocumentDB version to a specific release known to this build of the package. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithDocumentDBVersion( this IResourceBuilder builder, DocumentDBVersion version) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `version` ([DocumentDBVersion](/reference/api/csharp/aspire.hosting.documentdb/documentdbversion.md)) The DocumentDB version to use. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks The selected version is combined with the currently selected [DocumentDBPostgresVersion](/reference/api/csharp/aspire.hosting.documentdb/documentdbpostgresversion.md) (default [DocumentDBPostgresVersion.Pg17](/reference/api/csharp/aspire.hosting.documentdb/documentdbpostgresversion/fields.md)) to produce the container image tag `pgN-X.Y.Z`. Precedence: for the image tag, the most recent of [DocumentDBBuilderExtensions.WithDocumentDBVersion(IResourceBuilder, DocumentDBVersion)](/reference/api/csharp/aspire.hosting.documentdb/documentdbbuilderextensions/methods.md#withdocumentdbversion-iresourcebuilder-documentdbserverresource-documentdbversion), [DocumentDBBuilderExtensions.WithPostgresVersion(IResourceBuilder, DocumentDBPostgresVersion)](/reference/api/csharp/aspire.hosting.documentdb/documentdbbuilderextensions/methods.md#withpostgresversion-iresourcebuilder-documentdbserverresource-documentdbpostgresversion), `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](/reference/api/csharp/aspire.hosting.documentdb/documentdbversion.md) (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 ```csharp var server = builder.AddDocumentDB("documentdb") .WithDocumentDBVersion(DocumentDBVersion.V0_110_0); ``` ## WithHostPort(IResourceBuilder, int?) - Name: `WithHostPort(IResourceBuilder, int?)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L189-L194) Configures the host port that the DocumentDB resource is exposed on instead of using randomly assigned port. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithHostPort( this IResourceBuilder builder, int? port) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `port` (`int?`) The port to bind on the host. If `null` is used random port will be assigned. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Examples ```csharp var server = builder.AddDocumentDB("documentdb") .WithHostPort(10260); ``` ## WithInitData(IResourceBuilder, string) - Name: `WithInitData(IResourceBuilder, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L298-L307) Mounts custom initialization scripts into the DocumentDB Local container. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithInitData( this IResourceBuilder builder, string source) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `source` (`string`) The source directory on the host to mount into the container. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks The provided directory is bind-mounted at `/init_doc_db.d`, and the built-in sample data initialization is implicitly disabled so the mounted scripts are the only initialization source. ## WithLogLevel(IResourceBuilder, DocumentDBLogLevel) - Name: `WithLogLevel(IResourceBuilder, DocumentDBLogLevel)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L278-L283) Configures the DocumentDB Local container log level. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithLogLevel( this IResourceBuilder builder, DocumentDBLogLevel logLevel) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `logLevel` ([DocumentDBLogLevel](/reference/api/csharp/aspire.hosting.documentdb/documentdbloglevel.md)) The log level to configure. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## WithoutSampleData(IResourceBuilder) - Name: `WithoutSampleData(IResourceBuilder)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L317-L322) Disables the built-in sample data initialization performed by the DocumentDB Local container. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithoutSampleData( this IResourceBuilder builder) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## WithOwner(IResourceBuilder, string) - Name: `WithOwner(IResourceBuilder, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L380-L386) Configures the owner used by the DocumentDB Local container. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithOwner( this IResourceBuilder builder, string owner) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `owner` (`string`) The owner value to configure. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## WithPostgresVersion(IResourceBuilder, DocumentDBPostgresVersion) - Name: `WithPostgresVersion(IResourceBuilder, DocumentDBPostgresVersion)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L524-L539) Selects the PostgreSQL backend variant of the `documentdb-local` container image. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithPostgresVersion( this IResourceBuilder builder, DocumentDBPostgresVersion pgVersion) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `pgVersion` ([DocumentDBPostgresVersion](/reference/api/csharp/aspire.hosting.documentdb/documentdbpostgresversion.md)) The PostgreSQL backend variant to use. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Exceptions - `ArgumentNullException` -- Thrown when `builder` is `null`. - `ArgumentOutOfRangeException` -- Thrown when `pgVersion` is not a defined member of [DocumentDBPostgresVersion](/reference/api/csharp/aspire.hosting.documentdb/documentdbpostgresversion.md). Use a free-form `ContainerResourceBuilderExtensions.WithImageTag` call to target an unsupported PG variant. ## Remarks The selected variant is combined with the currently selected [DocumentDBVersion](/reference/api/csharp/aspire.hosting.documentdb/documentdbversion.md) (or [DocumentDBVersions.Latest](/reference/api/csharp/aspire.hosting.documentdb/documentdbversions/properties.md#latest) by default) to produce the container image tag `pgN-X.Y.Z`. Precedence: see [DocumentDBBuilderExtensions.WithDocumentDBVersion(IResourceBuilder, DocumentDBVersion)](/reference/api/csharp/aspire.hosting.documentdb/documentdbbuilderextensions/methods.md#withdocumentdbversion-iresourcebuilder-documentdbserverresource-documentdbversion) -- last call wins. ## Examples ```csharp var server = builder.AddDocumentDB("documentdb") .WithPostgresVersion(DocumentDBPostgresVersion.Pg16) .WithDocumentDBVersion(DocumentDBVersion.V0_110_0); // -> image tag "pg16-0.110.0" ``` ## WithTelemetry(IResourceBuilder, bool) - Name: `WithTelemetry(IResourceBuilder, bool)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L363-L368) Enables or disables DocumentDB Local telemetry. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithTelemetry( this IResourceBuilder builder, bool enabled = true) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `enabled` (`bool`) `optional` Whether telemetry should be enabled. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## WithTlsCertificate(IResourceBuilder, string, string) - Name: `WithTlsCertificate(IResourceBuilder, string, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/microsoft/azure-databases-aspire/blob/d8d44d4322ce04a98c27e15113a2ecacf12152d8//home/runner/work/azure-databases-aspire/azure-databases-aspire/src/Aspire.Hosting.DocumentDB/DocumentDBBuilderExtensions.cs#L338-L352) Mounts a custom TLS certificate and key into the DocumentDB Local container. ```csharp public static class DocumentDBBuilderExtensions { public static IResourceBuilder WithTlsCertificate( this IResourceBuilder builder, string certPath, string keyPath) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder for DocumentDB. - `certPath` (`string`) The certificate file to mount into the container. - `keyPath` (`string`) The private key file to mount into the container. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks The certificate and key files are mounted at distinct container paths so that they do not collide even if their host file names are identical.