Azure Mgmt Apimanagement Dotnet

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= # Required: Azure subscription ID
AZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production
AZURE_TENANT_ID= # For service principal auth (optional)
AZURE_CLIENT_ID= # For service principal auth (optional)
AZURE_CLIENT_SECRET= # For service principal auth (optional)

Authentication

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

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=
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
        └── 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 = @"

    
        
        
            CustomValue
        
        
    
    
        
    
    
        
    
    
        
    
";

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

1. Use WaitUntil.Completed for operations that must finish before proceeding
2. Use WaitUntil.Started for long operations like service creation (30+ min)
3. Always 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., service.GetApis())
7. Policy format — Use XML format for policies; JSON is also supported
8. 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](references/service-management.md) | Service CRUD, SKUs, networking, backup/restore | | [references/apis-operations.md](references/apis-operations.md) | APIs, operations, schemas, versioning | | [references/products-subscriptions.md](references/products-subscriptions.md) | Products, subscriptions, access control | | [references/policies.md](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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/skills
• License: MIT
• Homepage: https://microsoft.github.io/skills/

Install and usage instructions live in the source repository linked above.