GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

azure-mgmt-apimanagement-dotnet

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", "cre

Ciza · 0 points · 21 views 0 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-dotnet_skills_azure-mgmt-apimanagement-dotnet-e58528d.zip · 7 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-dotnet/skills/azure-mgmt-apimanagement-dotnet
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git git clone https://github.com/microsoft/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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> # Required: Azure subscription ID
AZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production
AZURE_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

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 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

  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 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
Files (skills)
  • references
    • apis-operations.md 3.8 KB
      Loading…
    • products-subscriptions.md 4 KB
      Loading…
    • service-management.md 3.9 KB
      Loading…
  • SKILL.md 10.2 KB
    ---
    name: azure-mgmt-apimanagement-dotnet
    description: |
      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".
    license: MIT
    metadata:
      author: Microsoft
      version: "1.0.0"
      package: Azure.ResourceManager.ApiManagement
    ---
    
    # 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.ApiManagement
    dotnet add package Azure.Identity
    ```
    
    **Current Version**: v1.3.0
    
    ## Environment Variables
    
    ```bash
    AZURE_SUBSCRIPTION_ID=<your-subscription-id> # Required: Azure subscription ID
    AZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production
    AZURE_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 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
    
    ```csharp
    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
    
    ```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 product
    await 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 keys
    var 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
    // 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
    
    ```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](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](https://learn.microsoft.com/en-us/azure/api-management/) | Official Azure docs |
    | [Policy Reference](https://learn.microsoft.com/en-us/azure/api-management/api-management-policies) | Complete policy reference |
    | [SDK Reference](https://learn.microsoft.com/en-us/dotnet/api/azure.resourcemanager.apimanagement) | .NET API reference |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.