확장을 위한 .NET 봇 구성Configure .NET bot for extension

적용 대상: SDK v4APPLIES TO: SDK v4

이 문서에서는 명명된 파이프를 사용하도록 봇을 업데이트하는 방법과 봇이 호스트되는 Azure App Service 리소스에서 Direct Line App Service 확장을 사용하도록 설정하는 방법을 설명합니다.This article describes how to update a bot to work with named pipes, and how to enable the Direct Line App Service extension in the Azure App Service resource where the bot is hosted.

전제 조건Prerequisites

다음에 설명된 단계를 수행하려면 Azure에 봇을 배포해야 합니다.To perform the steps described next, you need to have a bot deployed in Azure.

Direct Line App Service 확장 사용Enable Direct Line App Service extension

이 섹션에서는 봇의 Direct Line 채널 구성에서 App Service 확장 키를 사용하여 Direct Line App Service 확장을 사용하도록 설정하는 방법을 설명합니다.This section describes how to enable the Direct Line App Service extension using the App Service extension key from your bot's Direct Line channel configuration.

봇 코드 업데이트Update bot code

참고

Microsoft.Bot.Builder.StreamingExtensions NuGet 미리 보기 패키지는 더 이상 사용되지 않습니다.The Microsoft.Bot.Builder.StreamingExtensions NuGet preview packages have been deprecated. v4.8부터 SDK에는 Microsoft.Bot.Builder.Streaming 네임스페이스가 포함됩니다.Starting with v4.8, the SDK contains a Microsoft.Bot.Builder.Streaming namespace. 이전에 미리 보기 패키지를 사용한 봇이 있으면 아래 단계를 수행하기 전에 제거해야 합니다.If a bot previously made use of the preview packages they must be removed before following the steps below.

  1. Visual Studio에서 봇 프로젝트를 엽니다.In Visual Studio, open your bot project.

  2. 프로젝트에서 Bot Framework SDK 버전 4.8을 사용하는지 확인합니다.Make sure the project uses version 4.8 or later of the Bot Framework SDK.

  3. 앱에서 명명된 파이프를 사용하도록 허용:Allow your app to use named pipes:

    • Startup.cs 파일을 엽니다.Open the Startup.cs file.
    • Configure메서드에서 메서드에 대한 호출을 UseNamedPipes 추가합니다.In the Configure method, add a call to the UseNamedPipes method.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseHsts();
        }
    
        app.UseDefaultFiles();
        app.UseStaticFiles();
    
        // Allow the bot to use named pipes.
        app.UseNamedPipes(System.Environment.GetEnvironmentVariable("APPSETTING_WEBSITE_SITE_NAME") + ".directline");
    
        app.UseMvc();
    }
    
  4. Startup.cs 파일을 저장합니다.Save the Startup.cs file.

  5. Azure 웹앱 봇 리소스에 봇을 게시하여 업데이트된 코드를 배포합니다.Publish the bot to your Azure web app bot resource to deploy the updated code.

