Azure SignalR Service 사용

아티클
12/12/2024

이 문서에서는 앱 서버에서 SignalR을 사용할 때 앱 서버 쪽에서 SDK를 사용하여 SignalR Service에 연결하는 방법을 보여 줍니다.

Important

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다.

연결 문자열에는 애플리케이션이 Azure Web PubSub 서비스에 액세스하는 데 필요한 권한 부여 정보가 포함됩니다. 연결 문자열 내의 액세스 키는 서비스의 루트 암호와 비슷합니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 Microsoft Entra ID를 사용하여 연결 문자열 보호합니다.

액세스 키를 다른 사용자에게 배포하거나 하드 코딩하거나 다른 사용자가 액세스할 수 있는 일반 텍스트로 저장하지 않도록 합니다. 키가 손상되었다고 생각되면 키를 교체하세요.

Azure SignalR Service 인스턴스 만들기

빠른 시작: ARM 템플릿을 사용하여 Azure SignalR 배포에 따라 SignalR 서비스 인스턴스를 만듭니다.

ASP.NET Core SignalR의 경우

SDK 설치

명령을 실행하여 ASP.NET Core 프로젝트에 SignalR Service SDK를 설치합니다.

dotnet add package Microsoft.Azure.SignalR

Startup 클래스에서 SignalR Service SDK를 다음 코드 조각으로 사용합니다.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR()
            .AddAzureSignalR();
}

public void Configure(IApplicationBuilder app)
{
    app.UseEndpoints(routes =>
    {
        routes.MapHub<YourHubClass>("/path_for_your_hub");
    });
}

연결 문자열 구성

원시 연결 문자열 데모용으로만 이 문서에 표시됩니다. 프로덕션 환경에서는 항상 액세스 키를 보호합니다. Azure Key Vault를 사용하여 키를 안전하게 관리 및 회전하고 Microsoft Entra ID를 사용하여 연결 문자열 보호합니다.

애플리케이션에서 SignalR Service의 연결 문자열을 구성하는 방법에는 두 가지가 있습니다.

이름이 Azure:SignalR:ConnectionString 또는 Azure__SignalR__ConnectionString인 환경 변수를 설정합니다.
- Azure App Service의 애플리케이션 설정에 적용합니다.

연결 문자열을 AddAzureSignalR()의 매개 변수로 전달합니다.

services.AddSignalR()
        .AddAzureSignalR("<replace with your connection string>");

또는

services.AddSignalR()
        .AddAzureSignalR(options => options.ConnectionString = "<replace with your connection string>");

옵션 구성

Azure SignalR Service SDK를 사용할 때 사용자 지정할 수 있는 몇 가지 옵션이 있습니다.

`ConnectionString`

기본값은 Azure:SignalR:ConnectionString connectionString 파일 또는 appSetting 파일입니다 web.config .
다시 구성할 수 있지만 값이 하드 코딩되지 않았는지 확인합니다.

`InitialHubServerConnectionCount`

기본값은 5여야 합니다.
이 옵션은 애플리케이션 서버와 Azure SignalR Service 간의 허브당 초기 연결 수를 제어합니다. 일반적으로 기본값으로 충분하므로 유지합니다. 런타임 중에 SDK는 성능 튜닝 또는 부하 분산을 위해 새 서버 연결을 시작할 수 있습니다. 클라이언트 수가 많은 경우 더 나은 처리량을 위해 더 많은 수를 제공할 수 있습니다. 예를 들어, 총 100,000개의 클라이언트가 있는 경우 연결 수를 10 또는 15로 늘릴 수 있습니다.

`MaxHubServerConnectionCount`

기본값은 null여야 합니다.
이 옵션은 애플리케이션 서버와 Azure SignalR Service 간의 허브당 허용되는 최대 연결 수를 제어합니다. 런타임 중에 SDK는 성능 튜닝 또는 부하 분산을 위해 새 서버 연결을 시작할 수 있습니다. 기본적으로 필요할 때마다 새 서버 연결이 시작됩니다. 허용되는 최대 서버 연결 수가 구성되면 SDK는 서버 연결 수가 한도에 도달해도 새 연결을 시작하지 않습니다.

