Azure Resource Manager Cosmosdb Dotnet

1---
2name: azure-resource-manager-cosmosdb-dotnet
3description: |
4  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".
5package: Azure.ResourceManager.CosmosDB
6---
7 
8# Azure.ResourceManager.CosmosDB (.NET)
9 
10Management plane SDK for provisioning and managing Azure Cosmos DB resources via Azure Resource Manager.
11 
12> **⚠️ Management vs Data Plane**
13> - **This SDK (Azure.ResourceManager.CosmosDB)**: Create accounts, databases, containers, configure throughput, manage RBAC
14> - **Data Plane SDK (Microsoft.Azure.Cosmos)**: CRUD operations on documents, queries, stored procedures execution
15 
16## Installation
17 
18```bash
19dotnet add package Azure.ResourceManager.CosmosDB
20dotnet add package Azure.Identity
21```
22 
23**Current Versions**: Stable v1.4.0, Preview v1.4.0-beta.13
24 
25## Environment Variables
26 
27```bash
28AZURE_SUBSCRIPTION_ID=<your-subscription-id>
29# For service principal auth (optional)
30AZURE_TENANT_ID=<tenant-id>
31AZURE_CLIENT_ID=<client-id>
32AZURE_CLIENT_SECRET=<client-secret>
33```
34 
35## Authentication
36 
37```csharp
38using Azure.Identity;
39using Azure.ResourceManager;
40using Azure.ResourceManager.CosmosDB;
41 
42// Always use DefaultAzureCredential
43var credential = new DefaultAzureCredential();
44var armClient = new ArmClient(credential);
45 
46// Get subscription
47var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
48var subscription = armClient.GetSubscriptionResource(
49    new ResourceIdentifier($"/subscriptions/{subscriptionId}"));
50```
51 
52## Resource Hierarchy
53 
54```
55ArmClient
56└── SubscriptionResource
57    └── ResourceGroupResource
58        └── CosmosDBAccountResource
59            ├── CosmosDBSqlDatabaseResource
60            │   └── CosmosDBSqlContainerResource
61            │       ├── CosmosDBSqlStoredProcedureResource
62            │       ├── CosmosDBSqlTriggerResource
63            │       └── CosmosDBSqlUserDefinedFunctionResource
64            ├── CassandraKeyspaceResource
65            ├── GremlinDatabaseResource
66            ├── MongoDBDatabaseResource
67            └── CosmosDBTableResource
68```
69 
70## Core Workflow
71 
72### 1. Create Cosmos DB Account
73 
74```csharp
75using Azure.ResourceManager.CosmosDB;
76using Azure.ResourceManager.CosmosDB.Models;
77 
78// Get resource group
79var resourceGroup = await subscription
80    .GetResourceGroupAsync("my-resource-group");
81 
82// Define account
83var accountData = new CosmosDBAccountCreateOrUpdateContent(
84    location: AzureLocation.EastUS,
85    locations: new[]
86    {
87        new CosmosDBAccountLocation
88        {
89            LocationName = AzureLocation.EastUS,
90            FailoverPriority = 0,
91            IsZoneRedundant = false
92        }
93    })
94{
95    Kind = CosmosDBAccountKind.GlobalDocumentDB,
96    ConsistencyPolicy = new ConsistencyPolicy(DefaultConsistencyLevel.Session),
97    EnableAutomaticFailover = true
98};
99 
100// Create account (long-running operation)
101var accountCollection = resourceGroup.Value.GetCosmosDBAccounts();
102var operation = await accountCollection.CreateOrUpdateAsync(
103    WaitUntil.Completed,
104    "my-cosmos-account",
105    accountData);
106 
107CosmosDBAccountResource account = operation.Value;
108```
109 
110### 2. Create SQL Database
111 
112```csharp
113var databaseData = new CosmosDBSqlDatabaseCreateOrUpdateContent(
114    new CosmosDBSqlDatabaseResourceInfo("my-database"));
115 
116var databaseCollection = account.GetCosmosDBSqlDatabases();
117var dbOperation = await databaseCollection.CreateOrUpdateAsync(
118    WaitUntil.Completed,
119    "my-database",
120    databaseData);
121 
122CosmosDBSqlDatabaseResource database = dbOperation.Value;
123```
124 
125### 3. Create SQL Container
126 
127```csharp
128var containerData = new CosmosDBSqlContainerCreateOrUpdateContent(
129    new CosmosDBSqlContainerResourceInfo("my-container")
130    {
131        PartitionKey = new CosmosDBContainerPartitionKey
132        {
133            Paths = { "/partitionKey" },
134            Kind = CosmosDBPartitionKind.Hash
135        },
136        IndexingPolicy = new CosmosDBIndexingPolicy
137        {
138            Automatic = true,
139            IndexingMode = CosmosDBIndexingMode.Consistent
140        },
141        DefaultTtl = 86400 // 24 hours
142    });
143 
144var containerCollection = database.GetCosmosDBSqlContainers();
145var containerOperation = await containerCollection.CreateOrUpdateAsync(
146    WaitUntil.Completed,
147    "my-container",
148    containerData);
149 
150CosmosDBSqlContainerResource container = containerOperation.Value;
151```
152 
153### 4. Configure Throughput
154 
155```csharp
156// Manual throughput
157var throughputData = new ThroughputSettingsUpdateData(
158    new ThroughputSettingsResourceInfo
159    {
160        Throughput = 400
161    });
162 
163// Autoscale throughput
164var autoscaleData = new ThroughputSettingsUpdateData(
165    new ThroughputSettingsResourceInfo
166    {
167        AutoscaleSettings = new AutoscaleSettingsResourceInfo
168        {
169            MaxThroughput = 4000
170        }
171    });
172 
173// Apply to database
174await database.CreateOrUpdateCosmosDBSqlDatabaseThroughputAsync(
175    WaitUntil.Completed,
176    throughputData);
177```
178 
179### 5. Get Connection Information
180 
181```csharp
182// Get keys
183var keys = await account.GetKeysAsync();
184Console.WriteLine($"Primary Key: {keys.Value.PrimaryMasterKey}");
185 
186// Get connection strings
187var connectionStrings = await account.GetConnectionStringsAsync();
188foreach (var cs in connectionStrings.Value.ConnectionStrings)
189{
190    Console.WriteLine($"{cs.Description}: {cs.ConnectionString}");
191}
192```
193 
194## Key Types Reference
195 
196| Type | Purpose |
197|------|---------|
198| `ArmClient` | Entry point for all ARM operations |
199| `CosmosDBAccountResource` | Represents a Cosmos DB account |
200| `CosmosDBAccountCollection` | Collection for account CRUD |
201| `CosmosDBSqlDatabaseResource` | SQL API database |
202| `CosmosDBSqlContainerResource` | SQL API container |
203| `CosmosDBAccountCreateOrUpdateContent` | Account creation payload |
204| `CosmosDBSqlDatabaseCreateOrUpdateContent` | Database creation payload |
205| `CosmosDBSqlContainerCreateOrUpdateContent` | Container creation payload |
206| `ThroughputSettingsUpdateData` | Throughput configuration |
207 
208## Best Practices
209 
2101. **Use `WaitUntil.Completed`** for operations that must finish before proceeding
2112. **Use `WaitUntil.Started`** when you want to poll manually or run operations in parallel
2123. **Always use `DefaultAzureCredential`** — never hardcode keys
2134. **Handle `RequestFailedException`** for ARM API errors
2145. **Use `CreateOrUpdateAsync`** for idempotent operations
2156. **Navigate hierarchy** via `Get*` methods (e.g., `account.GetCosmosDBSqlDatabases()`)
216 
217## Error Handling
218 
219```csharp
220using Azure;
221 
222try
223{
224    var operation = await accountCollection.CreateOrUpdateAsync(
225        WaitUntil.Completed, accountName, accountData);
226}
227catch (RequestFailedException ex) when (ex.Status == 409)
228{
229    Console.WriteLine("Account already exists");
230}
231catch (RequestFailedException ex)
232{
233    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
234}
235```
236 
237## Reference Files
238 
239| File | When to Read |
240|------|--------------|
241| [references/account-management.md](references/account-management.md) | Account CRUD, failover, keys, connection strings, networking |
242| [references/sql-resources.md](references/sql-resources.md) | SQL databases, containers, stored procedures, triggers, UDFs |
243| [references/throughput.md](references/throughput.md) | Manual/autoscale throughput, migration between modes |
244 
245## Related SDKs
246 
247| SDK | Purpose | Install |
248|-----|---------|---------|
249| `Microsoft.Azure.Cosmos` | Data plane (document CRUD, queries) | `dotnet add package Microsoft.Azure.Cosmos` |
250| `Azure.ResourceManager.CosmosDB` | Management plane (this SDK) | `dotnet add package Azure.ResourceManager.CosmosDB` |
251