Azure.ResourceManager.ApiManagement (.NET)
Management plane SDK for provisioning and managing Azure API Management resources via Azure Resource Manager.
⚠️ Management vs Data Plane
- This SDK (Azure.ResourceManager.ApiManagement): Create services, APIs, products, subscriptions, policies, users, groups
- Data Plane: Direct API calls to your APIM gateway endpoints
Installation
bash
dotnet add package Azure.ResourceManager.ApiManagementdotnet add package Azure.IdentityCurrent Version: v1.3.0
Environment Variables
bash
AZURE_SUBSCRIPTION_ID=<your-subscription-id> # Required: Azure subscription IDAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in productionAZURE_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.ApiManagement;
// 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 subscriptionvar subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");var subscription = armClient.GetSubscriptionResource( new ResourceIdentifier($"/subscriptions/{subscriptionId}"));Resource Hierarchy
ArmClient└── SubscriptionResource └── ResourceGroupResource └── ApiManagementServiceResource ├── ApiResource │ ├── ApiOperationResource │ │ └── ApiOperationPolicyResource │ ├── ApiPolicyResource │ ├── ApiSchemaResource │ └── ApiDiagnosticResource ├── ApiManagementProductResource │ ├── ProductApiResource │ ├── ProductGroupResource │ └── ProductPolicyResource ├── ApiManagementSubscriptionResource ├── ApiManagementPolicyResource ├── ApiManagementUserResource ├── ApiManagementGroupResource ├── ApiManagementBackendResource ├── ApiManagementGatewayResource ├── ApiManagementCertificateResource ├── ApiManagementNamedValueResource └── ApiManagementLoggerResourceCore Workflow
1. Create API Management Service
csharp
using Azure.ResourceManager.ApiManagement;using Azure.ResourceManager.ApiManagement.Models;
// Get resource groupvar resourceGroup = await subscription .GetResourceGroupAsync("my-resource-group");
// Define servicevar serviceData = new ApiManagementServiceData( location: AzureLocation.EastUS, sku: new ApiManagementServiceSkuProperties( ApiManagementServiceSkuType.Developer, capacity: 1), publisherEmail: "[email protected]", publisherName: "Contoso");
// Create service (long-running operation - can take 30+ minutes)var serviceCollection = resourceGroup.Value.GetApiManagementServices();var operation = await serviceCollection.CreateOrUpdateAsync( WaitUntil.Completed, "my-apim-service", serviceData);
ApiManagementServiceResource service = operation.Value;2. Create an API
csharp
var apiData = new ApiCreateOrUpdateContent{ DisplayName = "My API", Path = "myapi", Protocols = { ApiOperationInvokableProtocol.Https }, ServiceUri = new Uri("https://backend.contoso.com/api")};
var apiCollection = service.GetApis();var apiOperation = await apiCollection.CreateOrUpdateAsync( WaitUntil.Completed, "my-api", apiData);
ApiResource api = apiOperation.Value;3. Create a Product
csharp
var productData = new ApiManagementProductData{ DisplayName = "Starter", Description = "Starter tier with limited access", IsSubscriptionRequired = true, IsApprovalRequired = false, SubscriptionsLimit = 1, State = ApiManagementProductState.Published};
var productCollection = service.GetApiManagementProducts();var productOperation = await productCollection.CreateOrUpdateAsync( WaitUntil.Completed, "starter", productData);
ApiManagementProductResource product = productOperation.Value;
// Add API to productawait product.GetProductApis().CreateOrUpdateAsync( WaitUntil.Completed, "my-api");4. Create a Subscription
csharp
var subscriptionData = new ApiManagementSubscriptionCreateOrUpdateContent{ DisplayName = "My Subscription", Scope = $"/products/{product.Data.Name}", State = ApiManagementSubscriptionState.Active};
var subscriptionCollection = service.GetApiManagementSubscriptions();var subOperation = await subscriptionCollection.CreateOrUpdateAsync( WaitUntil.Completed, "my-subscription", subscriptionData);
ApiManagementSubscriptionResource subscription = subOperation.Value;
// Get subscription keysvar keys = await subscription.GetSecretsAsync();Console.WriteLine($"Primary Key: {keys.Value.PrimaryKey}");5. Set API Policy
csharp
var policyXml = @"<policies> <inbound> <rate-limit calls=""100"" renewal-period=""60"" /> <set-header name=""X-Custom-Header"" exists-action=""override""> <value>CustomValue</value> </set-header> <base /> </inbound> <backend> <base /> </backend> <outbound> <base /> </outbound> <on-error> <base /> </on-error></policies>";
var policyData = new PolicyContractData{ Value = policyXml, Format = PolicyContentFormat.Xml};
await api.GetApiPolicy().CreateOrUpdateAsync( WaitUntil.Completed, policyData);6. Backup and Restore
csharp
// Backupvar backupParams = new ApiManagementServiceBackupRestoreContent( storageAccount: "mystorageaccount", containerName: "apim-backups", backupName: "backup-2024-01-15"){ AccessType = StorageAccountAccessType.SystemAssignedManagedIdentity};
await service.BackupAsync(WaitUntil.Completed, backupParams);
// Restoreawait service.RestoreAsync(WaitUntil.Completed, backupParams);Key Types Reference
| Type | Purpose |
|---|---|
ArmClient | Entry point for all ARM operations |
ApiManagementServiceResource | Represents an APIM service instance |
ApiManagementServiceCollection | Collection for service CRUD |
ApiResource | Represents an API |
ApiManagementProductResource | Represents a product |
ApiManagementSubscriptionResource | Represents a subscription |
ApiManagementPolicyResource | Service-level policy |
ApiPolicyResource | API-level policy |
ApiManagementUserResource | Represents a user |
ApiManagementGroupResource | Represents a group |
ApiManagementBackendResource | Represents a backend service |
ApiManagementGatewayResource | Represents a self-hosted gateway |
SKU Types
| SKU | Purpose | Capacity |
|---|---|---|
Developer | Development/testing (no SLA) | 1 |
Basic | Entry-level production | 1-2 |
Standard | Medium workloads | 1-4 |
Premium | High availability, multi-region | 1-12 per region |
Consumption | Serverless, pay-per-call | N/A |
Best Practices
- Use
WaitUntil.Completedfor operations that must finish before proceeding - Use
WaitUntil.Startedfor long operations like service creation (30+ min) - Always use
DefaultAzureCredential— never hardcode keys - Handle
RequestFailedExceptionfor ARM API errors - Use
CreateOrUpdateAsyncfor idempotent operations - Navigate hierarchy via
Get*methods (e.g.,service.GetApis()) - Policy format — Use XML format for policies; JSON is also supported
- Service creation — Developer SKU is fastest for testing (~15-30 min)
Error Handling
csharp
using Azure;
try{ var operation = await serviceCollection.CreateOrUpdateAsync( WaitUntil.Completed, serviceName, serviceData);}catch (RequestFailedException ex) when (ex.Status == 409){ Console.WriteLine("Service already exists");}catch (RequestFailedException ex) when (ex.Status == 400){ Console.WriteLine($"Bad request: {ex.Message}");}catch (RequestFailedException ex){ Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");}Reference Files
| File | When to Read |
|---|---|
| references/service-management.md [blocked] | Service CRUD, SKUs, networking, backup/restore |
| references/apis-operations.md [blocked] | APIs, operations, schemas, versioning |
| references/products-subscriptions.md [blocked] | Products, subscriptions, access control |
| references/policies.md [blocked] | Policy XML patterns, scopes, common policies |
Related Resources
| Resource | Purpose |
|---|---|
| API Management Documentation | Official Azure docs |
| Policy Reference | Complete policy reference |
| SDK Reference | .NET API reference |