`ApplicationName`

기본값은 null여야 합니다.
이 옵션은 동일한 허브 이름을 포함하는 여러 앱 서버에 대해 동일한 Azure SignalR 인스턴스를 공유하려는 경우 유용할 수 있습니다. 설정하지 않을 경우 연결된 모든 앱 서버는 동일한 애플리케이션의 인스턴스로 간주됩니다.

`ClaimsProvider`

기본값은 null여야 합니다.
이 옵션은 클라이언트 연결과 연결하려는 클레임을 제어합니다. 서비스 SDK가 클라이언트의 협상 요청에서 클라이언트에 대한 액세스 토큰을 생성할 때 사용됩니다. 기본적으로 협상된 요청의 HttpContext.User에서 발생한 모든 클레임은 예약되어 있습니다. Hub.Context.User에서 액세스할 수 있습니다.
일반적으로 이 옵션은 그대로 두어야 합니다. 사용자 지정하기 전에 어떤 일이 발생하는지 이해했는지 확인합니다.

`AccessTokenLifetime`

기본값은 1 hour여야 합니다.
이 옵션은 서비스 SDK가 각 클라이언트에 대해 생성하는 액세스 토큰의 유효한 수명을 제어합니다. 클라이언트의 협상 요청에 대한 응답으로 액세스 토큰이 반환됩니다.
ServerSentEvent 또는 LongPolling이 전송으로 사용되는 경우 만료된 시간 이후 인증 실패로 인해 클라이언트 연결이 닫힙니다. 클라이언트 연결 끊김을 방지하려면 이 값을 늘릴 수 있습니다.

`AccessTokenAlgorithm`

기본값은 HS256
이 옵션은 액세스 토큰을 생성할 때 SecurityAlgorithms를 선택할 수 있도록 합니다. 이제 지원되는 선택적 값은 HS256 및 HS512입니다. HS512는 더 안전하지만 생성된 토큰은 HS256을 사용하는 것보다 비교적 깁니다.

`ServerStickyMode`

기본값은 Disabled여야 합니다.
이 옵션은 서버 고정 모드를 지정합니다. 클라이언트가 처음 협상한 서버로 라우팅되면 이를 서버 고정이라고 합니다.
분산 시나리오에서는 하나의 Azure SignalR 인스턴스에 여러 앱 서버가 연결될 수 있습니다. 클라이언트 연결 내부에 설명된 대로 클라이언트는 먼저 앱 서버와 협상한 다음 Azure SignalR로 리디렉션하여 영구 연결을 설정합니다. 그러면 Azure SignalR은 클라이언트와 서버 간 데이터 전송에 설명된 대로 클라이언트에 서비스를 제공할 하나의 앱 서버를 찾습니다.
- Disabled인 경우 클라이언트는 임의의 앱 서버로 라우팅됩니다. 일반적으로 앱 서버는 이 모드를 사용하여 클라이언트 연결의 균형을 유지합니다. 시나리오가 브로드캐스트 또는 그룹 전송인 경우 이 기본 옵션을 사용하면 충분합니다.
- Preferred인 경우 Azure SignalR은 다른 비용이나 글로벌 라우팅이 필요하지 않은 방식으로 클라이언트가 처음 협상하는 앱 서버를 찾으려고 합니다. 이는 시나리오가 연결*로 전송될 때 유용할 수 있습니다. 연결로 보내기는 보낸 사람과 수신자가 동일한 앱 서버로 라우팅될 때 성능이 향상되고 대기 시간이 단축될 수 있습니다.
- Required인 경우 Azure SignalR은 항상 클라이언트가 처음 협상하는 앱 서버를 찾으려고 시도합니다. 이 옵션은 일부 클라이언트 컨텍스트를 negotiate 단계에서 가져와 메모리에 저장한 다음 Hub 내부에서 사용할 때 유용할 수 있습니다. 그러나 이 옵션은 Azure SignalR이 이 특정 앱 서버를 전역적으로 찾고 클라이언트와 서버 간에 전역적으로 라우팅 트래픽을 유지하기 위해 다른 활동을 기울여야 하기 때문에 성능상의 단점이 있을 수 있습니다.

