williamlimasilva/azure-mgmt-botservice-dotnet

Azure.ResourceManager.BotService (.NET)

Management plane SDK for provisioning and managing Azure Bot Service resources via Azure Resource Manager.

Installation

dotnet add package Azure.ResourceManager.BotService
dotnet add package Azure.Identity

Current Versions: Stable v1.1.1, Preview v1.1.0-beta.1

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.BotService;

// Authenticate using DefaultAzureCredential
var credential = new DefaultAzureCredential();
ArmClient armClient = new ArmClient(credential);

// Get subscription and resource group
SubscriptionResource subscription = await armClient.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroups().GetAsync("myResourceGroup");

// Access bot collection
BotCollection botCollection = resourceGroup.GetBots();

Resource Hierarchy

ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── BotResource
            ├── BotChannelResource (DirectLine, Teams, Slack, etc.)
            ├── BotConnectionSettingResource (OAuth connections)
            └── BotServicePrivateEndpointConnectionResource

Core Workflows

1. Create Bot Resource

using Azure.ResourceManager.BotService;
using Azure.ResourceManager.BotService.Models;

// Create bot data
var botData = new BotData(AzureLocation.WestUS2)
{
    Kind = BotServiceKind.Azurebot,
    Sku = new BotServiceSku(BotServiceSkuName.F0),
    Properties = new BotProperties(
        displayName: "MyBot",
        endpoint: new Uri("https://mybot.azurewebsites.net/api/messages"),
        msaAppId: "<your-msa-app-id>")
    {
        Description = "My Azure Bot",
        MsaAppType = BotMsaAppType.MultiTenant
    }
};

// Create or update the bot
ArmOperation<BotResource> operation = await botCollection.CreateOrUpdateAsync(
    WaitUntil.Completed, 
    "myBotName", 
    botData);
    
BotResource bot = operation.Value;
Console.WriteLine($"Bot created: {bot.Data.Name}");

2. Configure DirectLine Channel

// Get the bot
BotResource bot = await resourceGroup.GetBots().GetAsync("myBotName");

// Get channel collection
BotChannelCollection channels = bot.GetBotChannels();

// Create DirectLine channel configuration
var channelData = new BotChannelData(AzureLocation.WestUS2)
{
    Properties = new DirectLineChannel()
    {
        Properties = new DirectLineChannelProperties()
        {
            Sites = 
            {
                new DirectLineSite("Default Site")
                {
                    IsEnabled = true,
                    IsV1Enabled = false,
                    IsV3Enabled = true,
                    IsSecureSiteEnabled = true
                }
            }
        }
    }
};

// Create or update the channel
ArmOperation<BotChannelResource> channelOp = await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.DirectLineChannel,
    channelData);

Console.WriteLine("DirectLine channel configured");

3. Configure Microsoft Teams Channel

var teamsChannelData = new BotChannelData(AzureLocation.WestUS2)
{
    Properties = new MsTeamsChannel()
    {
        Properties = new MsTeamsChannelProperties()
        {
            IsEnabled = true,
            EnableCalling = false
        }
    }
};

await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.MsTeamsChannel,
    teamsChannelData);

4. Configure Web Chat Channel

var webChatChannelData = new BotChannelData(AzureLocation.WestUS2)
{
    Properties = new WebChatChannel()
    {
        Properties = new WebChatChannelProperties()
        {
            Sites =
            {
                new WebChatSite("Default Site")
                {
                    IsEnabled = true
                }
            }
        }
    }
};

await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.WebChatChannel,
    webChatChannelData);

5. Get Bot and List Channels

// Get bot
BotResource bot = await botCollection.GetAsync("myBotName");
Console.WriteLine($"Bot: {bot.Data.Properties.DisplayName}");
Console.WriteLine($"Endpoint: {bot.Data.Properties.Endpoint}");

// List channels
await foreach (BotChannelResource channel in bot.GetBotChannels().GetAllAsync())
{
    Console.WriteLine($"Channel: {channel.Data.Name}");
}

6. Regenerate DirectLine Keys

var regenerateRequest = new BotChannelRegenerateKeysContent(BotChannelName.DirectLineChannel)
{
    SiteName = "Default Site"
};

