Azure Mgmt Apimanagement Dotnet

1---
2name: azure-mgmt-apimanagement-dotnet
3description: |
4  Azure Resource Manager SDK for API Management in .NET. Use for MANAGEMENT PLANE operations: creating/managing APIM services, APIs, products, subscriptions, policies, users, groups, gateways, and backends via Azure Resource Manager. Triggers: "API Management", "APIM service", "create APIM", "manage APIs", "ApiManagementServiceResource", "API policies", "APIM products", "APIM subscriptions".
5package: Azure.ResourceManager.ApiManagement
6---
7 
8# Azure.ResourceManager.ApiManagement (.NET)
9 
10Management plane SDK for provisioning and managing Azure API Management resources via Azure Resource Manager.
11 
12> **⚠️ Management vs Data Plane**
13> - **This SDK (Azure.ResourceManager.ApiManagement)**: Create services, APIs, products, subscriptions, policies, users, groups
14> - **Data Plane**: Direct API calls to your APIM gateway endpoints
15 
16## Installation
17 
18```bash
19dotnet add package Azure.ResourceManager.ApiManagement
20dotnet add package Azure.Identity
21```
22 
23**Current Version**: v1.3.0
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.ApiManagement;
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        └── ApiManagementServiceResource
59            ├── ApiResource
60            │   ├── ApiOperationResource
61            │   │   └── ApiOperationPolicyResource
62            │   ├── ApiPolicyResource
63            │   ├── ApiSchemaResource
64            │   └── ApiDiagnosticResource
65            ├── ApiManagementProductResource
66            │   ├── ProductApiResource
67            │   ├── ProductGroupResource
68            │   └── ProductPolicyResource
69            ├── ApiManagementSubscriptionResource
70            ├── ApiManagementPolicyResource
71            ├── ApiManagementUserResource
72            ├── ApiManagementGroupResource
73            ├── ApiManagementBackendResource
74            ├── ApiManagementGatewayResource
75            ├── ApiManagementCertificateResource
76            ├── ApiManagementNamedValueResource
77            └── ApiManagementLoggerResource
78```
79 
80## Core Workflow
81 
82### 1. Create API Management Service
83 
84```csharp
85using Azure.ResourceManager.ApiManagement;
86using Azure.ResourceManager.ApiManagement.Models;
87 
88// Get resource group
89var resourceGroup = await subscription
90    .GetResourceGroupAsync("my-resource-group");
91 
92// Define service
93var serviceData = new ApiManagementServiceData(
94    location: AzureLocation.EastUS,
95    sku: new ApiManagementServiceSkuProperties(
96        ApiManagementServiceSkuType.Developer, 
97        capacity: 1),
98    publisherEmail: "admin@contoso.com",
99    publisherName: "Contoso");
100 
101// Create service (long-running operation - can take 30+ minutes)
102var serviceCollection = resourceGroup.Value.GetApiManagementServices();
103var operation = await serviceCollection.CreateOrUpdateAsync(
104    WaitUntil.Completed,
105    "my-apim-service",
106    serviceData);
107 
108ApiManagementServiceResource service = operation.Value;
109```
110 
111### 2. Create an API
112 
113```csharp
114var apiData = new ApiCreateOrUpdateContent
115{
116    DisplayName = "My API",
117    Path = "myapi",
118    Protocols = { ApiOperationInvokableProtocol.Https },
119    ServiceUri = new Uri("https://backend.contoso.com/api")
120};
121 
122var apiCollection = service.GetApis();
123var apiOperation = await apiCollection.CreateOrUpdateAsync(
124    WaitUntil.Completed,
125    "my-api",
126    apiData);
127 
128ApiResource api = apiOperation.Value;
129```
130 
131### 3. Create a Product
132 
133```csharp
134var productData = new ApiManagementProductData
135{
136    DisplayName = "Starter",
137    Description = "Starter tier with limited access",
138    IsSubscriptionRequired = true,
139    IsApprovalRequired = false,
140    SubscriptionsLimit = 1,
141    State = ApiManagementProductState.Published
142};
143 
144var productCollection = service.GetApiManagementProducts();
145var productOperation = await productCollection.CreateOrUpdateAsync(
146    WaitUntil.Completed,
147    "starter",
148    productData);
149 
150ApiManagementProductResource product = productOperation.Value;
151 
152// Add API to product
153await product.GetProductApis().CreateOrUpdateAsync(
154    WaitUntil.Completed,
155    "my-api");
156```
157 
158### 4. Create a Subscription
159 
160```csharp
161var subscriptionData = new ApiManagementSubscriptionCreateOrUpdateContent
162{
163    DisplayName = "My Subscription",
164    Scope = $"/products/{product.Data.Name}",
165    State = ApiManagementSubscriptionState.Active
166};
167 
168var subscriptionCollection = service.GetApiManagementSubscriptions();
169var subOperation = await subscriptionCollection.CreateOrUpdateAsync(
170    WaitUntil.Completed,
171    "my-subscription",
172    subscriptionData);
173 
174ApiManagementSubscriptionResource subscription = subOperation.Value;
175 
176// Get subscription keys
177var keys = await subscription.GetSecretsAsync();
178Console.WriteLine($"Primary Key: {keys.Value.PrimaryKey}");
179```
180 
181### 5. Set API Policy
182 
183```csharp
184var policyXml = @"
185<policies>
186    <inbound>
187        <rate-limit calls=""100"" renewal-period=""60"" />
188        <set-header name=""X-Custom-Header"" exists-action=""override"">
189            <value>CustomValue</value>
190        </set-header>
191        <base />
192    </inbound>
193    <backend>
194        <base />
195    </backend>
196    <outbound>
197        <base />
198    </outbound>
199    <on-error>
200        <base />
201    </on-error>
202</policies>";
203 
204var policyData = new PolicyContractData
205{
206    Value = policyXml,
207    Format = PolicyContentFormat.Xml
208};
209 
210await api.GetApiPolicy().CreateOrUpdateAsync(
211    WaitUntil.Completed,
212    policyData);
213```
214 
215### 6. Backup and Restore
216 
217```csharp
218// Backup
219var backupParams = new ApiManagementServiceBackupRestoreContent(
220    storageAccount: "mystorageaccount",
221    containerName: "apim-backups",
222    backupName: "backup-2024-01-15")
223{
224    AccessType = StorageAccountAccessType.SystemAssignedManagedIdentity
225};
226 
227await service.BackupAsync(WaitUntil.Completed, backupParams);
228 
229// Restore
230await service.RestoreAsync(WaitUntil.Completed, backupParams);
231```
232 
233## Key Types Reference
234 
235| Type | Purpose |
236|------|---------|
237| `ArmClient` | Entry point for all ARM operations |
238| `ApiManagementServiceResource` | Represents an APIM service instance |
239| `ApiManagementServiceCollection` | Collection for service CRUD |
240| `ApiResource` | Represents an API |
241| `ApiManagementProductResource` | Represents a product |
242| `ApiManagementSubscriptionResource` | Represents a subscription |
243| `ApiManagementPolicyResource` | Service-level policy |
244| `ApiPolicyResource` | API-level policy |
245| `ApiManagementUserResource` | Represents a user |
246| `ApiManagementGroupResource` | Represents a group |
247| `ApiManagementBackendResource` | Represents a backend service |
248| `ApiManagementGatewayResource` | Represents a self-hosted gateway |
249 
250## SKU Types
251 
252| SKU | Purpose | Capacity |
253|-----|---------|----------|
254| `Developer` | Development/testing (no SLA) | 1 |
255| `Basic` | Entry-level production | 1-2 |
256| `Standard` | Medium workloads | 1-4 |
257| `Premium` | High availability, multi-region | 1-12 per region |
258| `Consumption` | Serverless, pay-per-call | N/A |
259 
260## Best Practices
261 
2621. **Use `WaitUntil.Completed`** for operations that must finish before proceeding
2632. **Use `WaitUntil.Started`** for long operations like service creation (30+ min)
2643. **Always use `DefaultAzureCredential`** — never hardcode keys
2654. **Handle `RequestFailedException`** for ARM API errors
2665. **Use `CreateOrUpdateAsync`** for idempotent operations
2676. **Navigate hierarchy** via `Get*` methods (e.g., `service.GetApis()`)
2687. **Policy format** — Use XML format for policies; JSON is also supported
2698. **Service creation** — Developer SKU is fastest for testing (~15-30 min)
270 
271## Error Handling
272 
273```csharp
274using Azure;
275 
276try
277{
278    var operation = await serviceCollection.CreateOrUpdateAsync(
279        WaitUntil.Completed, serviceName, serviceData);
280}
281catch (RequestFailedException ex) when (ex.Status == 409)
282{
283    Console.WriteLine("Service already exists");
284}
285catch (RequestFailedException ex) when (ex.Status == 400)
286{
287    Console.WriteLine($"Bad request: {ex.Message}");
288}
289catch (RequestFailedException ex)
290{
291    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
292}
293```
294 
295## Reference Files
296 
297| File | When to Read |
298|------|--------------|
299| [references/service-management.md](references/service-management.md) | Service CRUD, SKUs, networking, backup/restore |
300| [references/apis-operations.md](references/apis-operations.md) | APIs, operations, schemas, versioning |
301| [references/products-subscriptions.md](references/products-subscriptions.md) | Products, subscriptions, access control |
302| [references/policies.md](references/policies.md) | Policy XML patterns, scopes, common policies |
303 
304## Related Resources
305 
306| Resource | Purpose |
307|----------|---------|
308| [API Management Documentation](https://learn.microsoft.com/en-us/azure/api-management/) | Official Azure docs |
309| [Policy Reference](https://learn.microsoft.com/en-us/azure/api-management/api-management-policies) | Complete policy reference |
310| [SDK Reference](https://learn.microsoft.com/en-us/dotnet/api/azure.resourcemanager.apimanagement) | .NET API reference |
311