# AzureCosmosExtensions Methods

- Package: [Aspire.Hosting.Azure.CosmosDB](/reference/api/csharp/aspire.hosting.azure.cosmosdb.md)
- Type: [AzureCosmosExtensions](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions.md)
- Kind: `Methods`
- Members: `14`

Extension methods for adding Azure Cosmos DB resources to the application model.

## AddAzureCosmosDB(IDistributedApplicationBuilder, string)

- Name: `AddAzureCosmosDB(IDistributedApplicationBuilder, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L39-L46)

Adds an Azure Cosmos DB connection to the application model.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> AddAzureCosmosDB(
        this IDistributedApplicationBuilder builder,
        string name)
    {
        // ...
    }
}
```

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

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddContainer(IResourceBuilder<AzureCosmosDBDatabaseResource>, string, string, string?)

- Name: `AddContainer(IResourceBuilder<AzureCosmosDBDatabaseResource>, string, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L350-L360)

Adds a container to the associated Cosmos DB database resource.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBContainerResource> AddContainer(
        this IResourceBuilder<AzureCosmosDBDatabaseResource> builder,
        string name,
        string partitionKeyPath,
        string? containerName = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBDatabaseResource>`)
  CosmosDBDatabase resource builder.
- `name` (`string`)
  Name of container resource.
- `partitionKeyPath` (`string`)
  Partition key path for the container.
- `containerName` (`string?`) `optional`
  The name of the container. If not provided, this defaults to the same value as `name`.

## Returns

`IResourceBuilder<AzureCosmosDBContainerResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## AddContainer(IResourceBuilder<AzureCosmosDBDatabaseResource>, string, IEnumerable<string>, string?)

- Name: `AddContainer(IResourceBuilder<AzureCosmosDBDatabaseResource>, string, IEnumerable<string>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L396-L417)

Adds a container to the associated Cosmos DB database resource with hierarchical partition keys.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBContainerResource> AddContainer(
        this IResourceBuilder<AzureCosmosDBDatabaseResource> builder,
        string name,
        IEnumerable<string> partitionKeyPaths,
        string? containerName = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBDatabaseResource>`)
  CosmosDBDatabase resource builder.
- `name` (`string`)
  Name of container resource.
- `partitionKeyPaths` (`IEnumerable<string>`)
  Hierarchical partition key paths for the container.
- `containerName` (`string?`) `optional`
  The name of the container. If not provided, this defaults to the same value as `name`.

## Returns

`IResourceBuilder<AzureCosmosDBContainerResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## AddCosmosDatabase(IResourceBuilder<AzureCosmosDBResource>, string, string?)

- Name: `AddCosmosDatabase(IResourceBuilder<AzureCosmosDBResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBDatabaseResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L327-L336)

Adds a database to the associated Cosmos DB account resource.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBDatabaseResource> AddCosmosDatabase(
        this IResourceBuilder<AzureCosmosDBResource> builder,
        string name,
        string? databaseName = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  AzureCosmosDB resource builder.
- `name` (`string`)
  The name of the database resource.
- `databaseName` (`string?`) `optional`
  The name of the database. If not provided, this defaults to the same value as `name`.

## Returns

`IResourceBuilder<AzureCosmosDBDatabaseResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddDatabase(IResourceBuilder<AzureCosmosDBResource>, string)

> **Obsolete:** This method is obsolete because it has the wrong return type and will be removed in a future version. Use AddCosmosDatabase instead to add a Cosmos DB database.

- Name: `AddDatabase(IResourceBuilder<AzureCosmosDBResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L308-L313)

Adds a database to the associated Cosmos DB account resource.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> AddDatabase(
        this IResourceBuilder<AzureCosmosDBResource> builder,
        string databaseName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  AzureCosmosDB resource builder.
- `databaseName` (`string`)
  Name of database.

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts. Use [AzureCosmosExtensions.AddCosmosDatabase(IResourceBuilder<AzureCosmosDBResource>, string, string?)](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods.md#addcosmosdatabase-iresourcebuilder-azurecosmosdbresource-string-string) instead.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## RunAsEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)

- Name: `RunAsEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L65)

Configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB emulator with the NoSQL API. This resource requires an [AzureCosmosDBResource](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosdbresource.md) to be added to the application model. For more information on the Azure Cosmos DB emulator, see [https://learn.microsoft.com/azure/cosmos-db/emulator#authentication](https://learn.microsoft.com/azure/cosmos-db/emulator#authentication).

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> RunAsEmulator(
        this IResourceBuilder<AzureCosmosDBResource> builder,
        Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>? configureContainer = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  The Azure Cosmos DB resource builder.
- `configureContainer` (`Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>`) `optional`
  Callback that exposes underlying container used for emulation to allow for customization.

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

When using the Azure Cosmos DB emulator, the container requires a TLS/SSL certificate. For more information, see [https://learn.microsoft.com/azure/cosmos-db/how-to-develop-emulator?tabs=docker-linux#export-the-emulators-tlsssl-certificate](https://learn.microsoft.com/azure/cosmos-db/how-to-develop-emulator?tabs=docker-linux#export-the-emulators-tlsssl-certificate). This version of the package defaults to the tag of the / container image.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## RunAsPreviewEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)

> **Experimental:** ASPIRECOSMOSDB001 - [Learn more](/diagnostics/aspirecosmosdb001/)

- Name: `RunAsPreviewEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L82)

Configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB Linux-based emulator (preview) with the NoSQL API. This resource requires an [AzureCosmosDBResource](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosdbresource.md) to be added to the application model. For more information on the Azure Cosmos DB emulator, see [https://learn.microsoft.com/azure/cosmos-db/emulator-linux](https://learn.microsoft.com/azure/cosmos-db/emulator-linux).

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> RunAsPreviewEmulator(
        this IResourceBuilder<AzureCosmosDBResource> builder,
        Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>? configureContainer = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  The Azure Cosmos DB resource builder.
- `configureContainer` (`Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>`) `optional`
  Callback that exposes underlying container used for emulation to allow for customization.

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

This version of the package defaults to the tag of the / container image.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithAccessKeyAuthentication(IResourceBuilder<AzureCosmosDBResource>)

- Name: `WithAccessKeyAuthentication(IResourceBuilder<AzureCosmosDBResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L508-L527)

Configures the resource to use access key authentication with Azure Cosmos DB.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> WithAccessKeyAuthentication(
        this IResourceBuilder<AzureCosmosDBResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  The Azure Cosmos DB resource builder.

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` builder.

## Remarks

The following example creates an Azure Cosmos DB resource that uses access key authentication.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var cosmosdb = builder.AddAzureCosmosDB("cache")
    .WithAccessKeyAuthentication();

builder.AddProject<Projects.ProductService>()
    .WithReference(cosmosdb);

builder.Build().Run();
```

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## WithAccessKeyAuthentication(IResourceBuilder<AzureCosmosDBResource>, IResourceBuilder<IAzureKeyVaultResource>)

- Name: `WithAccessKeyAuthentication(IResourceBuilder<AzureCosmosDBResource>, IResourceBuilder<IAzureKeyVaultResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L554-L571)

Configures the resource to use access key authentication with Azure Cosmos DB.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> WithAccessKeyAuthentication(
        this IResourceBuilder<AzureCosmosDBResource> builder,
        IResourceBuilder<IAzureKeyVaultResource> keyVaultBuilder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  The Azure Cosmos DB resource builder.
- `keyVaultBuilder` (`IResourceBuilder<IAzureKeyVaultResource>`)
  The Azure Key Vault resource builder where the connection string used to connect to this AzureCosmosDBResource will be stored.

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` builder.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## WithDataExplorer(IResourceBuilder<AzureCosmosDBEmulatorResource>, int?)

> **Experimental:** ASPIRECOSMOSDB001 - [Learn more](/diagnostics/aspirecosmosdb001/)

- Name: `WithDataExplorer(IResourceBuilder<AzureCosmosDBEmulatorResource>, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBEmulatorResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L446-L481)

Configures the Azure Cosmos DB preview emulator to expose the Data Explorer endpoint.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithDataExplorer(
        this IResourceBuilder<AzureCosmosDBEmulatorResource> builder,
        int? port = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBEmulatorResource>`)
  Builder for the Cosmos emulator container
- `port` (`int?`) `optional`
  Optional host port to bind the Data Explorer to.

## Returns

`IResourceBuilder<AzureCosmosDBEmulatorResource>` -- Cosmos emulator resource builder.

## Remarks

The Data Explorer is only available with [AzureCosmosExtensions.RunAsPreviewEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosextensions/methods.md#runaspreviewemulator-iresourcebuilder-azurecosmosdbresource-action-iresourcebuilder-azurecosmosdbemulatorresource).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDataVolume(IResourceBuilder<AzureCosmosDBEmulatorResource>, string?)

- Name: `WithDataVolume(IResourceBuilder<AzureCosmosDBEmulatorResource>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBEmulatorResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L245-L250)

Adds a named volume for the data folder to an Azure Cosmos DB emulator resource.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithDataVolume(
        this IResourceBuilder<AzureCosmosDBEmulatorResource> builder,
        string? name = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBEmulatorResource>`)
  The builder for the [AzureCosmosDBEmulatorResource](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosdbemulatorresource.md).
- `name` (`string?`) `optional`
  The name of the volume. Defaults to an auto-generated name based on the application and resource names.

## Returns

`IResourceBuilder<AzureCosmosDBEmulatorResource>` -- A builder for the [AzureCosmosDBEmulatorResource](/reference/api/csharp/aspire.hosting.azure.cosmosdb/azurecosmosdbemulatorresource.md).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDefaultAzureSku(IResourceBuilder<AzureCosmosDBResource>)

- Name: `WithDefaultAzureSku(IResourceBuilder<AzureCosmosDBResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L429-L430)

Configures the Azure Cosmos DB resource to be deployed use the default SKU provided by Azure.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBResource> WithDefaultAzureSku(
        this IResourceBuilder<AzureCosmosDBResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBResource>`)
  The builder for the Azure Cosmos DB resource.

## Returns

`IResourceBuilder<AzureCosmosDBResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithGatewayPort(IResourceBuilder<AzureCosmosDBEmulatorResource>, int?)

- Name: `WithGatewayPort(IResourceBuilder<AzureCosmosDBEmulatorResource>, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBEmulatorResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L262-L267)

Configures the gateway port for the Azure Cosmos DB emulator.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithGatewayPort(
        this IResourceBuilder<AzureCosmosDBEmulatorResource> builder,
        int? port)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBEmulatorResource>`)
  Builder for the Cosmos emulator container
- `port` (`int?`)
  Host port to bind to the emulator gateway port.

## Returns

`IResourceBuilder<AzureCosmosDBEmulatorResource>` -- Cosmos emulator resource builder.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithPartitionCount(IResourceBuilder<AzureCosmosDBEmulatorResource>, int)

- Name: `WithPartitionCount(IResourceBuilder<AzureCosmosDBEmulatorResource>, int)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<AzureCosmosDBEmulatorResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/cbc352350f1a9bafbaff10d14a2c8de4ac186a48/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L282-L294)

Configures the partition count for the Azure Cosmos DB emulator.

```csharp
public static class AzureCosmosExtensions
{
    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithPartitionCount(
        this IResourceBuilder<AzureCosmosDBEmulatorResource> builder,
        int count)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCosmosDBEmulatorResource>`)
  Builder for the Cosmos emulator container
- `count` (`int`)
  Desired partition count.

## Returns

`IResourceBuilder<AzureCosmosDBEmulatorResource>` -- Cosmos emulator resource builder.

## Remarks

Not calling this method will result in the default of 10 partitions. The actual started partitions is always one more than specified. See [this documentation](https://learn.microsoft.com/azure/cosmos-db/emulator-windows-arguments#change-the-number-of-default-containers) about setting the partition count.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.