Generated banner for Azure Resource Manager Cosmosdb Dotnet
Generated logo for Azure Resource Manager Cosmosdb Dotnet

Azure Resource Manager Cosmosdb Dotnet

MicrosoftOfficialCreated by Microsoft

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MIT
  • No issues found

From the author

Azure Resource Manager SDK for Cosmos DB in .NET. Use for MANAGEMENT PLANE operations: creating/managing Cosmos DB accounts, databases, containers, throughput settings, and RBAC via Azure Resource Manager. NOT for data plane operations (CRUD on documents) - use Microsoft.Azure.Cosmos for that. Triggers: "Cosmos DB account", "create Cosmos account", "manage Cosmos resources", "ARM Cosmos", "CosmosDBAccountResource", "provision Cosmos DB".
— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Azure.ResourceManager.CosmosDB SDK provides a .NET interface for management plane operations on Azure Cosmos DB. It allows developers to automate the provisioning and configuration of Cosmos DB accounts, databases, and containers, as well as manage throughput settings and RBAC configurations. This SDK is strictly for infrastructure management and should not be used for data plane operations like document CRUD or query execution.

What it does

  • Provision and configure Cosmos DB accounts with specific consistency and failover policies.
  • Create and manage SQL API databases and containers.
  • Configure manual or autoscale throughput settings for databases and containers.
  • Retrieve account keys and connection strings for application integration.
  • Manage indexing policies, partition keys, and hierarchical partitioning.
  • Perform lifecycle operations including updating and deleting Cosmos DB resources.

When to use it

  • When automating infrastructure-as-code deployments for Cosmos DB.
  • When you need to programmatically scale throughput or modify container settings.
  • When managing multiple Cosmos DB accounts across different resource groups or subscriptions.
  • When setting up environment-specific database configurations in a CI/CD pipeline.

Advantages

  • Native .NET integration for seamless infrastructure management.
  • Strongly typed models for complex resource configurations.
  • Supports long-running operations with built-in wait mechanisms.
  • Enables programmatic enforcement of infrastructure standards and policies.

Usage examples

“How do I create a new Cosmos DB account using the .NET SDK?”
The agent provides a code snippet using CosmosDBAccountCreateOrUpdateContent to define the account settings and calls CreateOrUpdateAsync on the account collection.
“Show me how to update throughput for an existing SQL container.”
The agent demonstrates using ThroughputSettingsUpdateData to set either manual or autoscale throughput and applying it via the container resource.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/microsoft/azure-resource-manager-cosmosdb-dotnet/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip azure-resource-manager-cosmosdb-dotnet.zip -d .agents/skills

Documentation by Microsoft

Azure.ResourceManager.CosmosDB (.NET)

Management plane SDK for provisioning and managing Azure Cosmos DB resources via Azure Resource Manager.

⚠️ Management vs Data Plane

  • This SDK (Azure.ResourceManager.CosmosDB): Create accounts, databases, containers, configure throughput, manage RBAC

  • Data Plane SDK (Microsoft.Azure.Cosmos): CRUD operations on documents, queries, stored procedures execution

Installation

dotnet add package Azure.ResourceManager.CosmosDB
dotnet add package Azure.Identity

Current Versions: Stable v1.4.0, Preview v1.4.0-beta.13

Environment Variables

AZURE_SUBSCRIPTION_ID=<your-subscription-id> # Required: Azure subscription ID
AZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production
AZURE_TENANT_ID=<tenant-id> # For service principal auth (optional)
AZURE_CLIENT_ID=<client-id> # For service principal auth (optional)
AZURE_CLIENT_SECRET=<client-secret> # For service principal auth (optional)

Authentication

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.CosmosDB;

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
var armClient = new ArmClient(credential);

// Get subscription
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var subscription = armClient.GetSubscriptionResource(
    new ResourceIdentifier($"/subscriptions/{subscriptionId}"));

Resource Hierarchy

ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── CosmosDBAccountResource
            ├── CosmosDBSqlDatabaseResource
            │   └── CosmosDBSqlContainerResource
            │       ├── CosmosDBSqlStoredProcedureResource
            │       ├── CosmosDBSqlTriggerResource
            │       └── CosmosDBSqlUserDefinedFunctionResource
            ├── CassandraKeyspaceResource
            ├── GremlinDatabaseResource
            ├── MongoDBDatabaseResource
            └── CosmosDBTableResource