`GracefulShutdown`

`GracefulShutdown.Mode`

기본값은 Off
이 옵션은 앱 서버가 SIGINT(CTRL + C)를 수신한 후의 동작을 지정합니다.
WaitForClientsClose로 설정하면 서버를 즉시 중지하는 대신 Azure SignalR Service에서 서버를 제거하여 새 클라이언트 연결이 이 서버에 할당되지 않도록 합니다.
또한 MigrateClients로 설정하면 클라이언트 연결을 다른 유효한 서버로 마이그레이션하려고 시도합니다. 마이그레이션은 메시지가 배달된 후에만 실행됩니다.
- OnConnected 및 OnDisconnected는 연결이 내부/외부로 마이그레이션될 때 트리거됩니다.
- IConnectionMigrationFeature는 연결이 내부/외부로 마이그레이션되었는지 식별하는 데 도움이 될 수 있습니다.
- 자세한 사용법은 샘플 코드를 참조하세요.

`GracefulShutdown.Timeout`

기본값은 30 seconds
이 옵션은 클라이언트가 닫히거나 마이그레이션될 때까지 기다리는 가장 긴 시간을 지정합니다.

`ServiceScaleTimeout`

기본값은 5 minutes
이 옵션은 온라인 클라이언트에 최소한 영향을 미치는 동적 조정 서비스 엔드포인트를 기다리는 가장 긴 시간을 지정합니다. 일반적으로 단일 앱 서버와 서비스 엔드포인트 간의 동적 크기 조정은 몇 초 안에 완료될 수 있지만, 네트워크 지터가 있는 여러 앱 서버와 서비스 엔드포인트가 있고 클라이언트 안정성을 보장하려는 경우 이에 따라 이 값을 구성할 수 있습니다.

`MaxPollIntervalInSeconds`

기본값은 5
이 옵션은 Azure SignalR Service에서 LongPolling 연결에 허용되는 최대 폴링 간격을 정의합니다. 다음 폴링 요청이 MaxPollIntervalInSeconds 내에 들어오지 않으면 Azure SignalR Service는 클라이언트 연결을 정리합니다.
값은 [1, 300]으로 제한됩니다.

`TransportTypeDetector`

기본값: 모든 전송이 사용하도록 설정됩니다.
이 옵션은 클라이언트가 HTTP 요청을 보내는 데 사용할 수 있는 전송을 사용자 지정하는 함수를 정의합니다.
전송을 구성하려면 HttpConnectionDispatcherOptions.Transports 대신 이 옵션을 사용합니다.

`AllowStatefulReconnects`

기본값은 null
이 옵션은 모든 허브에 대해 상태 저장 다시 연결할 수 있도록 설정하거나 사용하지 않도록 설정합니다.
이 경우 nullSDK는 허브 설정을 읽습니다.
이 경우 trueAzure SignalR Service는 선언된 모든 허브에서 상태 저장 다시 연결할 수 있습니다. 또한 클라이언트는 클라이언트 쪽에서 상태 저장 다시 연결할 수 있도록 설정해야 합니다.
이 경우 falseAzure SignalR Service는 선언된 모든 허브에서 상태 저장 다시 연결이 비활성화됩니다.

Sample

위의 옵션을 다음 샘플 코드와 같이 구성할 수 있습니다.