봇 Direct Line App Service 확장 사용Enable bot Direct Line App Service extension

  1. Azure Portal 웹앱 봇 리소스를 찾습니다.In the Azure portal, locate your Web App Bot resource.

  2. 관리 아래의 왼쪽 패널 메뉴에서 채널을 클릭하여 봇이 메시지를 수락하는 Azure Bot Service 채널을 구성합니다.From the left panel menu under Bot management click on Channels to configure the Azure Bot Service channels your bot accepts messages from.

  3. 아직 사용하도록 설정되지 않은 경우 Direct Line 채널을 클릭하고 지침에 따라 채널을 사용하도록 설정합니다.If it is not already enabled, click on the Direct Line channel and follow instructions to enable the channel.

  4. 채널에 연결 테이블에서 직접 줄 행에 있는 편집 링크를 클릭 합니다.In the Connect to channels table click on the Edit link on the Direct Line row.

  5. App Service 확장 키 섹션까지 아래로 스크롤합니다.Scroll down to the App Service extension Keys section.

  6. 표시 링크를 클릭 하 여 키 중 하나를 표시 합니다.Click on the Show link to reveal one of the keys. 나중에 사용 하기 위해이 값을 복사 합니다.Copy this value for use later.

    App Service 확장 키

  7. 홈 페이지로 이동 하 고 페이지 맨 위에 있는 App Services 아이콘을 클릭 합니다.Navigate to the home page, click the App Services icon at the top of the page. 포털 메뉴를 표시 한 다음 왼쪽 패널에서 App Services 메뉴 항목을 클릭할 수도 있습니다.You can also display the portal menu, and then click the App Services menu item, in the left panel. App Services 페이지가 표시 됩니다.The App Services page is displayed.

  8. 검색 상자에 웹 앱 봇 리소스 이름을 입력 합니다.In the search box enter your Web App Bot resource name. 리소스가 나열 됩니다.Your resource will be listed. 아이콘 또는 메뉴 항목 위로 마우스를 가져가면 마지막으로 본 리소스 목록이 표시 됩니다.Notice that if you hover over the icon or the menu item, you get the list of the last resources you viewed. 웹 앱 봇 리소스가 나열 될 가능성이 있습니다.Chances are your Web App Bot resource will be listed.

  9. 리소스 링크를 클릭 합니다.Click your resource link.

  10. 설정 섹션에서 구성 메뉴 항목을 클릭 합니다.In the Settings section, click the Configuration menu item.

  11. 오른쪽 패널에 다음과 같은 새 설정을 추가 합니다.In the right panel, add the following new settings:

    이름Name Value
    DirectLineExtensionKeyDirectLineExtensionKey 이전에 복사한 App Service 확장 키의 값입니다.The value of the App Service extension key you copied earlier.
    DIRECTLINE_EXTENSION_VERSIONDIRECTLINE_EXTENSION_VERSION 최신latest
  12. 봇이 소 버린 또는 제한 된 Azure 클라우드에서 호스트 되는 경우 공용 포털을 통해 azure에 액세스 하지 않는 경우 다음과 같은 새 설정도 추가 해야 합니다.If your bot is hosted in a sovereign or otherwise restricted Azure cloud, where you don't access Azure via the public portal, you will also need to add the following new setting:

    이름Name Value
    DirectLineExtensionABSEndpointDirectLineExtensionABSEndpoint 사용자의 봇에서 호스트 되는 Azure 클라우드의 끝점입니다.The endpoint specific to the Azure cloud your bot is hosted in. 예를 들어 미국 정부 클라우드의 경우 끝점은 https://directline.botframework.azure.us/v3/extension 입니다.For the USGov cloud for example, the endpoint is https://directline.botframework.azure.us/v3/extension.
  13. 구성 섹션 내에서 일반 설정 섹션을 클릭 하 고 웹 소켓 을 설정 합니다.Still within the Configuration section, click on the General settings section and turn on Web sockets.

  14. 저장 을 클릭하여 설정을 저장합니다.Click on Save to save the settings. 그러면 Azure App Service가 다시 시작됩니다.This restarts the Azure App Service.

확장 및 봇이 구성되었는지 확인합니다.Confirm the extension and the bot are configured

