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

dotnet add package Azure.ResourceManager.ApiManagement dotnet add package Azure.Identity

Current Version: v1.3.0

Environment Variables

AZURE_SUBSCRIPTION_ID=<your-subscription-id>

For service principal auth (optional)

AZURE_TENANT_ID=<tenant-id> AZURE_CLIENT_ID=<client-id> AZURE_CLIENT_SECRET=<client-secret>

Authentication

using Azure.Identity; using Azure.ResourceManager; using Azure.ResourceManager.ApiManagement;

// Always use DefaultAzureCredential var credential = new DefaultAzureCredential(); 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 └── ApiManagementServiceResource ├── ApiResource │ ├── ApiOperationResource │ │ └── ApiOperationPolicyResource │ ├── ApiPolicyResource │ ├── ApiSchemaResource │ └── ApiDiagnosticResource ├── ApiManagementProductResource │ ├── ProductApiResource │ ├── ProductGroupResource │ └── ProductPolicyResource ├── ApiManagementSubscriptionResource ├── ApiManagementPolicyResource ├── ApiManagementUserResource ├── ApiManagementGroupResource ├── ApiManagementBackendResource ├── ApiManagementGatewayResource ├── ApiManagementCertificateResource ├── ApiManagementNamedValueResource └── ApiManagementLoggerResource

Core Workflow

1. Create API Management Service

using Azure.ResourceManager.ApiManagement; using Azure.ResourceManager.ApiManagement.Models;

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

// Define service var serviceData = new ApiManagementServiceData( location: AzureLocation.EastUS, sku: new ApiManagementServiceSkuProperties( ApiManagementServiceSkuType.Developer, capacity: 1), publisherEmail: "admin@contoso.com", 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

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

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 product await product.GetProductApis().CreateOrUpdateAsync( WaitUntil.Completed, "my-api");

4. Create a Subscription

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 keys var keys = await subscription.GetSecretsAsync(); Console.WriteLine($"Primary Key: {keys.Value.PrimaryKey}");

5. Set API Policy

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

// Backup var backupParams = new ApiManagementServiceBackupRestoreContent( storageAccount: "mystorageaccount", containerName: "apim-backups", backupName: "backup-2024-01-15") { AccessType = StorageAccountAccessType.SystemAssignedManagedIdentity };

await service.BackupAsync(WaitUntil.Completed, backupParams);

// Restore await 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.Completed for operations that must finish before proceeding

• Use WaitUntil.Started for long operations like service creation (30+ min)

• Always use DefaultAzureCredential — never hardcode keys

• Handle RequestFailedException for ARM API errors

• Use CreateOrUpdateAsync for 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

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 Service CRUD, SKUs, networking, backup/restore

references/apis-operations.md APIs, operations, schemas, versioning

references/products-subscriptions.md Products, subscriptions, access control

references/policies.md 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