services.AddSignalR()
        .AddAzureSignalR(options =>
            {
                options.InitialHubServerConnectionCount = 10;
                options.AccessTokenLifetime = TimeSpan.FromDays(1);
                options.ClaimsProvider = context => context.User.Claims;

                options.GracefulShutdown.Mode = GracefulShutdownMode.WaitForClientsClose;
                options.GracefulShutdown.Timeout = TimeSpan.FromSeconds(10);
                options.TransportTypeDetector = httpContext => AspNetCore.Http.Connections.HttpTransportType.WebSockets | AspNetCore.Http.Connections.HttpTransportType.LongPolling;
            });

레거시 ASP.NET SignalR의 경우

참고 항목

SignalR을 처음 사용하는 경우 ASP.NET Core SignalR을 사용하는 것이 좋습니다. 더 간단하고 안정적이며 사용하기 쉽습니다.

SDK 설치

패키지 관리자 콘솔을 사용하여 ASP.NET 프로젝트에 SignalR Service SDK를 설치합니다.

Install-Package Microsoft.Azure.SignalR.AspNet

Startup 클래스에서 SignalR Service SDK를 다음 코드 조각으로 사용하고 MapSignalR()을 MapAzureSignalR({your_applicationName})으로 바꿉니다. {YourApplicationName}을 애플리케이션 이름으로 바꿉니다. 이는 이 애플리케이션을 다른 애플리케이션과 구분하기 위한 고유한 이름입니다. this.GetType().FullName을 값으로 사용할 수 있습니다.

public void Configuration(IAppBuilder app)
{
    app.MapAzureSignalR(this.GetType().FullName);
}

연결 문자열 구성

web.config 파일의 연결 문자열을 connectionStrings 섹션으로 설정합니다.

<configuration>
    <connectionStrings>
        <add name="Azure:SignalR:ConnectionString" connectionString="Endpoint=...;AccessKey=..."/>
    </connectionStrings>
    ...
</configuration>

옵션 구성

Azure SignalR Service SDK를 사용할 때 사용자 지정할 수 있는 몇 가지 옵션이 있습니다.

`ConnectionString`

기본값은 Azure:SignalR:ConnectionString connectionString 파일 또는 appSetting 파일입니다 web.config .
다시 구성할 수 있지만 값이 하드 코딩되지 않았는지 확인합니다.

`InitialHubServerConnectionCount`

기본값은 5여야 합니다.
이 옵션은 애플리케이션 서버와 Azure SignalR Service 간의 허브당 초기 연결 수를 제어합니다. 일반적으로 기본값으로 충분하므로 유지합니다. 런타임 중에 SDK는 성능 튜닝 또는 부하 분산을 위해 새 서버 연결을 시작할 수 있습니다. 클라이언트 수가 많은 경우 더 나은 처리량을 위해 더 많은 수를 제공할 수 있습니다. 예를 들어, 총 100,000개의 클라이언트가 있는 경우 연결 수를 10 또는 15로 늘릴 수 있습니다.

`MaxHubServerConnectionCount`

기본값은 null여야 합니다.
이 옵션은 애플리케이션 서버와 Azure SignalR Service 간의 허브당 허용되는 최대 연결 수를 제어합니다. 런타임 중에 SDK는 성능 튜닝 또는 부하 분산을 위해 새 서버 연결을 시작할 수 있습니다. 기본적으로 필요할 때마다 새 서버 연결이 시작됩니다. 허용되는 최대 서버 연결 수가 구성되면 SDK는 서버 연결 수가 한도에 도달해도 새 연결을 시작하지 않습니다.

`ApplicationName`

기본값은 null여야 합니다.
이 옵션은 동일한 허브 이름을 포함하는 여러 앱 서버에 대해 동일한 Azure SignalR 인스턴스를 공유하려는 경우 유용할 수 있습니다. 설정하지 않을 경우 연결된 모든 앱 서버는 동일한 애플리케이션의 인스턴스로 간주됩니다.

`ClaimProvider`