Core Workflow

1. Create Cosmos DB Account
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;

// Get resource group
var resourceGroup = await subscription
    .GetResourceGroupAsync("my-resource-group");

// Define account
var accountData = new CosmosDBAccountCreateOrUpdateContent(
    location: AzureLocation.EastUS,
    locations: new[]
    {
        new CosmosDBAccountLocation
        {
            LocationName = AzureLocation.EastUS,
            FailoverPriority = 0,
            IsZoneRedundant = false
        }
    })
{
    Kind = CosmosDBAccountKind.GlobalDocumentDB,
    ConsistencyPolicy = new ConsistencyPolicy(DefaultConsistencyLevel.Session),
    EnableAutomaticFailover = true
};

// Create account (long-running operation)
var accountCollection = resourceGroup.Value.GetCosmosDBAccounts();
var operation = await accountCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-cosmos-account",
    accountData);

CosmosDBAccountResource account = operation.Value;
2. Create SQL Database
var databaseData = new CosmosDBSqlDatabaseCreateOrUpdateContent(
    new CosmosDBSqlDatabaseResourceInfo("my-database"));

var databaseCollection = account.GetCosmosDBSqlDatabases();
var dbOperation = await databaseCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-database",
    databaseData);

CosmosDBSqlDatabaseResource database = dbOperation.Value;
3. Create SQL Container
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/partitionKey" },
            Kind = CosmosDBPartitionKind.Hash
        },
        IndexingPolicy = new CosmosDBIndexingPolicy
        {
            Automatic = true,
            IndexingMode = CosmosDBIndexingMode.Consistent
        },
        DefaultTtl = 86400 // 24 hours
    });

var containerCollection = database.GetCosmosDBSqlContainers();
var containerOperation = await containerCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-container",
    containerData);

CosmosDBSqlContainerResource container = containerOperation.Value;
4. Configure Throughput
// Manual throughput
var throughputData = new ThroughputSettingsUpdateData(
    new ThroughputSettingsResourceInfo
    {
        Throughput = 400
    });

// Autoscale throughput
var autoscaleData = new ThroughputSettingsUpdateData(
    new ThroughputSettingsResourceInfo
    {
        AutoscaleSettings = new AutoscaleSettingsResourceInfo
        {
            MaxThroughput = 4000
        }
    });

// Apply to database
await database.CreateOrUpdateCosmosDBSqlDatabaseThroughputAsync(
    WaitUntil.Completed,
    throughputData);
5. Get Connection Information
// Get keys
var keys = await account.GetKeysAsync();
Console.WriteLine($"Primary Key: {keys.Value.PrimaryMasterKey}");

// Get connection strings
var connectionStrings = await account.GetConnectionStringsAsync();
foreach (var cs in connectionStrings.Value.ConnectionStrings)
{
    Console.WriteLine($"{cs.Description}: {cs.ConnectionString}");
}

Key Types Reference

TypePurpose
ArmClientEntry point for all ARM operations
CosmosDBAccountResourceRepresents a Cosmos DB account
CosmosDBAccountCollectionCollection for account CRUD
CosmosDBSqlDatabaseResourceSQL API database
CosmosDBSqlContainerResourceSQL API container
CosmosDBAccountCreateOrUpdateContentAccount creation payload
CosmosDBSqlDatabaseCreateOrUpdateContentDatabase creation payload
CosmosDBSqlContainerCreateOrUpdateContentContainer creation payload
ThroughputSettingsUpdateDataThroughput configuration

Best Practices

  1. Use WaitUntil.Completed for operations that must finish before proceeding

  2. Use WaitUntil.Started when you want to poll manually or run operations in parallel

  3. Use DefaultAzureCredential — never hardcode keys

  4. Handle RequestFailedException for ARM API errors

  5. Use CreateOrUpdateAsync for idempotent operations

  6. Navigate hierarchy via Get* methods (e.g., account.GetCosmosDBSqlDatabases())

Error Handling

using Azure;

