Azure 机器人服务 .NET 管理 SDK

azure-mgmt-botservice-dotnet

分类商业

作者Agentic Awesome Skills 社区

许可MIT

评分4.70/5

使用16.3K

Azure.ResourceManager.BotService (.NET)

用于通过 Azure 资源管理器 (ARM) 部署和管理 Azure Bot Service 资源的管理平面 SDK。

安装

bash

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

当前版本：稳定版 v1.1.1，预览版 v1.1.0-beta.1

环境变量

bash

AZURE_SUBSCRIPTION_ID=<your-subscription-id>
用于服务主体身份验证（可选）
AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

身份验证

csharp

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.BotService;
// 使用 DefaultAzureCredential 进行身份验证
var credential = new DefaultAzureCredential();
ArmClient armClient = new ArmClient(credential);
// 获取订阅和资源组
SubscriptionResource subscription = await armClient.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroups().GetAsync("myResourceGroup");
// 访问 Bot 集合
BotCollection botCollection = resourceGroup.GetBots();

资源层级

code

ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── BotResource
            ├── BotChannelResource (DirectLine, Teams, Slack 等)
            ├── BotConnectionSettingResource (OAuth 连接)
            └── BotServicePrivateEndpointConnectionResource

核心工作流

1. 创建 Bot 资源

csharp

using Azure.ResourceManager.BotService;
using Azure.ResourceManager.BotService.Models;
// 创建 Bot 数据
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
    }
};
// 创建或更新 Bot
ArmOperation<BotResource> operation = await botCollection.CreateOrUpdateAsync(
    WaitUntil.Completed, 
    "myBotName", 
    botData);
    
BotResource bot = operation.Value;
Console.WriteLine($"Bot created: {bot.Data.Name}");

2. 配置 DirectLine 频道

csharp

// 获取 Bot
BotResource bot = await resourceGroup.GetBots().GetAsync("myBotName");
// 获取频道集合
BotChannelCollection channels = bot.GetBotChannels();
// 创建 DirectLine 频道配置
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
                }
            }
        }
    }
};
// 创建或更新频道
ArmOperation<BotChannelResource> channelOp = await channels.CreateOrUpdateAsync(
    WaitUntil.Completed,
    BotChannelName.DirectLine, // 假设此处为 DirectLine
    channelData);

LineChannel,
channelData);

Console.WriteLine("DirectLine channel configured");

code

### 3. 配置 Microsoft Teams 频道

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

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

code

### 4. 配置 Web Chat 频道

csharp
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);

code

### 5. 获取 Bot 并列出频道

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

// 列出频道
await foreach (BotChannelResource channel in bot.GetBotChannels().GetAllAsync())
{
Console.WriteLine($"Channel: {channel.Data.Name}");
}

code

### 6. 重新生成 DirectLine 密钥

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

BotChannelResource channelWithKeys = await bot.GetBotChannelWithRegenerateKeysAsync(regenerateRequest);

code

### 7. 更新 Bot

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

// 使用 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);

code

### 8. 删除 Bot

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

code

## 支持的频道类型
| 频道 | 常量 | 类 |
|---------|----------|-------|
| 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 |
关键类型参考
| 类型 | 用途 |
|------|---------|
| ArmClient | 所有 ARM 操作的入口点 |
| BotResource | 表示一个 Azure Bot 资源 |
| BotCollection | 用于 Bot CRUD 操作的集合 |
| BotData | Bot 资源定义 |
| BotProperties | Bot 配置属性 |
| BotChannelResource | 频道配置 |
| BotChannelCollection | 频道集合 |
| BotChannelData | 频道配置数据 |
|
| BotConnectionSettingResource | OAuth 连接设置 |
BotServiceKind 取值
| 取值 | 描述 |
|-------|-------------|
| BotServiceKind.Azurebot | Azure Bot (推荐) |
| BotServiceKind.Bot | 传统 Bot Framework 机器人 |
| BotServiceKind.Designer | Composer 机器人 |
| BotServiceKind.Function | Function 机器人 |
| BotServiceKind.Sdk | SDK 机器人 |
BotServiceSkuName 取值
| 取值 | 描述 |
|-------|-------------|
| BotServiceSkuName.F0 | 免费层级 |
| BotServiceSkuName.S1 | 标准层级 |
BotMsaAppType 取值
| 取值 | 描述 |
|-------|-------------|
| BotMsaAppType.MultiTenant | 多租户应用 |
| BotMsaAppType.SingleTenant | 单租户应用 |
| BotMsaAppType.UserAssignedMSI | 用户分配的托管标识 |
最佳实践
1. 始终使用 DefaultAzureCredential —— 支持多种身份验证方法
2. 同步操作请使用 WaitUntil.Completed
3. 处理 RequestFailedException 以应对 API 错误
4. 所有操作均使用异步方法 (*Async)
5. 安全存储 MSA 应用凭据 —— 使用 Key Vault 存储密钥
6. 生产环境机器人请使用托管标识 (BotMsaAppType.UserAssignedMSI)
7. 生产环境中的 DirectLine 频道请启用安全站点
错误处理

csharp 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}");
}
``


相关 SDK

| SDK | 用途 | 安装命令 | |-----|---------|---------| |Azure.ResourceManager.BotService | 机器人管理 (本 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 集成 | dotnet add package Microsoft.Bot.Builder.Integration.AspNet.Core` |

参考链接

| 资源 | URL |
|----------|-----|
| NuGet 包 | https://www.nuget.org/packages/Azure.ResourceManager.BotService |
| API 参考 | https://learn.microsoft.com/dotnet/api/azure.resourcemanager.botservice |
| GitHub 源码 | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/botservice/Azure.ResourceManager.BotService |
| Azure Bot Service 文档 | https://learn.microsoft.com/azure/bot-service/ |

使用场景

本技能适用于执行概览中描述的工作流或操作。

局限性

仅在任务明确符合上述范围时使用本技能。

不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。

如果缺失必要的输入、权限、安全边界或成功标准，请停止操作并寻求澄清。

Azure 机器人服务 .NET 管理 SDK

Azure.ResourceManager.BotService (.NET)

安装

环境变量

用于服务主体身份验证（可选）

身份验证

资源层级

核心工作流

1. 创建 Bot 资源

2. 配置 DirectLine 频道

关键类型参考

BotServiceKind 取值

BotServiceSkuName 取值

BotMsaAppType 取值

最佳实践

`错误处理`

相关 SDK

参考链接

使用场景

局限性

扫码进交流群