DocumentDBBuilderExtensions Methods

AddDatabase(IResourceBuilder<DocumentDBServerResource>, string, string?) extension IResourceBuilder<DocumentDBDatabaseResource>

Adds a DocumentDB database to the application model.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBDatabaseResource> AddDatabase(
        this IResourceBuilder<DocumentDBServerResource> builder,
        string name,
        string? databaseName = null)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L143-L172

Parameters

builder IResourceBuilder<DocumentDBServerResource> 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<DocumentDBDatabaseResource> 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

var server = builder.AddDocumentDB("documentdb");
var ordersDb = server.AddDatabase("orders");
var usersDb = server.AddDatabase("users");

AddDocumentDB(IDistributedApplicationBuilder, string, int?) extension IResourceBuilder<DocumentDBServerResource>

Adds a DocumentDB resource to the application model. A container is used for local development.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> AddDocumentDB(
        this IDistributedApplicationBuilder builder,
        string name,
        int? port)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L53

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<DocumentDBServerResource> 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

var server = builder.AddDocumentDB("documentdb", port: 10260);

AddDocumentDB(IDistributedApplicationBuilder, string, int?, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>)

extension IResourceBuilder<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)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L82-L117

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<ParameterResource> optional A parameter that contains the DocumentDB server user name, or null to use a default value.

password IResourceBuilder<ParameterResource> optional A 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) extension IResourceBuilder<DocumentDBServerResource>

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.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> AllowInsecureTls(
        this IResourceBuilder<DocumentDBServerResource> builder,
        bool allowInsecureTls = true)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L435-L438

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

allowInsecureTls bool optional Whether to allow insecure TLS. Defaults to true.

Returns

IResourceBuilder<DocumentDBServerResource> 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

// Require valid certificates (for example, production with real certs):
var server = builder.AddDocumentDB("documentdb")
                    .AllowInsecureTls(false);

UseTls(IResourceBuilder<DocumentDBServerResource>, bool) extension IResourceBuilder<DocumentDBServerResource>

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.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> UseTls(
        this IResourceBuilder<DocumentDBServerResource> builder,
        bool useTls = true)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L406-L409

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

useTls bool optional Whether to enable TLS. Defaults to true.

Returns

IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

Examples

// Disable TLS for a non-TLS endpoint:
var server = builder.AddDocumentDB("documentdb")
                    .UseTls(false);

WithDataBindMount(IResourceBuilder<DocumentDBServerResource>, string, bool) extension IResourceBuilder<DocumentDBServerResource>

Adds a bind mount for the data folder to a DocumentDB container resource.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithDataBindMount(
        this IResourceBuilder<DocumentDBServerResource> builder,
        string source,
        bool isReadOnly = false)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L257-L267

Parameters

builder IResourceBuilder<DocumentDBServerResource> 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<DocumentDBServerResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Prefer DocumentDBBuilderExtensions.WithDataVolume 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

var server = builder.AddDocumentDB("documentdb")
                    .WithDataBindMount("./data/documentdb");

WithDataVolume(IResourceBuilder<DocumentDBServerResource>, string?, bool, string?) extension IResourceBuilder<DocumentDBServerResource>

Adds a named volume for the data folder to a DocumentDB container resource.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithDataVolume(
        this IResourceBuilder<DocumentDBServerResource> builder,
        string? name = null,
        bool isReadOnly = false,
        string? targetPath = null)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L223-L232

Parameters

builder IResourceBuilder<DocumentDBServerResource> 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<DocumentDBServerResource> 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

var server = builder.AddDocumentDB("documentdb")
                    .WithDataVolume();

WithDocumentDBVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBVersion) extension IResourceBuilder<DocumentDBServerResource>

Pins the DocumentDB version to a specific release known to this build of the package.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithDocumentDBVersion(
        this IResourceBuilder<DocumentDBServerResource> builder,
        DocumentDBVersion version)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L483-L486

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

version DocumentDBVersion The 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?) extension IResourceBuilder<DocumentDBServerResource>

Configures the host port that the DocumentDB resource is exposed on instead of using randomly assigned port.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithHostPort(
        this IResourceBuilder<DocumentDBServerResource> builder,
        int? port)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L189-L194

Parameters

builder IResourceBuilder<DocumentDBServerResource> 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<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

Examples

var server = builder.AddDocumentDB("documentdb")
                    .WithHostPort(10260);

WithInitData(IResourceBuilder<DocumentDBServerResource>, string) extension IResourceBuilder<DocumentDBServerResource>

Mounts custom initialization scripts into the DocumentDB Local container.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithInitData(
        this IResourceBuilder<DocumentDBServerResource> builder,
        string source)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L298-L307

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

source string The source directory on the host to mount into the container.

Returns

IResourceBuilder<DocumentDBServerResource> 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<DocumentDBServerResource>, DocumentDBLogLevel) extension IResourceBuilder<DocumentDBServerResource>

Configures the DocumentDB Local container log level.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithLogLevel(
        this IResourceBuilder<DocumentDBServerResource> builder,
        DocumentDBLogLevel logLevel)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L278-L283

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

logLevel DocumentDBLogLevel The log level to configure.

Returns

IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

WithoutSampleData(IResourceBuilder<DocumentDBServerResource>) extension IResourceBuilder<DocumentDBServerResource>

Disables the built-in sample data initialization performed by the DocumentDB Local container.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithoutSampleData(
        this IResourceBuilder<DocumentDBServerResource> builder)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L317-L322

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

Returns

IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

WithOwner(IResourceBuilder<DocumentDBServerResource>, string) extension IResourceBuilder<DocumentDBServerResource>

Configures the owner used by the DocumentDB Local container.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithOwner(
        this IResourceBuilder<DocumentDBServerResource> builder,
        string owner)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L380-L386

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

owner string The owner value to configure.

Returns

IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

WithPostgresVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBPostgresVersion) extension IResourceBuilder<DocumentDBServerResource>

Selects the PostgreSQL backend variant of the documentdb-local container image.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithPostgresVersion(
        this IResourceBuilder<DocumentDBServerResource> builder,
        DocumentDBPostgresVersion pgVersion)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L524-L539

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

pgVersion DocumentDBPostgresVersion The PostgreSQL backend variant to use.

Returns

IResourceBuilder<DocumentDBServerResource> 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. 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) extension IResourceBuilder<DocumentDBServerResource>

Enables or disables DocumentDB Local telemetry.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithTelemetry(
        this IResourceBuilder<DocumentDBServerResource> builder,
        bool enabled = true)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L363-L368

Parameters

builder IResourceBuilder<DocumentDBServerResource> The resource builder for DocumentDB.

enabled bool optional Whether telemetry should be enabled.

Returns

IResourceBuilder<DocumentDBServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

WithTlsCertificate(IResourceBuilder<DocumentDBServerResource>, string, string) extension IResourceBuilder<DocumentDBServerResource>

Mounts a custom TLS certificate and key into the DocumentDB Local container.

public static class DocumentDBBuilderExtensions
{
    public static IResourceBuilder<DocumentDBServerResource> WithTlsCertificate(
        this IResourceBuilder<DocumentDBServerResource> builder,
        string certPath,
        string keyPath)
    {
        // ...
    }
}

DocumentDBBuilderExtensions.cs#L338-L352

Parameters

builder IResourceBuilder<DocumentDBServerResource> 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<DocumentDBServerResource> 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.