try
{
    var operation = await accountCollection.CreateOrUpdateAsync(
        WaitUntil.Completed, accountName, accountData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("Account already exists");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

Reference Files

FileWhen to Read
references/account-management.mdAccount CRUD, failover, keys, connection strings, networking
references/sql-resources.mdSQL databases, containers, stored procedures, triggers, UDFs
references/throughput.mdManual/autoscale throughput, migration between modes
SDKPurposeInstall
Microsoft.Azure.CosmosData plane (document CRUD, queries)dotnet add package Microsoft.Azure.Cosmos
Azure.ResourceManager.CosmosDBManagement plane (this SDK)dotnet add package Azure.ResourceManager.CosmosDB

Files

references/sql-resources.md

SQL API Resources

Patterns for managing SQL (Core) API databases, containers, and programmability objects.

SQL Database Operations

Create Database
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;

var databaseData = new CosmosDBSqlDatabaseCreateOrUpdateContent(
    new CosmosDBSqlDatabaseResourceInfo("my-database"));

var databaseCollection = account.GetCosmosDBSqlDatabases();
var operation = await databaseCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-database",
    databaseData);

CosmosDBSqlDatabaseResource database = operation.Value;
Create Database with Shared Throughput
var databaseData = new CosmosDBSqlDatabaseCreateOrUpdateContent(
    new CosmosDBSqlDatabaseResourceInfo("my-database"))
{
    Options = new CosmosDBCreateUpdateConfig
    {
        Throughput = 400  // Shared across containers
    }
};

// Or with autoscale
var databaseData = new CosmosDBSqlDatabaseCreateOrUpdateContent(
    new CosmosDBSqlDatabaseResourceInfo("my-database"))
{
    Options = new CosmosDBCreateUpdateConfig
    {
        AutoscaleSettings = new AutoscaleSettings
        {
            MaxThroughput = 4000
        }
    }
};
List Databases
await foreach (var db in account.GetCosmosDBSqlDatabases())
{
    Console.WriteLine($"Database: {db.Data.Name}");
    Console.WriteLine($"  Resource ID: {db.Data.Resource.DatabaseName}");
}
Delete Database
var database = await account.GetCosmosDBSqlDatabaseAsync("my-database");
await database.Value.DeleteAsync(WaitUntil.Completed);

SQL Container Operations

Create Container with Partition Key
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/tenantId" },
            Kind = CosmosDBPartitionKind.Hash,
            Version = 2  // Use V2 for hierarchical partition keys
        }
    });

var containerCollection = database.GetCosmosDBSqlContainers();
var operation = await containerCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-container",
    containerData);
Hierarchical Partition Key (V2)
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/tenantId", "/userId", "/sessionId" },
            Kind = CosmosDBPartitionKind.MultiHash,
            Version = 2
        }
    });
Create Container with Indexing Policy
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/partitionKey" },
            Kind = CosmosDBPartitionKind.Hash
        },
        IndexingPolicy = new CosmosDBIndexingPolicy
        {
            Automatic = true,
            IndexingMode = CosmosDBIndexingMode.Consistent,
            
            // Include paths
            IncludedPaths =
            {
                new CosmosDBIncludedPath { Path = "/*" }
            },
            
            // Exclude paths
            ExcludedPaths =
            {
                new CosmosDBExcludedPath { Path = "/largeTextField/*" },
                new CosmosDBExcludedPath { Path = "/_etag/?" }
            },
            
            // Composite indexes for ORDER BY on multiple fields
            CompositeIndexes =
            {
                new CosmosDBCompositePath[]
                {
                    new() { Path = "/name", Order = CompositePathSortOrder.Ascending },
                    new() { Path = "/timestamp", Order = CompositePathSortOrder.Descending }
                }
            },
            
            // Spatial indexes
            SpatialIndexes =
            {
                new SpatialSpec
                {
                    Path = "/location/*",
                    Types = { SpatialType.Point, SpatialType.Polygon }
                }
            }
        }
    });
Create Container with TTL
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/partitionKey" },
            Kind = CosmosDBPartitionKind.Hash
        },
        // Default TTL in seconds (-1 = off, 0 = on but no default, >0 = default seconds)
        DefaultTtl = 86400  // 24 hours
    });
Create Container with Unique Keys
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/tenantId" },
            Kind = CosmosDBPartitionKind.Hash
        },
        UniqueKeys = new CosmosDBUniqueKeyPolicy
        {
            UniqueKeys =
            {
                new CosmosDBUniqueKey
                {
                    Paths = { "/email" }
                },
                new CosmosDBUniqueKey
                {
                    Paths = { "/department", "/employeeId" }
                }
            }
        }
    });
