확장을 위한 .NET 봇 구성

아티클
10/24/2023

2023년 9월 1일부터 네트워크 격리를 위해 Azure 서비스 태그 방법을 사용하는 것이 좋습니다. DL-ASE의 사용률은 매우 구체적인 시나리오로 제한되어야 합니다. 프로덕션 환경에서 이 솔루션을 구현하기 전에 지원 팀에 지침을 문의하는 것이 좋습니다.

적용 대상: SDK v4

이 문서에서는 명명된 파이프를 사용하도록 .NET 봇을 업데이트하는 방법과 봇을 배포한 Azure 앱 Service 리소스에서 Direct Line App Service 확장을 사용하도록 설정하는 방법을 설명합니다.

필수 조건

Azure 계정. 아직 계정이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
Azure에 배포된 .NET 봇입니다.
.NET용 Bot Framework SDK, 4.14.1 이상.

직접 회선 App Service 확장 사용

이 섹션에서는 봇의 직접 회선 채널 구성에서 App Service 확장 키를 사용하여 Direct Line App Service 확장을 사용하도록 설정하는 방법을 설명합니다.

봇 코드 업데이트

참고 항목

Microsoft.Bot.Builder.StreamingExtensions NuGet 미리 보기 패키지는 더 이상 사용되지 않습니다. v4.8부터 SDK에는 네임스페이 Microsoft.Bot.Builder.Streaming 스가 포함됩니다. 봇이 이전에 미리 보기 패키지를 사용한 경우 아래 단계를 따르기 전에 제거해야 합니다.

Visual Studio에서 봇 프로젝트를 엽니다.

앱에서 명명된 파이프를 사용하도록 허용합니다.

Startup.cs 파일을 엽니다.
Microsoft.Bot.Builder.Integration.AspNet.Core NuGet 패키지에 대한 참조를 추가합니다.
```
using Microsoft.Bot.Builder.Integration.AspNet.Core;
```

메서드에서 Configure 메서드에 대한 호출을 추가합니다 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();
}

Startup.cs 파일을 저장합니다.

업데이트된 봇을 Azure에 배포합니다.

봇 Direct Line App Service 확장 사용

Azure Portal에서 Azure Bot 리소스로 이동합니다.
1. 설정 아래에서 채널을 선택하여 봇이 메시지를 수락하는 채널을 구성합니다.
2. 아직 사용하도록 설정되지 않은 경우 사용 가능한 채널 목록에서 직접 회선 채널을 선택하여 채널을 사용하도록 설정합니다.
3. 직접 회선을 사용하도록 설정한 후 채널 페이지에서 다시 선택합니다.
4. App Service 확장 탭을 선택합니다.
5. App Service 확장 키에서 해당 키 옆에 있는 눈 아이콘을 선택합니다.
홈 페이지로 이동하여 페이지 맨 위에 있는 App Services를 선택합니다. 또는 포털 메뉴를 표시한 다음 App Services 메뉴 항목을 선택합니다. Azure에서 App Services 페이지를 표시합니다 .
검색 상자에 Azure Bot 리소스 이름을 입력합니다. 리소스가 나열됩니다.

아이콘이나 메뉴 항목을 마우스로 가리키면 마지막으로 본 리소스 목록이 표시됩니다. Azure Bot 리소스가 나열될 가능성이 높습니다.

리소스 링크를 선택합니다.

설정 섹션에서 구성 메뉴 항목을 선택합니다.
오른쪽 패널에서 다음 설정을 추가합니다.

속성 값

DirectLineExtensionKey 이전에 복사한 App Service 확장 키의 값입니다.

DIRECTLINE_EXTENSION_VERSION latest

속성	값
DirectLineExtensionKey	이전에 복사한 App Service 확장 키의 값입니다.
DIRECTLINE_EXTENSION_VERSION	latest

퍼블릭 포털을 통해 Azure에 액세스하지 않는 소버린 또는 기타 제한된 Azure 클라우드에서 봇이 호스트되는 경우 다음 설정도 추가해야 합니다.

속성	값
DirectLineExtensionABSEndpoint	봇이 호스트되는 Azure 클라우드와 관련된 엔드포인트입니다. 예를 들어 USGov 클라우드의 경우 엔드포인트는 .입니다 `https://directline.botframework.azure.us/v3/extension`.

구성 섹션 내에서 일반 설정 섹션을 선택하고 웹 소켓을 켭니다.
저장을 선택하여 설정을 저장합니다. 그러면 Azure 앱 서비스가 다시 시작됩니다.

직접 회선 확장 및 봇이 구성되었는지 확인

브라우저에서 https://<your_app_service>.azurewebsites.net/.bot으로 이동합니다. 모든 것이 올바르면 페이지에서 다음 JSON 콘텐츠를 반환합니다.

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

v 는 Direct Line App Service 확장의 빌드 버전을 보여줍니다.
k 는 확장이 해당 구성에서 확장 키를 읽을 수 있는지 여부를 나타냅니다.
initialized 는 확장이 Azure AI Bot Service에서 봇 메타데이터를 다운로드할 수 있는지 여부를 나타냅니다.
ib 는 확장이 봇에 대한 인바운드 연결을 설정할 수 있는지 여부를 나타냅니다.
ob 은 확장이 봇에서 아웃바운드 연결을 설정할 수 있는지 여부를 나타냅니다.

문제 해결

.bot 엔드포인트에서 표시하는 ib 및 ob 값이 false이면 봇과 Direct Line App Service 확장이 서로 연결할 수 없습니다.
1. 명명된 파이프를 사용하는 코드가 봇에 추가된 검사 두 번 추가되었습니다.
2. 봇이 시작하고 실행할 수 있는지 확인합니다. 유용한 도구는 WebChat에서 테스트, 추가 채널 연결, 원격 디버깅 또는 로깅입니다.
3. 봇이 호스팅되는 전체 Azure 앱 서비스를 다시 시작하여 클린 모든 프로세스를 시작하도록 합니다.
.bot 엔드포인트의 초기화된 값이 false이면 Direct Line App Service 확장에서 위의 봇 애플리케이션 설정 추가된 App Service 확장 키의 유효성을 검사할 수 없습니다.
1. 값이 올바르게 입력되었는지 확인합니다.
2. 봇의 직접 회선 구성 페이지에 표시된 대체 확장 키로 전환합니다.

봇이 Out of process 호스팅 모델을 사용하도록 설정합니다. 그렇지 않으면 HTTP 오류 500.34 - ANCM 혼합 호스팅 오류가 표시됩니다(여기서 ANCM은 ASP.NET 핵심 모듈을 의미합니다). 이 오류는 봇 템플릿이 기본적으로 호스팅 모델을 사용하고 InProcess 있기 때문에 발생합니다. Out of process 호스팅을 구성하려면 Out-of-process 호스팅 모델을 참조하세요. 자세한 내용은 aspNetCore 요소 의 특성 및 web.config를 사용한 구성을 참조하세요.

Direct Line App Service 확장과 함께 OAuth를 사용하려고 하고 "대상 그룹 클레임에서 봇 AppId를 가져올 수 없습니다"라는 오류가 발생하면 로 BotFrameworkHttpAdapter설정합니다 ClaimsIdentityAudienceClaim. 이렇게 하려면 어댑터를 서브클래스할 수 있습니다. 예시:

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

다음 단계

Direct Line App Service 확장과 함께 웹 채팅 사용