.NET용 Azure Web PubSub 클라이언트 라이브러리

비고

여기서 사용되는 용어에 대한 자세한 내용은 주요 개념 문서에 설명 되어 있습니다 .

클라이언트 쪽 SDK는 개발자의 워크플로 속도를 향상하는 것을 목표로 합니다. 보다 구체적으로,

  • 클라이언트 연결 관리를 간소화합니다.
  • 클라이언트 간에 메시지 보내기 간소화
  • 의도하지 않은 클라이언트 연결 삭제 후 자동으로 다시 시도
  • 연결 끊기에서 복구한 후 메시지를 수와 순서대로 신뢰성 있게 배달합니다.

다이어그램에 표시된 것처럼 클라이언트는 Web PubSub 리소스와 WebSocket 연결을 설정합니다. Web PubSub 리소스를 사용하여 WebSocket 연결을 설정하는 클라이언트를 보여 주는 스크린샷

시작하기

패키지 설치

NuGet에서 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

필수 조건

  • Azure 구독
  • 기존 Web PubSub 인스턴스

클라이언트 인증

클라이언트는 Client Access URL를 사용하여 서비스에 연결하고 인증합니다. Client Access URL 은 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> 패턴을 따릅니다. Client Access URL을(를) 얻는 방법에는 여러 가지가 있습니다. 빠른 시작으로 Azure Portal에서 복사하여 붙여넣을 수 있으며 프로덕션의 경우 일반적으로 생성 Client Access URL할 협상 서버가 필요합니다. 세부 정보를 참조하세요.

Azure Portal에서 클라이언트 액세스 URL 사용

빠른 시작으로 Azure Portal로 이동하여 키 블레이드에서 클라이언트 액세스 URL을 복사할 수 있습니다.

Azure Portal에서 클라이언트 액세스 URL을 가져오는 방법을 보여 주는 스크린샷

다이어그램에 표시된 것처럼 클라이언트에는 특정 그룹에 메시지를 보내고 특정 그룹에 조인할 수 있는 권한이 부여됩니다. 클라이언트 권한에 대한 자세한 내용은 사용 권한을 참조하세요.

var client = new WebPubSubClient(new Uri("<client-access-uri>"));

협상 서버를 사용하여 생성 Client Access URL

운영 환경에서 클라이언트는 일반적으로 협상 서버에서 Client Access URL을 가져옵니다. 서버가 connection string를 보유하고 WebPubSubServiceClient를 통해 Client Access URL을 생성합니다. 샘플로 코드 조각은 단일 프로세스 내에서 Client Access URL를 생성하는 방법을 보여 줍니다.

var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
{
    // In common practice, you will have a negotiation server for generating token. Client should fetch token from it.
    return FetchClientAccessTokenFromServerAsync(token);
}));

public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
{
    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
    return await serviceClient.GetClientAccessUriAsync();
}

차별화할 WebPubSubClient 및 WebPubSubServiceClient 기능

클래스 이름 WebPubSubClient WebPubSubServiceClient
NuGet 패키지 이름 Azure.Messaging.WebPubSub.Client Azure.Messaging.WebPubSub
기능 클라이언트 쪽에서 사용됩니다. 메시지를 게시하고 메시지를 구독합니다. 서버 쪽에서 사용됩니다. 클라이언트 액세스 URI 생성 및 클라이언트 관리

예시

서버 및 그룹에서 메시지 수신

클라이언트는 콜백을 추가하여 서버 및 그룹의 메시지를 사용할 수 있습니다. 클라이언트는 조인된 그룹 메시지만 받을 수 있습니다.

client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.GroupMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

connected, disconnected, 및 stopped 이벤트에 대한 콜백 추가

클라이언트 연결이 서비스에 연결되면 서비스에서 connected 연결된 메시지를 받으면 이벤트가 트리거됩니다.

client.Connected += eventArgs =>
{
    Console.WriteLine($"Connection {eventArgs.ConnectionId} is connected");
    return Task.CompletedTask;
};

클라이언트 연결이 끊어지고 복구 disconnected 에 실패하면 이벤트가 트리거됩니다.

client.Disconnected += eventArgs =>
{
    Console.WriteLine($"Connection is disconnected");
    return Task.CompletedTask;
};

클라이언트가 중지되면 클라이언트 연결이 끊어지고 클라이언트가 다시 연결 stopped 하려고 중지하면 이벤트가 트리거됩니다. 일반적으로 client.StopAsync()가 호출된 후, 또는 AutoReconnect가 비활성화된 후에 발생합니다. 클라이언트를 다시 시작하려면 Stopped 이벤트에서 client.StartAsync()를 호출할 수 있습니다.

client.Stopped += eventArgs =>
{
    Console.WriteLine($"Client is stopped");
    return Task.CompletedTask;
};

자동 그룹 재가입 및 재가입 실패 시 처리

클라이언트 연결이 끊어지고 복구에 실패하면 모든 그룹 컨텍스트가 서비스 쪽에서 정리됩니다. 즉, 클라이언트가 다시 연결되면 그룹에 다시 가입해야 합니다. 기본적으로 클라이언트는 옵션을 사용하도록 설정했습니다 AutoRejoinGroups . 그러나 이 기능에는 제한이 있습니다. 클라이언트는 원래 클라이언트에 의해 조인된 그룹만 다시 조인할 수 있으며, 서버 측에서 조인된 그룹은 다시 조인할 수 없습니다. 또한 여러 가지 이유로 인해 그룹 다시 조인 작업이 실패할 수 있습니다. 예를 들어 클라이언트에는 그룹에 조인할 수 있는 권한이 없습니다. 이러한 경우 사용자는 이러한 오류를 처리하기 위해 콜백을 추가해야 합니다.

client.RejoinGroupFailed += eventArgs =>
{
    Console.WriteLine($"Restore group failed");
    return Task.CompletedTask;
};

작업 및 다시 시도

기본적으로 client.JoinGroupAsync(), client.LeaveGroupAsync(), client.SendToGroupAsync(), client.SendEventAsync() 같은 작업에는 세 번의 재시도가 있습니다. WebPubSubClientOptions.MessageRetryOptions을(를) 사용하여 변경할 수 있습니다. 모든 재시도에 실패하면 오류가 발생합니다. 이전 재시도와 동일하게 ackId 전달하여 재시도를 계속할 수 있으므로 서비스는 동일한 ackId작업을 중복 제거하도록 도울 수 있습니다.

// Send message to group "testGroup"
try
{
    await client.JoinGroupAsync("testGroup");
}
catch (SendMessageFailedException ex)
{
    if (ex.AckId != null)
    {
        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
    }
}

문제 해결

로그 활성화

다음 환경 변수를 설정하여 이 라이브러리를 사용할 때 디버그 로그를 가져올 수 있습니다.

export AZURE_LOG_LEVEL=verbose

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서를 참조하세요.

라이브 추적

Azure Portal의 라이브 추적 도구를 사용하여 Web PubSub 리소스를 통해 라이브 메시지 트래픽을 검사합니다.

  • Last updated on