DocumentDBBuilderExtensions Methods

ClassMethods16 members

Provides extension methods for adding DocumentDB resources to an Hosting.IDistributedApplicationBuilder.

AddDatabase(IResourceBuilder<DocumentDBServerResource>, string, string?)extensionIResourceBuilder<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

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.

databaseNamestring?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

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?)extensionIResourceBuilder<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

builderIDistributedApplicationBuilderThe 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

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

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

DocumentDBBuilderExtensions.cs#L82-L117

Parameters

builderIDistributedApplicationBuilderThe 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.

userNameIResourceBuilder<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)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

allowInsecureTlsbooloptionalWhether 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)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

useTlsbooloptionalWhether 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)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder.

sourcestringThe source directory on the host to mount into the container.

isReadOnlybooloptionalA 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?)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder.

namestring?optionalThe name of the volume. Defaults to an auto-generated name based on the application and resource names.

isReadOnlybooloptionalA flag that indicates if this is a read-only volume.

targetPathstring?optionalThe 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)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

versionDocumentDBVersionThe 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?)extensionIResourceBuilder<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

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)extensionIResourceBuilder<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

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

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)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

logLevelDocumentDBLogLevelThe log level to configure.

Returns

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

WithoutSampleData(IResourceBuilder<DocumentDBServerResource>)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

Returns

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

WithOwner(IResourceBuilder<DocumentDBServerResource>, string)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

ownerstringThe owner value to configure.

Returns

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

WithPostgresVersion(IResourceBuilder<DocumentDBServerResource>, DocumentDBPostgresVersion)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

pgVersionDocumentDBPostgresVersionThe PostgreSQL backend variant to use.

Returns

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 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)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

enabledbooloptionalWhether telemetry should be enabled.

Returns

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

WithTlsCertificate(IResourceBuilder<DocumentDBServerResource>, string, string)extensionIResourceBuilder<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

builderIResourceBuilder<DocumentDBServerResource>The resource builder for DocumentDB.

certPathstringThe certificate file to mount into the container.

keyPathstringThe 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.