Configurar o bot do .NET para a extensão

2024-10-09

A partir de 1º de setembro de 2023, é altamente recomendável empregar o método de Marca de Serviço do Azure para isolamento de rede. A utilização do DL-ASE deve ser limitada a cenários altamente específicos. Antes de implementar essa solução em um ambiente de produção, recomendamos consultar sua equipe de suporte para obter orientação.

APLICA-SE A: SDK v4

Este artigo descreve como atualizar um bot NET para trabalhar com pipes nomeados e como habilitar a extensão de serviço de aplicativo do Direct Line no recurso de Serviço de Aplicativo do Azure em que o bot está hospedado.

Pré-requisitos

Uma conta do Azure. Se ainda não tiver uma, crie uma conta gratuita antes de começar.
Um bot NET implantado no Azure.
SDK do Bot Framework para NET, 4.14.1 ou posterior.

Habilitar a Extensão de Serviço de Aplicativo do Direct Line

Esta seção descreve como habilitar a extensão do serviço de aplicativo do Direct Line usando a chave de extensão do serviço de aplicativo da configuração de canal do Direct Line do seu bot.

Atualizar o código do bot

Observação

Os pacotes de preview do NuGet Microsoft.Bot.Builder.StreamingExtensions foram preteridos. A partir da v4.8, o SDK contém um namespace Microsoft.Bot.Builder.Streaming. Se um bot usou anteriormente os pacotes de preview, eles devem ser removidos antes de você seguir as etapas abaixo.

No Visual Studio, abra o projeto do bot.

Permita que seu aplicativo use pipes nomeados:

Abra o arquivo Startup.cs.
Adicione uma referência ao pacote do NuGet Microsoft.Bot.Builder.Integration.AspNet.Core.
```
using Microsoft.Bot.Builder.Integration.AspNet.Core;
```

No método Configure, adicione uma chamada ao método UseNamedPipes.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseDefaultFiles()
        .UseStaticFiles()
        .UseWebSockets()
        // Allow the bot to use named pipes.
        .UseNamedPipes(System.Environment.GetEnvironmentVariable("APPSETTING_WEBSITE_SITE_NAME") + ".directline")
        .UseRouting()
        .UseAuthorization()
        .UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });

    // app.UseHttpsRedirection();
}

Salve o arquivo Startup.cs.

Implante seu Bot de Atualização no Azure.

Habilite a Extensão de Serviço de Aplicativo do Direct Line do bot

No portal do Azure, acesse o recurso Bot do Azure.
1. Em Configurações, selecione Canais para configurar os canais dos quais o bot aceita mensagens.
2. Se ainda não estiver habilitado, selecione o canal do Direct Line na lista de Canais disponíveis para habilitar o canal.
3. Depois de habilitar o Direct Line, selecione-o novamente na página Canais.
4. Selecione a guia Extensão do Serviço de Aplicativo.
5. Em Chaves de Extensão do Serviço de Aplicativo, selecione o ícone de olho ao lado da chave correspondente.
Acesse a home page e selecione Serviços de Aplicativo na parte superior da página. Como alternativa, exiba o menu do portal e selecione o item de menu Serviços de Aplicativo. O Azure exibirá a página Serviços de Aplicativo.
Na caixa de pesquisa, digite o nome do recurso do Bot do Azure. Seu recurso estará listado.

Observe que, se você passar o mouse sobre o ícone ou o item de menu, obterá uma lista dos últimos recursos visualizados. Seu recurso de Bot do Azure provavelmente estará listado.

Selecione o link de recursos.

Na seção Configurações, selecione o item de menu Configuração.
No painel à direita, adicione as seguintes configurações:

Nome Valor

DirectLineExtensionKey O valor da chave de extensão do Serviço de Aplicativo que você copiou anteriormente.

DIRECTLINE_EXTENSION_VERSION mais recente