브라우저에서 https://<your_app_service>.azurewebsites.net/.bot로 이동합니다.In your browser, navigate to https://<your_app_service>.azurewebsites.net/.bot. 모든 것이 올바르면 JSON 콘텐츠 {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}가 반환됩니다.If everything is correct, the page will return this JSON content: {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}. 이는 모든 것이 올바르게 작동할 때 얻을 수 있는 정보입니다. 여기서,This is the information you obtain when everything works correctly, where

  • v는 Direct Line App Service 확장의 빌드 버전을 표시합니다.v displays the build version of the Direct Line App Service extension.
  • k는 확장이 해당 구성에서 확장 키를 읽을 수 있는지 여부를 결정합니다.k determines whether the extension can read an extension key from its configuration.
  • initialized는 확장 키가 확장 키를 사용하여 Azure Bot Service 봇 메타데이터를 다운로드할 수 있는지 여부를 결정합니다.initialized determines whether the extension can use the extension key to download the bot metadata from Azure Bot Service.
  • ib는 확장이 봇과의 인바운드 연결을 설정할 수 있는지 여부를 결정합니다.ib determines whether the extension can establish an inbound connection with the bot.
  • ob은 확장이 봇과 아웃바운드 연결을 설정할 수 있는지 여부를 결정합니다.ob determines whether the extension can establish an outbound connection with the bot.

문제 해결Troubleshooting

  • .bot 엔드포인트에서 표시하는 ibob 값이 false이면 봇과 Direct Line App Service 확장이 서로 연결할 수 없음을 의미합니다.If the ib and ob values displayed by the .bot endpoint are false this means the bot and the Direct Line App Service extension are unable to connect to each other.

    1. 명명된 파이프를 사용하는 코드가 봇에 추가되었는지 다시 확인합니다.Double check the code for using named pipes has been added to the bot.
    2. 봇을 시작하고 실행할 수 있는지 확인합니다.Confirm the bot is able to start up and run at all. 유용한 도구는 WebChat에서 테스트, 추가 채널 연결, 원격 디버깅 또는 로깅입니다.Useful tools are Test in WebChat, connecting an additional channel, remote debugging, or logging.
    3. 봇이 호스트되는 전체 Azure App Service 다시 시작하여 모든 프로세스를 완전히 시작합니다.Restart the entire Azure App Service the bot is hosted within, to ensure a clean start up of all processes.
  • "HTTP 오류 500.34 - ANCM 혼합 호스팅"이 수신되면 봇이 호스팅 모델을 사용하려고 InProcess 합니다.If you receive an "HTTP Error 500.34 - ANCM Mixed Hosting", your bot is attempting to use the InProcess Hosting Model. 이 문제는 봇을 대신 실행하도록 명시적으로 설정하여 OutOfProcess 해결됩니다.This is remedied by explicitly setting the bot to run OutOfProcess instead. 자세한 내용은 AZP.NET Core 설명서의 Out of Process 호스팅 모델을 참조하세요.See Out-of-process hosting model in the AZP.NET Core documentation for more information.

  • .bot 엔드포인트의 초기화된 값이 false이면 Direct Line App Service 확장이 위의 봇의 애플리케이션 설정에 추가된 App Service 확장 키의 유효성을 검사할 수 없음을 의미합니다.If the initialized value of the .bot endpoint is false it means the Direct Line App Service extension is unable to validate the App Service extension key added to the bot's Application Settings above.

    1. 값이 올바르게 입력되었는지 확인합니다.Confirm the value was correctly entered.
    2. 봇의 Direct Line 구성 페이지에 표시된 대체 확장 키로 전환합니다.Switch to the alternate extension key shown on your bot's Configure Direct Line page.
  • Direct Line App Service 확장과 함께 OAuth를 사용하려고 하고 "대상 클레임에서 봇 AppId를 가져올 수 없습니다." 오류가 발생하는 경우If you attempt to use OAuth with the Direct Line App Service extension and encounter the error "Unable to get the bot AppId from the audience claim." ClaimsIdentity할당된 가 있는 을 AudienceClaim 에 설정해야 BotFrameworkHttpAdapter 합니다.A ClaimsIdentity with the AudienceClaim assigned needs to be set on the BotFrameworkHttpAdapter. 이를 위해 개발자는 아래 예제와 비슷한 방식으로 어댑터를 서브 클래스 할 수 있습니다.In order to accomplish this a developer may subclass the adapter similar to the example below:

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

다음 단계Next steps