GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

azure-resource-manager-cosmosdb-dotnet

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

Ciza · 0 points · 20 views 0 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-dotnet_skills_azure-resource-manager-cosmosdb-dotnet-e58528d.zip · 9 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-dotnet/skills/azure-resource-manager-cosmosdb-dotnet
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git git clone https://github.com/microsoft/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

Type Purpose
ArmClient Entry point for all ARM operations
CosmosDBAccountResource Represents a Cosmos DB account
CosmosDBAccountCollection Collection for account CRUD
CosmosDBSqlDatabaseResource SQL API database
CosmosDBSqlContainerResource SQL API container
CosmosDBAccountCreateOrUpdateContent Account creation payload
CosmosDBSqlDatabaseCreateOrUpdateContent Database creation payload
CosmosDBSqlContainerCreateOrUpdateContent Container creation payload
ThroughputSettingsUpdateData Throughput 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

File When to Read
references/account-management.md Account CRUD, failover, keys, connection strings, networking
references/sql-resources.md SQL databases, containers, stored procedures, triggers, UDFs
references/throughput.md Manual/autoscale throughput, migration between modes

Related SDKs

SDK Purpose Install
Microsoft.Azure.Cosmos Data plane (document CRUD, queries) dotnet add package Microsoft.Azure.Cosmos
Azure.ResourceManager.CosmosDB Management plane (this SDK) dotnet add package Azure.ResourceManager.CosmosDB
Files (skills)
  • references
    • account-management.md 7.3 KB
      Loading…
    • sql-resources.md 9.7 KB
      Loading…
    • throughput.md 7.7 KB
      Loading…
  • SKILL.md 8.4 KB
    ---
    name: azure-resource-manager-cosmosdb-dotnet
    description: |
      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".
    license: MIT
    metadata:
      author: Microsoft
      version: "1.0.0"
      package: Azure.ResourceManager.CosmosDB
    ---
    
    # 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
    
    ```bash
    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
    
    ```bash
    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
    
    ```csharp
    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
    
    ```csharp
    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
    
    ```csharp
    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
    
    ```csharp
    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
    
    ```csharp
    // 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
    
    ```csharp
    // 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
    
    | Type | Purpose |
    |------|---------|
    | `ArmClient` | Entry point for all ARM operations |
    | `CosmosDBAccountResource` | Represents a Cosmos DB account |
    | `CosmosDBAccountCollection` | Collection for account CRUD |
    | `CosmosDBSqlDatabaseResource` | SQL API database |
    | `CosmosDBSqlContainerResource` | SQL API container |
    | `CosmosDBAccountCreateOrUpdateContent` | Account creation payload |
    | `CosmosDBSqlDatabaseCreateOrUpdateContent` | Database creation payload |
    | `CosmosDBSqlContainerCreateOrUpdateContent` | Container creation payload |
    | `ThroughputSettingsUpdateData` | Throughput 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
    
    ```csharp
    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
    
    | File | When to Read |
    |------|--------------|
    | [references/account-management.md](references/account-management.md) | Account CRUD, failover, keys, connection strings, networking |
    | [references/sql-resources.md](references/sql-resources.md) | SQL databases, containers, stored procedures, triggers, UDFs |
    | [references/throughput.md](references/throughput.md) | Manual/autoscale throughput, migration between modes |
    
    ## Related SDKs
    
    | SDK | Purpose | Install |
    |-----|---------|---------|
    | `Microsoft.Azure.Cosmos` | Data plane (document CRUD, queries) | `dotnet add package Microsoft.Azure.Cosmos` |
    | `Azure.ResourceManager.CosmosDB` | Management plane (this SDK) | `dotnet add package Azure.ResourceManager.CosmosDB` |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.