azure-mgmt-apimanagement-dotnet

Bundled upstream support

Supporting files are included at skill-relative paths. See UPSTREAM-NOTICE.md for their pinned sources, licenses, hashes, and import changes.

Supporting material availability

These paths remain unavailable in this catalog copy:

• <support-root>/references/policies.md

Do not invoke a step that requires one of these files. Obtain the original material and review its dependencies, license, and effects before use. Independent inline steps and the bundled helpers can proceed within the user’s authorized scope.

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

Version note: examples are version-sensitive; resolve and pin a supported SDK package in the target project rather than treating v1.3.0 as current.

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;

// Choose a deliberate credential chain; managed identity is preferable in hosted production
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: "[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

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.NotPublished
};

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 apimSubscription = subOperation.Value;

// Get subscription keys
var keys = await apimSubscription.GetSecretsAsync();
// Store keys only through the approved secret store; never log them.

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

1. Use WaitUntil.Completed for operations that must finish before proceeding
2. Use WaitUntil.Started for long operations like service creation (30+ min)
3. Choose an explicit production identity — never hardcode keys; constrain credential-chain fallbacks
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 — Policies are XML (xml/rawxml or corresponding link formats); JSON is the transport envelope, not a policy language
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)
{
    throw; // 409 is a conflict requiring diagnosis, not proof of successful existing state
}
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

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Resource mutation and SDK limits

These snippets are separate examples with omitted project setup and version-specific model types/constructors; they have not been compiled or run against Azure. ResourceIdentifier/AzureLocation require Azure.Core, and WaitUntil/ETag require Azure. Verify exact SDK overloads, required ETags and supported SKU/region capabilities before adaptation. A 409 can indicate another conflict or operation in progress; it is not successful creation. Started operations still need polling and provisioning-state readback. CreateOrUpdate can replace existing configuration and is not harmless because its name sounds idempotent.

Confirm tenant, subscription, resource IDs, RBAC, cost and deployment scope before provisioning. Keep products unpublished until access review; a subscription key alone is not end-user identity or complete API authorization. Rotate one key at a time with consumer migration and readback; do not immediately regenerate both. Service deletion, subscription suspension, policy changes and restore require explicit target approval and recovery planning. Backup with managed identity also requires the actual identity, storage permissions and supported tier; a backup is not a complete rollback guarantee. The policy example does not add JWT validation and its rate limit is not a universal traffic ceiling. Preserve existing policy inheritance and use a reviewed revision before rollout. Omit raw ARM error bodies from public logs.