Configurar o bot .NET para extensão

Artigo
10/24/2023

A partir de 1º de setembro de 2023, é altamente recomendável empregar o método de Etiqueta 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 esta 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 do Serviço de Aplicativo de Linha Direta no recurso do Serviço de Aplicativo do Azure no qual você implantou seu bot.

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.
Bot Framework SDK para .NET, 4.14.1 ou posterior.

Habilitar a extensão do Serviço de Aplicativo de Linha Direta

Esta seção descreve como habilitar a extensão do Serviço de Aplicativo de Linha Direta usando a chave de extensão do Serviço de Aplicativo da configuração do canal de Linha Direta do seu bot.

Atualizar código do bot

Nota

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

No Visual Studio, abra seu projeto de bot.

Permita que seu aplicativo use pipes nomeados:

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

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

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 atualizado no Azure.

Ativar a extensão do Serviço de Aplicativo de Linha Direta do bot

No portal do Azure, vá para seu recurso de Bot do Azure.
1. Em Configurações , selecione Canais para configurar os canais dos quais seu bot aceita mensagens.
2. Se ainda não estiver ativado, selecione o canal Linha Direta na lista de Canais disponíveis para ativar o canal.
3. Depois de ativar a Linha Direta, selecione-a 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.
Vá para a página inicial 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, insira o nome do recurso do Bot do Azure. Seu recurso será 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 será listado.

Selecione o link do recurso.

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

Nome Valor

DirectLineExtensionKey O valor da chave de extensão do Serviço de Aplicativo copiada anteriormente.

DIRECTLINE_EXTENSION_VERSION mais recente

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

Se o seu bot estiver hospedado em uma nuvem soberana ou restrita do Azure, 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 Configurações gerais e ative os soquetes da Web.
Selecione Guardar para guardar as definições. Isso reinicia o Serviço de Aplicativo do Azure.

Confirme se a extensão de Linha Direta e o bot estão configurados

No browser, aceda a 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 mostra a versão de compilação da extensão do Serviço de Aplicativo de Linha Direta.
k indica se a extensão foi capaz de ler uma chave de extensão a partir de sua configuração.
initialized indica se a extensão foi capaz de baixar metadados de bot do Serviço de Bot do Azure AI.
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 do bot.

Resolução de problemas

Se os valores ib e ob exibidos pelo ponto de extremidade .bot forem falsos, o bot e a extensão do Serviço de Aplicativo de Linha Direta 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 é capaz de iniciar e executar. Ferramentas úteis são Teste no WebChat, conexão de um canal adicional, depuração remota ou registro.
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 .bot for false, a extensão do Serviço de Aplicativo de Linha Direta não poderá validar a chave de extensão do Serviço de Aplicativo adicionada às Configurações do Aplicativo do bot acima.
1. Confirme se o valor foi inserido corretamente.
2. Alterne para a chave de extensão alternativa mostrada na página Configurar Linha Direta do bot.

Habilitar o bot para usar 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). Este erro ocorre porque o modelo de bot está usando o InProcess modelo de hospedagem por padrão. Para configurar a hospedagem fora do processo, consulte Modelo de hospedagem fora do processo. Para obter mais informações, consulte 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 de Linha Direta e encontrar o erro "Não é possível obter o AppId do bot da declaração de audiência", definido 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óximos passos

Usar o Web Chat com a extensão do Serviço de Aplicativo de Linha Direta

Partilhar via