Create Container with Dedicated Throughput
var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
    new CosmosDBSqlContainerResourceInfo("my-container")
    {
        PartitionKey = new CosmosDBContainerPartitionKey
        {
            Paths = { "/partitionKey" },
            Kind = CosmosDBPartitionKind.Hash
        }
    })
{
    Options = new CosmosDBCreateUpdateConfig
    {
        Throughput = 1000  // Dedicated to this container
    }
};
List Containers
await foreach (var container in database.GetCosmosDBSqlContainers())
{
    Console.WriteLine($"Container: {container.Data.Name}");
    Console.WriteLine($"  Partition Key: {string.Join(", ", container.Data.Resource.PartitionKey.Paths)}");
    Console.WriteLine($"  Default TTL: {container.Data.Resource.DefaultTtl}");
}
Delete Container
var container = await database.GetCosmosDBSqlContainerAsync("my-container");
await container.Value.DeleteAsync(WaitUntil.Completed);

Stored Procedures

Create Stored Procedure
var sprocData = new CosmosDBSqlStoredProcedureCreateOrUpdateContent(
    new CosmosDBSqlStoredProcedureResourceInfo("bulkDelete")
    {
        Body = @"
function bulkDelete(query) {
    var context = getContext();
    var container = context.getCollection();
    var response = context.getResponse();
    var deleted = 0;
    
    var accepted = container.queryDocuments(
        container.getSelfLink(),
        query,
        function(err, docs) {
            if (err) throw err;
            docs.forEach(function(doc) {
                container.deleteDocument(doc._self);
                deleted++;
            });
            response.setBody({ deleted: deleted });
        }
    );
    
    if (!accepted) {
        response.setBody({ deleted: deleted, continuation: true });
    }
}"
    });

var sprocCollection = container.GetCosmosDBSqlStoredProcedures();
await sprocCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "bulkDelete",
    sprocData);
List Stored Procedures
await foreach (var sproc in container.GetCosmosDBSqlStoredProcedures())
{
    Console.WriteLine($"Stored Procedure: {sproc.Data.Name}");
}

Triggers

Create Trigger
var triggerData = new CosmosDBSqlTriggerCreateOrUpdateContent(
    new CosmosDBSqlTriggerResourceInfo("validateDocument")
    {
        Body = @"
function validateDocument() {
    var context = getContext();
    var request = context.getRequest();
    var doc = request.getBody();
    
    if (!doc.createdAt) {
        doc.createdAt = new Date().toISOString();
    }
    
    request.setBody(doc);
}",
        TriggerType = CosmosDBSqlTriggerType.Pre,
        TriggerOperation = CosmosDBSqlTriggerOperation.Create
    });

var triggerCollection = container.GetCosmosDBSqlTriggers();
await triggerCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "validateDocument",
    triggerData);
Trigger Types
TypeWhen
PreBefore the operation
PostAfter the operation
Trigger Operations
OperationApplies To
AllAll operations
CreateDocument creation
UpdateDocument updates
DeleteDocument deletion
ReplaceDocument replacement

User Defined Functions (UDFs)

Create UDF
var udfData = new CosmosDBSqlUserDefinedFunctionCreateOrUpdateContent(
    new CosmosDBSqlUserDefinedFunctionResourceInfo("formatCurrency")
    {
        Body = @"
function formatCurrency(amount, currency) {
    return currency + ' ' + amount.toFixed(2);
}"
    });

var udfCollection = container.GetCosmosDBSqlUserDefinedFunctions();
await udfCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "formatCurrency",
    udfData);

Partition Key Strategies

StrategyPath ExampleUse Case
Single property/tenantIdMulti-tenant apps
Synthetic key/partitionKeyComputed from multiple fields
Hierarchical/tenantId, /userIdLarge tenants with sub-partitioning
ID-based/idEven distribution, no cross-partition queries
Choosing Partition Key
  1. High cardinality — Many distinct values

  2. Even distribution — No hot partitions

  3. Query alignment — Most queries include partition key

  4. Immutable — Cannot change after document creation

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Microsoft
Publisher
Microsoft (Official)
Source
microsoft/skills · .github/plugins/azure-sdk-dotnet/skills/azure-resource-manager-cosmosdb-dotnet · commit 0696600
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download azure-resource-manager-cosmosdb-dotnet.zip