BotChannelResource channelWithKeys = await bot.GetBotChannelWithRegenerateKeysAsync(regenerateRequest);

7. Update Bot

BotResource bot = await botCollection.GetAsync("myBotName");

// Update using patch
var updateData = new BotData(bot.Data.Location)
{
    Properties = new BotProperties(
        displayName: "Updated Bot Name",
        endpoint: bot.Data.Properties.Endpoint,
        msaAppId: bot.Data.Properties.MsaAppId)
    {
        Description = "Updated description"
    }
};

await bot.UpdateAsync(updateData);

8. Delete Bot

BotResource bot = await botCollection.GetAsync("myBotName");
await bot.DeleteAsync(WaitUntil.Completed);

Supported Channel Types

| Channel | Constant | Class | |---------|----------|-------| | Direct Line | BotChannelName.DirectLineChannel | DirectLineChannel | | Direct Line Speech | BotChannelName.DirectLineSpeechChannel | DirectLineSpeechChannel | | Microsoft Teams | BotChannelName.MsTeamsChannel | MsTeamsChannel | | Web Chat | BotChannelName.WebChatChannel | WebChatChannel | | Slack | BotChannelName.SlackChannel | SlackChannel | | Facebook | BotChannelName.FacebookChannel | FacebookChannel | | Email | BotChannelName.EmailChannel | EmailChannel | | Telegram | BotChannelName.TelegramChannel | TelegramChannel | | Telephony | BotChannelName.TelephonyChannel | TelephonyChannel |

Key Types Reference

| Type | Purpose | |------|---------| | ArmClient | Entry point for all ARM operations | | BotResource | Represents an Azure Bot resource | | BotCollection | Collection for bot CRUD | | BotData | Bot resource definition | | BotProperties | Bot configuration properties | | BotChannelResource | Channel configuration | | BotChannelCollection | Collection of channels | | BotChannelData | Channel configuration data | | BotConnectionSettingResource | OAuth connection settings |

BotServiceKind Values

| Value | Description | |-------|-------------| | BotServiceKind.Azurebot | Azure Bot (recommended) | | BotServiceKind.Bot | Legacy Bot Framework bot | | BotServiceKind.Designer | Composer bot | | BotServiceKind.Function | Function bot | | BotServiceKind.Sdk | SDK bot |

BotServiceSkuName Values

| Value | Description | |-------|-------------| | BotServiceSkuName.F0 | Free tier | | BotServiceSkuName.S1 | Standard tier |

BotMsaAppType Values

| Value | Description | |-------|-------------| | BotMsaAppType.MultiTenant | Multi-tenant app | | BotMsaAppType.SingleTenant | Single-tenant app | | BotMsaAppType.UserAssignedMSI | User-assigned managed identity |

Best Practices

1. Always use DefaultAzureCredential — supports multiple auth methods
2. Use WaitUntil.Completed for synchronous operations
3. Handle RequestFailedException for API errors
4. Use async methods (*Async) for all operations
5. Store MSA App credentials securely — use Key Vault for secrets
6. Use managed identity (BotMsaAppType.UserAssignedMSI) for production bots
7. Enable secure sites for DirectLine channels in production

Error Handling

using Azure;

try
{
    var operation = await botCollection.CreateOrUpdateAsync(
        WaitUntil.Completed, 
        botName, 
        botData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("Bot already exists");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

Related SDKs

| SDK | Purpose | Install | |-----|---------|---------| | Azure.ResourceManager.BotService | Bot management (this SDK) | dotnet add package Azure.ResourceManager.BotService | | Microsoft.Bot.Builder | Bot Framework SDK | dotnet add package Microsoft.Bot.Builder | | Microsoft.Bot.Builder.Integration.AspNet.Core | ASP.NET Core integration | dotnet add package Microsoft.Bot.Builder.Integration.AspNet.Core |

Reference Links

| Resource | URL | |----------|-----| | NuGet Package | https://www.nuget.org/packages/Azure.ResourceManager.BotService | | API Reference | https://learn.microsoft.com/dotnet/api/azure.resourcemanager.botservice | | GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/botservice/Azure.ResourceManager.BotService | | Azure Bot Service Docs | https://learn.microsoft.com/azure/bot-service/ |