기본값은 null여야 합니다.
이 옵션은 클라이언트 연결과 연결하려는 클레임을 제어합니다. 서비스 SDK가 클라이언트의 협상 요청에서 클라이언트에 대한 액세스 토큰을 생성할 때 사용됩니다. 기본적으로 협상된 요청의 IOwinContext.Authentication.User에서 발생한 모든 클레임은 예약되어 있습니다.
일반적으로 이 옵션은 그대로 두어야 합니다. 사용자 지정하기 전에 어떤 일이 발생하는지 이해했는지 확인합니다.

`AccessTokenLifetime`

기본값은 1 hour여야 합니다.
이 옵션은 서비스 SDK가 각 클라이언트에 대해 생성하는 액세스 토큰의 유효한 수명을 제어합니다. 클라이언트의 협상 요청에 대한 응답으로 액세스 토큰이 반환됩니다.
ServerSentEvent 또는 LongPolling이 전송으로 사용되는 경우 만료된 시간 이후 인증 실패로 인해 클라이언트 연결이 닫힙니다. 클라이언트 연결 끊김을 방지하려면 이 값을 늘릴 수 있습니다.

`AccessTokenAlgorithm`

기본값은 HS256
이 옵션은 액세스 토큰을 생성할 때 SecurityAlgorithms를 선택할 수 있도록 합니다. 이제 지원되는 선택적 값은 HS256 및 HS512입니다. HS512는 더 안전하지만 생성된 토큰은 HS256을 사용하는 것보다 비교적 깁니다.

`ServerStickyMode`

기본값은 Disabled여야 합니다.
이 옵션은 서버 고정 모드를 지정합니다. 클라이언트가 처음 협상한 서버로 라우팅되면 이를 서버 고정이라고 합니다.
분산 시나리오에서는 하나의 Azure SignalR 인스턴스에 여러 앱 서버가 연결될 수 있습니다. 클라이언트 연결 내부에 설명된 대로 클라이언트는 먼저 앱 서버와 협상한 다음 Azure SignalR로 리디렉션하여 영구 연결을 설정합니다. 그러면 Azure SignalR은 클라이언트와 서버 간 데이터 전송에 설명된 대로 클라이언트에 서비스를 제공할 하나의 앱 서버를 찾습니다.
- Disabled인 경우 클라이언트는 임의의 앱 서버로 라우팅됩니다. 일반적으로 앱 서버는 이 모드를 사용하여 클라이언트 연결의 균형을 유지합니다. 시나리오가 브로드캐스트 또는 그룹 전송인 경우 이 기본 옵션을 사용하면 충분합니다.
- Preferred인 경우 Azure SignalR은 다른 비용이나 글로벌 라우팅이 필요하지 않은 방식으로 클라이언트가 처음 협상하는 앱 서버를 찾으려고 합니다. 이는 시나리오가 연결*로 전송될 때 유용할 수 있습니다. 연결로 보내기는 보낸 사람과 수신자가 동일한 앱 서버로 라우팅될 때 성능이 향상되고 대기 시간이 단축될 수 있습니다.
- Required인 경우 Azure SignalR은 항상 클라이언트가 처음 협상하는 앱 서버를 찾으려고 시도합니다. 이 옵션은 일부 클라이언트 컨텍스트를 negotiate 단계에서 가져와 메모리에 저장한 다음 Hub 내부에서 사용할 때 유용할 수 있습니다. 그러나 이 옵션은 Azure SignalR이 이 특정 앱 서버를 전역적으로 찾고 클라이언트와 서버 간에 전역적으로 라우팅 트래픽을 유지하기 위해 다른 활동을 기울여야 하기 때문에 성능상의 단점이 있을 수 있습니다.

`MaxPollIntervalInSeconds`

기본값은 5
이 옵션은 Azure SignalR Service의 비활성 연결에 허용되는 최대 유휴 시간을 정의합니다. ASP.NET SignalR에서는 긴 폴링 전송 형식 또는 재연결에 적용됩니다. 다음 /reconnect 또는 /poll 요청이 MaxPollIntervalInSeconds 내에 들어오지 않으면 Azure SignalR Service는 클라이언트 연결을 정리합니다.
값은 [1, 300]으로 제한됩니다.