Nome	Valor
DirectLineExtensionKey	O valor da chave de extensão do Serviço de Aplicativo que você copiou anteriormente.
DIRECTLINE_EXTENSION_VERSION	mais recente

Se o bot estiver hospedado em uma nuvem do Azure soberana ou restrita, onde você não acessa o Azure por meio do portal público, você também precisará adicionar a seguinte configuração:

Nome	Valor
DirectLineExtensionABSEndpoint	O ponto de extremidade específico para a nuvem do Azure em que seu bot está hospedado. Para a nuvem USGov, por exemplo, o ponto de extremidade é `https://directline.botframework.azure.us/v3/extension`.

Na seção Configuração, selecione a seção de configurações Gerais e ative os Webs sockets.
Clique em Salvar para salvar as configurações. Isso reinicia o Serviço de Aplicativo do Azure.

Confirme a extensão do Direct Line e que o bot estão configurados

No navegador, vá para https://<your_app_service>.azurewebsites.net/.bot. Se tudo estiver correto, a página retornará o seguinte conteúdo JSON:

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}

v exibe a versão de build da Extensão de Serviço de Aplicativo do Direct Line.
k indica se a extensão foi capaz de ler uma chave de extensão em sua configuração.
initialized indica se a extensão foi capaz de fazer download dos metadados de bot do Serviço de Bot de IA do Azure.
ib indica se a extensão foi capaz de estabelecer uma conexão de entrada com o bot.
ob indica se a extensão foi capaz de estabelecer uma conexão de saída com o bot.

Solução de problemas

Se os valores ib e ob exibidos pelo ponto de extremidade .bot forem false, o bot e a extensão do Serviço de Aplicativo do Direct Line não poderão se conectar um ao outro.
1. Verifique se o código para usar pipes nomeados foi adicionado ao bot.
2. Confirme se o bot está em funcionamento. As ferramentas úteis são Testar no Webchat, conectar um canal adicional, depuração remota ou registro em log.
3. Reinicie todo o Serviço de Aplicativo do Azure no qual o bot está hospedado para garantir uma inicialização limpa de todos os processos.
Se o valor inicializado do ponto de extremidade do .bot for false, a extensão do Serviço de Aplicativo do Direct Line não poderá validar a chave de extensão do Serviço de Aplicativo adicionada às Configurações de Aplicativo do bot acima.
1. Confirme se o valor foi digitado corretamente.
2. Alterne para a chave de extensão alternativa mostrada na página Configurar o Direct Line do bot.

Permita que o bot use o modelo de hospedagem fora do processo; caso contrário, você receberá um erro HTTP 500.34 - erro de hospedagem mista ANCM (onde ANCM significa ASP.NET Core Module). Esse erro ocorre porque o modelo de bot está usando o modelo de hospedagem InProcess por padrão. Para configurar a hospedagem fora do processo, confira Modelo de hospedagem fora do processo. Para obter mais informações, confira Atributos do elemento aspNetCore e Configuração com web.config.

Se você tentar usar o OAuth com a extensão do Serviço de Aplicativo do Direct Line e encontrar o erro "Não é possível obter o AppId do bot da declaração de público-alvo", defina ClaimsIdentity como AudienceClaim no BotFrameworkHttpAdapter. Para fazer isso, você pode subclassificar o adaptador. Por exemplo:

public class AdapterWithStaticClaimsIdentity : BotFrameworkHttpAdapter
{
    public AdapterWithStaticClaimsIdentity(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, ConversationState conversationState = null)
        : base(configuration, logger)
    {
        // Manually create the ClaimsIdentity and create a Claim with a valid AudienceClaim and the AppID for a bot using the Direct Line App Service extension.
        var appId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;
        ClaimsIdentity = new ClaimsIdentity(new List<Claim>{
            new Claim(AuthenticationConstants.AudienceClaim, appId)
        });
    }
}

Próximas etapas

Usar o Webchat com a extensão de serviço de aplicativo do Direct Line

Compartilhar via