예제

위의 옵션을 다음 샘플 코드와 같이 구성할 수 있습니다.

app.Map("/signalr",subApp => subApp.RunAzureSignalR(this.GetType().FullName, new HubConfiguration(), options =>
{
    options.InitialHubServerConnectionCount = 1;
    options.AccessTokenLifetime = TimeSpan.FromDays(1);
    options.ClaimProvider = context => context.Authentication?.User.Claims;
}));

애플리케이션 서버 스케일 아웃

Azure SignalR Service를 사용하면 애플리케이션 서버에서 영구 연결이 오프로드되므로 허브 클래스에서 비즈니스 논리를 구현하는 데 집중할 수 있습니다. 하지만 대규모 클라이언트 연결을 처리할 때 더 나은 성능을 얻으려면 여전히 애플리케이션 서버를 스케일 아웃해야 합니다. 다음은 애플리케이션 서버 크기 조정에 대한 몇 가지 팁입니다.

여러 애플리케이션 서버가 동일한 Azure SignalR Service 인스턴스에 연결할 수 있습니다.
동일한 허브 이름을 포함하는 여러 애플리케이션에 대해 동일한 Azure SignalR 인스턴스를 공유하려면 다른 ApplicationName 옵션을 사용하여 설정합니다. 설정하지 않을 경우 연결된 모든 앱 서버는 동일한 애플리케이션의 인스턴스로 간주됩니다.
ApplicationName 옵션과 허브 클래스의 이름이 동일하면 서로 다른 애플리케이션 서버의 연결은 동일한 허브에 그룹화됩니다.
각 클라이언트 연결은 애플리케이션 서버 중 하나에서만 만들어지며 해당 클라이언트의 메시지는 동일한 애플리케이션 서버로만 전송됩니다. 전역적으로 클라이언트 정보에 액세스하려면(모든 애플리케이션 서버에서) 중앙 집중식 스토리지를 사용하여 모든 애플리케이션 서버의 클라이언트 정보를 저장해야 합니다.

다음 단계

이 문서에서는 애플리케이션에서 SignalR Service를 사용하는 방법을 알아봅니다. SignalR Service에 대해 자세히 알아보려면 다음 문서를 확인합니다.

Azure SignalR Service 내부 기능

빠른 시작: SignalR Service를 사용하여 채팅방 만들기

다음을 통해 공유

Azure SignalR Service 사용

Azure SignalR Service 인스턴스 만들기

ASP.NET Core SignalR의 경우

SDK 설치

연결 문자열 구성

옵션 구성

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimsProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

GracefulShutdown

GracefulShutdown.Mode

GracefulShutdown.Timeout

ServiceScaleTimeout

MaxPollIntervalInSeconds

TransportTypeDetector

AllowStatefulReconnects

Sample

레거시 ASP.NET SignalR의 경우

SDK 설치

연결 문자열 구성

옵션 구성

ConnectionString

InitialHubServerConnectionCount

MaxHubServerConnectionCount

ApplicationName

ClaimProvider

AccessTokenLifetime

AccessTokenAlgorithm

ServerStickyMode

MaxPollIntervalInSeconds

예제

애플리케이션 서버 스케일 아웃

다음 단계

피드백

추가 리소스

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimsProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`GracefulShutdown`

`GracefulShutdown.Mode`

`GracefulShutdown.Timeout`

`ServiceScaleTimeout`

`MaxPollIntervalInSeconds`

`TransportTypeDetector`

`AllowStatefulReconnects`

`ConnectionString`

`InitialHubServerConnectionCount`

`MaxHubServerConnectionCount`

`ApplicationName`

`ClaimProvider`

`AccessTokenLifetime`

`AccessTokenAlgorithm`

`ServerStickyMode`

`MaxPollIntervalInSeconds`